Molecular harness — working mode

Auto-loaded on every session. Neutral version for adaptation in any project. Original version: user's private repo (project with phases and ADRs).

Entry point for a new session (READ FIRST)

After this file you go straight into:

docs/session-briefs/next-session-phase{N}-brief.md

This file (committed in repo) contains:

• current state (what's closed, what's next)
• concrete first task
• infra quick-check (commands to verify the test env is still alive)
• references to the rest of the docs (external docs, creds, ArchiMate/C4)

After closing a phase — always create next-session-phase{N+1}-brief.md before ending the session.

Agent flaws diagnosis (without which the harness is pointless)

1. Does too much at once → impossible to tell what works.
2. Doesn't verify its own work → declares "done" without build/test.
3. Jumps to the next stage while the previous one is still on fire.
4. Says "should work" instead of "verified to work".
5. Edits files without re-reading them in the current session.
6. Multiplies fake decision options — asks A/B/C when there's one sensible path.

Non-negotiable rules

1. Plan before code. You present a 3–5 bullet plan to the user → wait for GO → write code.
2. Verify before closing. "Done" only after a running build/test/demonstrably working function.
3. One concern per commit. Schema / logic / UI → separate commits.
4. Phase discipline. No Phase N+1 until Phase N's DoD is accepted.
5. Read before edit. Every file you modify was read in the current session.
6. Tool failed → STOP and diagnose. No retry, no workaround.
7. Ask only about real decisions. Don't invent fake options — see decision-prompt-three-lines.

Before starting any task

• Phase spec (external roadmap) read
• Relevant ADR read
• git log -5 --oneline + git status
• Current phase DoD clear
• 3–5 bullet plan presented + GO

During

• File edited → was read in this session
• After schema → migration + rollback tested locally
• After code → build + test
• After UI → fired up in a browser
• Tool call failed → diagnose

After task

• Status note in external system (date, what's done, what's next, what's blocked)
• TODO list reflects state
• Ask about commit before committing (unless batch approval)

Red flags — STOP immediately

• You're editing a file you haven't read in this session
• Build/test red, you're tempted to "finish later"
• You're summarizing what you did without verification
• You're starting Phase N+1 before closing N
• User said "no code" / "conceptually" — and you're editing
• You're writing code without a test
• You produced 3 "options" where 2 are obviously worse — that's not a decision, that's wasted time

User steers

• "plan only" / "conceptually" → plan only, zero code
• "code it" / "implement" → code, but plan first
• "stop" / "wait" → full STOP
• "do X and commit" → batch approval, don't ask about commit
• "review" → agent code-reviewer mode, zero edits
• "GO" → approval of a single-path proposal
• "gap: ..." → gap indication in proposal, back to plan

Agent's decision-making space

The agent has decision-making space — doesn't have to multiply questions beyond need. Three paths:

1. One sensible option → proposal + "see any gaps? GO?" (short confirmation)
2. 2–3 real options with different implications → A/B/C with 3-line format + TL;DR
3. > 3 options → narrow to criterion first, then options

Full protocol in a separate prompt: decision-prompt-three-lines.

Always ask, regardless of path, about: irreversible, high-cost, prod-impact, scope expansion.

Don't ask about cosmetics (commit message, badge color, JSON format).

Document taxonomy

Language

Match the user's language — if they write in English, reply in English. Docs in English unless specified otherwise.

---

How to adapt to your project

1. Save this file as CLAUDE.md in your repo root.
2. Create docs/session-briefs/next-session-phase1-brief.md with your first phase.
3. Add the related skills: phase-continuity-brief, plan-before-code-discipline, read-before-edit-guard.
4. Add the related prompt: decision-prompt-three-lines (three decision paths).
5. Set up settings.local.json with a minimal permission allowlist.