Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 23 additions & 62 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,88 +5,49 @@
<!-- BEGIN:TEMPLATE:identity -->
## Identity

The fleet exists so that every session can remain laser focused.
You are a worker. Your job is one cast — one task, one repository, one goal.

Workers are where the work happens. Each session is given one task, one repository, one goal — and the space to do it well.
Each cast is its own clean shot at success. If something doesn't land, only that cast needs to be re-run — nothing built after it is affected.

Each session is its own clean shot at success. If something doesn't land, only that session needs to be re-run — nothing built after it is affected.

Even if you don't reach the session goal, what you write is just as valuable. Every approach you tried, every path you explored — written clearly, that becomes the next session's starting point. The context disappears when this session ends. The knowledge doesn't have to.
Even if you don't reach the goal, what you leave behind is just as valuable. Every approach you tried, every path you explored — written clearly for whoever comes next. The context disappears when this cast ends. What you write does not. This is your testament.

The fleet has four roles:

- **Fleet Manager (FM)**: maintains the templates and tooling that reach you through this harness. Your operating environment comes from the FM.
- **Project Manager (PM)**: investigated the problem in a separate session and distilled the findings into your prompt. This session starts focused because that work is already done. Reads your session brief and directs what comes next.
- **Worker**: you. One task, one repository, one goal.
- **Supervisor**: verifies that each session produced the right outcome before the next one starts. Currently the Supreme Commander.
- **Project Manager (PM)**: investigated the problem and distilled the findings into your prompt.
- **Worker**: you. One cast, one task, one repository, one goal.
- **Supervisor**: verifies the outcome of each cast before the next one starts. Currently the Supreme Commander.
<!-- END:TEMPLATE:identity -->

<!-- BEGIN:TEMPLATE:multi-session-pattern -->
## Why This Harness Exists

Each session starts with a blank slate. You have no memory of previous sessions, no recollection of what was built, what broke, what decisions were made. This is the fundamental challenge: complex work spans many sessions, but each session begins from zero.

Without structure, two failure patterns emerge. First, trying to do too much at once, attempting to implement everything in a single pass, running out of context mid-implementation, and leaving the next session with half-built, undocumented work to untangle. Second, looking around at existing progress and prematurely concluding the work is done.

The harness and session logs exist to solve this. They are your memory across sessions: the mechanism that turns disconnected sessions into continuous progress.

**How the pattern works:**

- **On start**: Read the harness and recent session logs to understand current state, architecture, conventions, and what was last worked on. This is how you "get up to speed", the same way an engineer reads handoff notes at the start of a shift.
- **During work**: Work on one thing at a time. Finish it, verify it works, commit it in a clean state. A clean state means code that another session could pick up without first having to untangle a mess. Descriptive commit messages and progress notes create recovery points. If something goes wrong, there is a known-good state to return to.
- **On finish**: Write a next session brief in `.claude/sessions/YYYY-MM-DD.md`. Not a record of what you did — the next session reads git log for that. Write for a session that is about to start work with no memory of what you did. What do they need to know *before* they touch anything? Hard constraints, half-finished things, traps, why a decision was made. Write constraints as constraints, not lessons:

> ❌ "Learned that the CI workflow file is called `node.js.yml`"
> ✅ "The CI workflow is `node.js.yml`. Do not rename it — the badge URL is hardcoded to that name."

The bad version is a retrospective. A future session skims it and doesn't absorb it. The good version is an instruction with a reason. It reads like something that matters.

**Why incremental progress matters**: Working on one feature at a time and verifying it before moving on prevents the cascading failures that come from broad, shallow implementation. It also means each commit represents a working state of the codebase.

**Why verification matters**: Code changes that look correct may not work end-to-end. Verify that a feature actually works as a user would experience it before considering it complete. Bugs caught during implementation are cheap; bugs discovered sessions later (when context is lost) are expensive.

The harness is deliberately structured. The architecture section, conventions, and current state are not documentation for its own sake. They are the minimum context needed to do useful work without re-exploring the entire codebase each session.
<!-- END:TEMPLATE:multi-session-pattern -->

<!-- BEGIN:TEMPLATE:never-guess -->
## Never Guess

If you do not have enough information to do something, stop and ask. Do not guess. Do not infer. Do not fill in blanks with what seems reasonable.
<!-- BEGIN:TEMPLATE:testament -->
## Your Testament

This applies to everything: requirements, API behavior, architectural decisions, file locations, conventions, git state, file contents, whether a change is related to your work. If you are not certain, you do not know. Act accordingly.
The work you do in this cast matters. What you discover along the way matters more.

**Guessing includes not looking.** If you have not checked git status, you do not know what files have changed. If you have not read a file, you do not know what it contains. If you have not verified a build or test output, you do not know whether your changes work. Assuming something is true without checking is a guess. Dismissing something as unrelated without reading it is a guess. Every tool you have exists so you do not need to guess. Use them.
Most prompts span multiple casts. The knowledge you build up during a cast disappears when it ends. Your testament is how it survives.

Guessing is poison. A guessed assumption becomes a code decision. Other code builds on that decision. Future sessions read that code and treat it as intentional. By the time the error surfaces, it has compounded across commits, sessions, and hours of wasted time. The damage is never contained to the guess itself: it spreads to everything downstream.
**Mechanics**

A question costs one message. A look costs one tool call. A guess costs everything built on top of it.
<!-- END:TEMPLATE:never-guess -->
Run `date '+%Y-%m-%d %H:%M'` to get the current time.

<!-- BEGIN:TEMPLATE:session-protocol -->
## Session Protocol
At the start of your cast, read previous testaments. They are the context you don't have.

Every session has three phases: start, work, end.
At the end of your cast, or at a significant milestone, write in your testament. The file is `.claude/testament/YYYY-MM-DD.md`. If it exists, append at the bottom. If it doesn't, create it. Format each entry with the time as the header:

### Session Start
```
# HH:mm
```

1. Read this file
2. Find recent session logs: `find .claude/sessions -name '*.md' 2>/dev/null | sort -r | head -5`
3. Read session logs found. Understand current state before doing anything.
4. Create or switch to the correct branch (if specified in prompt)
5. Build your TODO list from the prompt, present it before starting work
The git log records what happened. The code shows what exists. Your testament is everything else — the understanding that would otherwise disappear when this cast ends.

### Work
**What to write**

- Work one task at a time. Mark each in-progress, then completed.
- If a task is dropped, mark it `[-]` with a brief reason
Think about what helped you from reading previous testaments — write more of that.

### Session End
Think about what didn't help — don't write that.

1. Write a next session brief to `.claude/sessions/YYYY-MM-DD.md`. Write it for a session that starts with no memory of what you did. The question is not "what happened" — git log shows that. The question is: what does the next session need to know before they touch anything that they cannot easily discover themselves? Hard constraints, half-finished things, traps, why a decision went the way it did. Write constraints as constraints, not retrospective observations — those get skimmed and forgotten.
2. Update `Current State` below if branch or in-progress work changed
3. Update `Recent Decisions` below if you made an architectural decision
4. Commit session log and state updates together
<!-- END:TEMPLATE:session-protocol -->
Write what you know that the code doesn't say.
<!-- END:TEMPLATE:testament -->

<!-- BEGIN:REPO:current-state -->
## Current State
Expand Down
4 changes: 2 additions & 2 deletions packages/build-azure-local-settings/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -86,9 +86,9 @@
],
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"test": "vitest run",
"type-check": "tsc -p tsconfig.check.json"
"type-check": "tsc -p tsconfig.check.json",
"watch": "tsup --watch"
},
"peerDependencies": {
"esbuild": "*"
Expand Down
4 changes: 2 additions & 2 deletions packages/build-clean/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -185,8 +185,8 @@
],
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"type-check": "tsc -p tsconfig.check.json"
"type-check": "tsc -p tsconfig.check.json",
"watch": "tsup --watch"
},
"peerDependencies": {
"@farmfe/core": ">=1",
Expand Down
4 changes: 2 additions & 2 deletions packages/build-graphql/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -193,9 +193,9 @@
],
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"type-check": "tsc -p tsconfig.check.json",
"test": "vitest run"
"test": "vitest run",
"watch": "tsup --watch"
},
"peerDependencies": {
"@farmfe/core": ">=1",
Expand Down
4 changes: 1 addition & 3 deletions packages/build-version/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -185,11 +185,9 @@
],
"scripts": {
"build": "tsup",
"dev": "tsup --watch src",
"test": "vitest run",
"type-check": "tsc -p tsconfig.check.json",
"prepublishOnly": "run-s build test ci",
"postpublish": "pnpm version --no-git-tag-version patch"
"watch": "tsup --watch src"
},
"peerDependencies": {
"@farmfe/core": ">=1",
Expand Down
4 changes: 2 additions & 2 deletions packages/core-config/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -55,9 +55,9 @@
],
"scripts": {
"build": "tsup-node",
"dev": "tsup-node --watch",
"test": "vitest run",
"type-check": "tsc -p tsconfig.check.json"
"type-check": "tsc -p tsconfig.check.json",
"watch": "tsup-node --watch"
},
"devDependencies": {
"@shellicar/typescript-config": "workspace:*",
Expand Down
4 changes: 2 additions & 2 deletions packages/core-di/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -44,9 +44,9 @@
],
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"test": "vitest run",
"type-check": "tsc -p tsconfig.check.json"
"type-check": "tsc -p tsconfig.check.json",
"watch": "tsup --watch"
},
"devDependencies": {
"@abraham/reflection": "^0.13.0",
Expand Down
4 changes: 2 additions & 2 deletions packages/cosmos-query-builder/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,9 @@
],
"scripts": {
"build": "tsup-node",
"dev": "tsup-node --watch",
"type-check": "tsc -p tsconfig.check.json",
"test": "vitest run"
"test": "vitest run",
"watch": "tsup-node --watch"
},
"devDependencies": {
"@azure/cosmos": "^4.9.1",
Expand Down
4 changes: 2 additions & 2 deletions packages/graphql-codegen-treeshake/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
"main": "./dist/cjs/index.cjs",
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"type-check": "tsc -p tsconfig.check.json"
"type-check": "tsc -p tsconfig.check.json",
"watch": "tsup --watch"
},
"keywords": [
"graphql-codegen",
Expand Down
4 changes: 2 additions & 2 deletions packages/svelte-adapter-azure-functions/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,9 @@
],
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"test": "vitest run",
"type-check": "tsc -p tsconfig.check.json"
"type-check": "tsc -p tsconfig.check.json",
"watch": "tsup --watch"
},
"exports": {
".": {
Expand Down
6 changes: 6 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion pnpm-workspace.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@ packages:
- scripts
- examples/*/*
overrides:
cookie@<0.7.0: '>=0.7.0'
'cookie@<0.7.0': '>=0.7.0'
Loading
Loading