Workspace workflows

The architecture becomes useful through repeated practice. These workflows are intentionally lightweight: each one leaves behind enough evidence for the next person or agent to continue.

Starting a project

1. Create a bounded project area.
2. Write the short project brief before building a large note hierarchy.
3. Add technical or production setup to the README.
4. Record the immediate work in the task list.
5. Create the decision log when the first consequential choice is made.
6. Initialize or connect the delivery repository at the appropriate boundary.

The initial structure should describe the project you have, not the organization you imagine it might need later.

Research and notes

1. Preserve source material and provenance.
2. Separate external claims from personal observations and generated hypotheses.
3. Classify the material under the project that owns it.
4. Distil findings into reader-facing or operational documentation.
5. Link the distilled result back to its supporting evidence when useful.

This keeps raw research available without forcing every future session to read it.

Agent handoffs

1. Confirm the working tree and active branch.
2. Run proportionate verification.
3. Record unfinished work in the task list.
4. Capture durable decisions separately from the session narrative.
5. Create or update a landmark when the investigation exposed non-obvious implementation context.
6. Reference exact files, commits, issues, pull requests, and relevant landmarks.
7. Summarize only the context the next session cannot recover cheaply.

A handoff is successful when the next agent can act, not when it perfectly recounts the conversation.

The next session should begin through the bootstrap path, following links into deeper context only when the task needs it.

Decisions and history

Record a decision when its reasoning will matter after the current task. Include the context, chosen direction, reasoning, and consequences. Do not use a decision log as a chronological diary.

Session history serves a different purpose: it preserves what happened during a meaningful block of work. Tasks describe what remains. Git records the file-level implementation. Keeping those responsibilities distinct makes each source easier to trust.

The feedback loop

Orient → Investigate → Change → Verify → Record → Hand off
   ↑                                                ↓
   └────────────── the next session begins ─────────┘

Every loop should leave the workspace slightly easier to understand than it was before.