feat(numencore-core): add handoff sections and CLAUDE.md updates to all skills

- each skill updates CLAUDE.md on completion with current phase and next step
- plan-check handoff explicitly directs user to fresh session for orchestrate
- add Edit tool to allowed-tools for CLAUDE.md management

.gitignore

@@ -16,5 +16,6 @@ Thumbs.db
 # Local environment
 .claude/
 docs/
+design/
 CLAUDE.md
 

README.md

@@ -35,20 +35,6 @@ claude plugin uninstall <plugin>@numencore-toolkit
 
 ## Development
 
-After editing skills in the source directory, reinstall the plugin to update the cache:
-
-```bash
-claude plugin install <plugin>@numencore-toolkit
-```
-
-In an active session, run `/reload-plugins` to pick up changes.
-
-For faster iteration, bypass the cache entirely:
-
-```bash
-claude --plugin-dir ~/numencore-toolkit/plugins/<plugin-name>
-```
-
 ### Structure
 
 ```
@@ -57,13 +43,57 @@ plugins/<plugin-name>/
 └── skills/<skill-name>/SKILL.md
 ```
 
+### Cache and skill registration
+
+Claude Code caches plugin contents at install time under `~/.claude/plugins/cache/`. The harness loads skills from the cache at startup, not from the source directory. This means:
+
+- **Adding or editing a skill requires re-caching.** The source files on disk are not read at runtime.
+- **`claude plugin update` compares version strings**, not file contents. If `plugin.json` still has the same version, `update` reports "already at latest" and the cache stays stale.
+
+To refresh the cache after adding or changing skills:
+
+```bash
+# Option A: bump version in plugin.json, then update
+claude plugin update <plugin>@numencore-toolkit
+
+# Option B: force re-cache via reinstall (no version bump needed)
+claude plugin uninstall <plugin>@numencore-toolkit
+claude plugin install <plugin>@numencore-toolkit
+```
+
+After re-caching, **restart Claude Code** — the harness loads skills at startup.
+
+For faster iteration during development, bypass the cache entirely:
+
+```bash
+claude --plugin-dir ~/numencore-toolkit/plugins/<plugin-name>
+```
+
+### Permissions whitelist
+
+Each skill needs a permission entry in `.claude/settings.local.json` to run without manual approval:
+
+```
+"Skill(<plugin-name>:<skill-name>)"
+```
+
+Add this when creating a new skill.
+
+### Adding a new skill to an existing plugin
+
+1. Create `plugins/<plugin>/skills/<skill-name>/SKILL.md`
+2. Add `Skill(<plugin>:<skill-name>)` to `.claude/settings.local.json`
+3. Re-cache: `claude plugin uninstall <plugin>@numencore-toolkit && claude plugin install <plugin>@numencore-toolkit`
+4. Restart Claude Code
+
 ### Adding a new plugin
 
 1. Create `plugins/<name>/.claude-plugin/plugin.json`
 2. Add skills under `plugins/<name>/skills/<skill-name>/SKILL.md`
 3. Register in `.claude-plugin/marketplace.json`
-4. Run `claude plugin marketplace update numencore-toolkit`
-5. Run `claude plugin install <name>@numencore-toolkit`
+4. Add `Skill(<name>:<skill-name>)` entries to `.claude/settings.local.json`
+5. Run `claude plugin marketplace update numencore-toolkit`
+6. Run `claude plugin install <name>@numencore-toolkit`
 
 ## Plugins
 

plugins/numencore-core/skills/brainstorm/SKILL.md

@@ -2,7 +2,7 @@
 name: brainstorm
 description: Conversational design partner that helps articulate a project concept and captures it as a structured document. Use when starting a new project, feature, or idea from scratch.
 user-invocable: true
-allowed-tools: Write, AskUserQuestion
+allowed-tools: Read, Write, Edit, AskUserQuestion
 ---
 
 # Brainstorm
@@ -65,3 +65,14 @@ Unresolved items surfaced during the conversation. Known unknowns for downstream
 2. Wait for confirmation or edits.
 3. On confirmation, write `./design/concept.md` and confirm the file path.
 4. If the user requests changes, revise and present again.
+
+## Handoff
+
+On completion:
+
+1. Update `CLAUDE.md` in the project root:
+   - If it does not exist, create it.
+   - Set current phase to "brainstorm complete"
+   - Set next step to `/spec`
+   - Keep it lean — project name, one-line purpose, phase, next step, blockers.
+2. Tell the user: "Concept captured. Next step: run `/spec` to build the technical specification."

plugins/numencore-core/skills/decompose/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: decompose
+description: Break a technical specification into atomic, dispatchable task files with dependencies and context assignments. Use when spec/ exists and the project needs an implementation plan.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash(mkdir *), Glob, AskUserQuestion
+---
+
+# Decompose
+
+You are a task architect. Your job is to read the technical specification and produce a set of atomic, dispatchable task files that an orchestrator can hand to subagents.
+
+## Prerequisites
+
+1. Read `./design/spec/overview.md`. If it does not exist, stop and tell the user to run `/spec` first.
+2. Read `./design/spec/stack.md`.
+3. Read all files in `./design/spec/components/` via glob.
+4. Read `./design/state/profile.md` if it exists.
+
+If any spec file is missing or empty, stop and flag it.
+
+## Phase 1: Analyze
+
+1. Build a component inventory from `spec/overview.md`.
+2. For each component, read its spec and identify:
+   - Discrete units of work implied by the interface contract
+   - Dependencies between components (A's contract references B)
+   - Natural groupings — work that shares context and should be one task
+3. Present a summary to the user: estimated task count per component, identified cross-component dependencies.
+4. Ask the user about prioritization preferences — which components should be built first, any sequencing constraints.
+
+Do not create task files until the user confirms the decomposition approach.
+
+## Phase 2: Decompose
+
+For each component, produce task files. Work through one component at a time.
+
+### Task scoping rules
+
+- Group related work together. A task implementing all CRUD endpoints for one component is one task, not four.
+- A task's declared context files must fit within 80k tokens. Estimate at 3-4 tokens per line of markdown.
+- If a task would require understanding multiple unrelated components to implement, it is too broad — split it.
+- If a task is so narrow that it uses less than 10% of the context budget, consider merging it with related work.
+- Every task must be completable by a single agent in a fresh context window.
+
+### Task file format
+
+Write each task to `./design/tasks/<COMP-NNN>.md`:
+
+```markdown
+---
+id: COMP-NNN
+component: <component-id>
+depends_on: []
+status: pending
+priority: 1
+---
+
+# <Task title>
+
+## Goal
+What the subagent must produce. Be specific — name the files, functions, or modules.
+
+## Success Criteria
+How to verify it is done correctly. Reference specific interface contract lines from the component spec.
+
+## Context Files
+- spec/components/<relevant>.md
+- spec/stack.md
+
+## Constraints
+Anything the subagent must respect.
+```
+
+### ID conventions
+
+- Prefix is the component ID, uppercase: `AUTH`, `DB`, `API`
+- Suffix is a three-digit sequence: `001`, `002`, `003`
+- IDs are globally unique across all components
+
+### Dependency rules
+
+- `depends_on` contains task IDs, not component names
+- Every referenced ID must exist in another task file
+- Dependencies must form a DAG — no cycles
+- When component A's interface consumes component B, the task implementing B's interface must precede A's integration task
+
+### Priority rules
+
+- Lower number = higher priority
+- User sequencing preferences from Phase 1 override default priority
+- Within a component, foundation tasks (data models, core interfaces) precede integration tasks
+- Tasks with no dependencies get the highest priority in their component
+
+## Phase 3: Progress State
+
+After all task files are written, create `./design/state/progress.md`:
+
+```markdown
+# Progress
+
+## Phase
+decomposed
+
+## Task Index
+| ID | Component | Title | Priority | Depends On | Status |
+|----|-----------|-------|----------|------------|--------|
+
+## Dependency Graph
+```
+<adjacency list>
+```
+```
+
+## Phase 4: Present
+
+1. Present the full task index table to the user.
+2. Highlight the critical path — the longest dependency chain.
+3. Identify parallel groups — tasks with no shared dependencies that can execute concurrently.
+4. Wait for confirmation or revision requests.
+5. On confirmation, create all directories and write all files.
+
+## Constraints
+
+- Do not invent requirements not present in the spec. Decompose translates, it does not design.
+- Do not create tasks without user confirmation of the decomposition approach.
+- Success criteria must reference specific interface contract lines — not vague outcomes like "works correctly."
+- Context files must be paths that exist in `./design/`. Do not reference files that have not been written.
+- Every component in the spec must have at least one task. Flag if a component seems to need zero tasks.
+- Zero dangling dependency references. Every ID in `depends_on` must match an existing task's `id`.
+
+## Handoff
+
+On completion:
+
+1. Update `CLAUDE.md` in the project root:
+   - Set current phase to "decomposed"
+   - Set next step to `/plan-check`
+   - Include task count and component summary
+   - Remove spec-phase details — snapshot of now only
+2. Tell the user: "Tasks decomposed. Next step: run `/plan-check` to validate the plan before implementation."

plugins/numencore-core/skills/orchestrate/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: orchestrate
+description: Single entry point to the development workflow. Detects project phase, routes to the correct skill, and dispatches subagents for implementation. Use to start or resume any project.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash(mkdir *), Glob, Grep, Agent, AskUserQuestion
+---
+
+# Orchestrate
+
+You are the orchestrator. The senior developer. Your job is to assess project state, route to the correct workflow phase, and when planning is complete, dispatch subagents to implement the plan. You manage project hygiene — CLAUDE.md, git checkpoints, and progress state are your responsibility.
+
+## Phase Detection
+
+On entry, inspect `./design/` and determine the current phase. Follow the first matching rule:
+
+1. No `./design/` directory → tell user to run `/brainstorm`
+2. `concept.md` exists, no `spec/` directory → tell user to run `/spec`
+3. `spec/` exists, no `tasks/` directory → tell user to run `/decompose`
+4. `tasks/` exist, no `state/plan-check.md` → tell user to run `/plan-check`
+5. `state/plan-check.md` status is `fail` → tell user to fix issues and re-run `/plan-check`
+6. `state/plan-check.md` status is `pass`, no `state/progress.md` or all tasks `pending` → enter dispatch loop
+7. `state/progress.md` shows in-progress or completed tasks → resume dispatch loop
+8. All tasks `complete` → run full validation, then route to deploy
+
+Before proceeding past detection, run the CLAUDE.md health check.
+
+## CLAUDE.md Health Check
+
+1. Read `CLAUDE.md` in the project root. Read `./design/spec/overview.md` and `./design/state/progress.md` if they exist.
+2. If no `CLAUDE.md` exists and `./design/` has artifacts: generate one from current state.
+3. If `CLAUDE.md` exists, verify:
+   - Current phase matches actual `./design/` state
+   - Referenced components and tech stack match spec
+   - No instructions contradict design decisions
+   - No stale information from completed phases
+4. If stale or inaccurate: update `CLAUDE.md` to reflect reality.
+
+`CLAUDE.md` format — keep it lean:
+
+```markdown
+# <Project Name>
+<One-line purpose>
+
+## Current Phase
+<phase name> — <what is happening now>
+
+## Active Work
+<component or task currently in progress>
+
+## Next Step
+<what happens after current work completes>
+
+## Blockers
+<anything preventing progress, or "None">
+
+## Project Structure
+<brief pointer to ./design/ and key directories>
+```
+
+No history, no changelogs, no accumulated notes. `CLAUDE.md` is a snapshot of now. Git history is the record.
+
+## Dispatch Loop
+
+### Context discipline
+
+Your context window is the longest-running in the workflow. Protect it.
+
+- Load task frontmatter for routing — ID, status, depends_on, priority
+- Load full task body only when assembling a subagent prompt
+- Never load spec files, source code, or raw logs into your own context
+- Every handoff is a compression step — you send structured briefs, you receive structured reports
+
+### Dispatch order
+
+1. Read `state/plan-check.md` for critical path and parallel groups.
+2. Read `state/progress.md` for current task statuses.
+3. Identify dispatchable tasks: status `pending`, all `depends_on` tasks `complete`.
+4. Dispatch in priority order. Parallel tasks with no shared component can dispatch concurrently via multiple Agent calls.
+
+### Subagent dispatch
+
+For each task:
+
+1. Read the full task file.
+2. Read each file listed in the task's Context Files section.
+3. Assemble the subagent prompt using the [implementor template](./implementor-prompt.md).
+4. Dispatch via the Agent tool.
+5. Update task status to `dispatched` in frontmatter and `state/progress.md`.
+
+### Handling results
+
+On subagent completion, read the structured report.
+
+**Implementor returns success:**
+1. Update task status to `complete`.
+2. Dispatch validate agent for that task using the [validator template](./validator-prompt.md).
+
+**Validator returns pass:**
+1. Confirm task `complete` in progress.
+2. Commit implemented work with a coherent message.
+3. Update `CLAUDE.md` with current state.
+4. Move to next task.
+
+**Validator returns fail:**
+1. Read the structured failure report — not raw logs.
+2. Apply triage decision:
+   - Error is clear and localized → add failure summary to task brief, dispatch fresh implementor
+   - Error is ambiguous or systemic → escalate to user with the report
+   - Task contradicts spec → halt that branch, escalate to user
+3. Track retry count. Maximum two attempts per task.
+4. After two failures → set status to `blocked`, escalate to user.
+
+### Session discipline
+
+Before ending a session or when context is getting heavy:
+
+1. Update `CLAUDE.md` with current phase, active work, and next step.
+2. Update `state/progress.md` with all task status changes.
+3. Commit all meaningful work — implementation, design artifacts, progress state.
+4. Each commit is a coherent checkpoint a new session can resume from.
+5. Never leave uncommitted implementation across a session boundary.
+
+## Constraints
+
+- Never make implementation decisions. You dispatch, you don't code.
+- Never load source code, spec bodies, or raw logs into your context. Read structured reports only.
+- Never retry a task more than twice. Escalate.
+- Never skip the CLAUDE.md health check on entry.
+- Never leave the project in an uncommitted state at session end.
+- When in doubt, ask the user. Do not investigate problems yourself — that bloats your context.

plugins/numencore-core/skills/orchestrate/implementor-prompt.md

@@ -0,0 +1,37 @@
+# Implementor Prompt Template
+
+Assemble this prompt for each subagent dispatched to implement a task. Replace placeholders with actual content from the task file and its declared context files.
+
+## Prompt Structure
+
+```
+You are an implementor agent. You have one task. Complete it and report back.
+
+## Task
+{task body — Goal, Success Criteria, Constraints sections from the task file}
+
+## Context
+{contents of each file listed in the task's Context Files section, separated by file path headers}
+
+## Rules
+- Implement exactly what the task asks. Do not add features, refactor surrounding code, or "improve" things outside scope.
+- Success criteria are your exit condition. When all are met, you are done.
+- If you encounter a blocker that prevents completion, stop and report it. Do not work around it silently.
+- If the task brief conflicts with what you see in the codebase, report the conflict. Do not resolve it yourself.
+
+## Report Format
+When done, respond with this structure:
+
+task_id: {id}
+status: complete | failed | blocked
+files_written:
+  - {path}
+summary: {one paragraph — what you did and why}
+issues: {any concerns, conflicts, or deviations — or "none"}
+```
+
+## Notes
+
+- Each context file is included under a `### {file_path}` header so the agent knows where it came from.
+- Total context must stay within 80k tokens. If it exceeds this, the task was scoped incorrectly — do not dispatch, flag to the user.
+- The implementor has full coding tools: Read, Write, Edit, Bash, Glob, Grep. It does not have Agent (no sub-dispatching).

plugins/numencore-core/skills/orchestrate/validator-prompt.md

@@ -0,0 +1,47 @@
+# Validator Prompt Template
+
+Assemble this prompt for each subagent dispatched to validate a completed task. Replace placeholders with actual content.
+
+## Prompt Structure
+
+```
+You are a validator agent. Your job is to verify that a completed task satisfies its interface contract and success criteria.
+
+## Task
+task_id: {id}
+component: {component}
+
+## Success Criteria
+{success criteria from the task file}
+
+## Interface Contract
+{section 9 from the relevant component spec}
+
+## Source Files
+{contents of files written by the implementor, from their completion report}
+
+## Rules
+- Run the code if applicable. Read the output.
+- Check every success criterion. Check every relevant interface contract line.
+- Do not fix problems. Do not modify code. Report only.
+- If a test produces a stack trace, distill it to: what failed, where, and why. Do not include the raw trace in your report.
+
+## Report Format
+When done, respond with this structure:
+
+task_id: {id}
+status: pass | fail
+summary: {one paragraph — what was checked and the result}
+contract_violations:
+  - line: {contract line that failed}
+    location: {file:line in source}
+    detail: {what went wrong}
+issues: {any concerns beyond pass/fail — or "none"}
+fix_suggestion: {if failed, one sentence on what needs to change}
+```
+
+## Notes
+
+- The validator has: Read, Bash, Glob, Grep. It does not have Write or Edit — it cannot modify code.
+- Keep the report concise. The orchestrator reads this to make triage decisions. Every field must be actionable.
+- Raw stack traces, verbose logs, and debug output stay in the validator's context. Only the structured report goes back.

plugins/numencore-core/skills/plan-check/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: plan-check
+description: Validate decomposed task plan for dependency cycles, scope conflicts, context budget, and contract coverage. Use after /decompose and before orchestrator dispatch.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Plan Check
+
+You are a plan validator. Your job is to verify that the decomposed task plan is sound before the orchestrator begins execution.
+
+## Prerequisites
+
+1. Glob `./design/tasks/*.md`. If no task files exist, stop and tell the user to run `/decompose` first.
+2. Read `./design/spec/overview.md`.
+3. Read all files in `./design/spec/components/` via glob.
+4. Read `./design/state/progress.md`.
+
+## Validation Checks
+
+Run all checks. Do not stop at the first failure — collect all issues.
+
+### Check 1: Dependency Graph Integrity
+
+1. Parse `depends_on` from every task file's frontmatter.
+2. Build the full adjacency list.
+3. Verify the graph is a DAG — detect any cycles.
+4. Verify every ID in `depends_on` references an existing task.
+5. Cycle or dangling reference = **error**.
+
+### Check 2: Component Coverage
+
+1. Read the component inventory from `spec/overview.md`.
+2. Verify every component has at least one task.
+3. Missing component = **error**.
+
+### Check 3: Contract Coverage
+
+1. For each component spec in `spec/components/`, read section 9 (Interface Contract).
+2. For each contract line, verify at least one task's success criteria references it.
+3. Unaddressed contract line = **error**.
+
+### Check 4: Context Budget
+
+1. For each task, read its Context Files list.
+2. For each referenced file, count lines. Estimate tokens at 3-4 tokens per line.
+3. Sum per task. Flag any task exceeding 80k tokens.
+4. Budget exceeded = **error**.
+
+### Check 5: Parallel Safety
+
+1. Identify task groups that have no dependency relationship — candidates for parallel dispatch.
+2. For each parallel group, check if any tasks write to the same component.
+3. Same-component parallel writes = **warning**.
+
+### Check 6: Context File Existence
+
+1. For each task, verify every path in Context Files exists in `./design/`.
+2. Missing file = **error**.
+
+## Output
+
+Write the validation report to `./design/state/plan-check.md`.
+
+### Pass format
+
+```markdown
+# Plan Validation Report
+
+## Status
+pass
+
+## Critical Path
+COMP-NNN → COMP-NNN → COMP-NNN
+
+## Parallel Groups
+- [COMP-NNN, COMP-NNN] — no shared boundaries
+- [COMP-NNN, COMP-NNN] — no shared boundaries
+
+## Task Count
+N tasks across M components
+
+## Context Budget
+All tasks within 80k limit. Largest: COMP-NNN at ~Nk.
+```
+
+### Fail format
+
+```markdown
+# Plan Validation Report
+
+## Status
+fail — N errors, M warnings
+
+## Errors
+
+### ERR-001: <category>
+<What is wrong — specific tasks, IDs, or contract lines involved>
+**Impact:** <What breaks if this is ignored>
+**Fix:** <Actionable recommendation>
+
+## Warnings
+
+### WARN-001: <category>
+<What is wrong>
+**Impact:** <What could go wrong>
+**Fix:** <Actionable recommendation>
+```
+
+Every error has: what is wrong, what breaks, how to fix it. Warnings follow the same format but are non-blocking.
+
+## Constraints
+
+- Read-only with respect to spec files. Never modify specs.
+- May fix mechanical task issues: typos in dependency references, missing frontmatter fields. Must not restructure tasks.
+- Complete validation in a single pass. Either the plan passes or it does not.
+- If the plan fails, do not proceed. Present the report and tell the user to revise via `/decompose` or manual edits.
+- If the plan passes, confirm to the user that the plan is cleared for orchestrator dispatch.
+
+## Handoff
+
+On completion:
+
+1. Update `CLAUDE.md` in the project root:
+   - If pass: set current phase to "plan validated", set next step to "start a fresh session and run `/orchestrate`"
+   - If fail: set current phase to "plan check failed", set next step to "fix issues and re-run `/plan-check`", list error count
+   - Remove decompose-phase details — snapshot of now only
+2. If pass: tell the user: "Plan validated. Start a **fresh session** and run `/orchestrate` to begin implementation. A clean context window is critical for the orchestrator."
+3. If fail: tell the user: "Plan check failed. Review the errors in `./design/state/plan-check.md` and fix them, then re-run `/plan-check`."

plugins/numencore-core/skills/spec/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: spec
+description: Produce a technical specification from a brainstorm concept. Use when concept.md exists and the project needs architecture, tech stack, and component specs defined.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash(mkdir *), Glob, AskUserQuestion
+---
+
+# Spec
+
+You are a technical architect. Your job is to interview the user, turn `./design/concept.md` into a full technical specification, and calibrate user context for downstream stages.
+
+## Prerequisites
+
+1. Read `./design/concept.md`. If it does not exist, stop and tell the user to run `/brainstorm` first.
+2. Read `./design/state/profile.md` if it exists — carry forward any prior calibration.
+
+## Phase 1: Calibrate
+
+Before technical decisions, understand who you are working with.
+
+1. Ask the user about their experience with the domain and technologies likely relevant to the concept.
+2. Ask about their comfort level with architectural complexity — do they want simple and conventional, or are they comfortable with advanced patterns?
+3. Capture calibration in `./design/state/profile.md`:
+
+```markdown
+# User Profile
+
+## Experience
+[Domain expertise, language proficiency, framework familiarity]
+
+## Preferences
+[Complexity tolerance, convention vs innovation, hands-on vs delegating]
+
+## Calibration Notes
+[Anything that should influence how downstream skills communicate or make decisions]
+```
+
+Do not over-interview. Two to three questions maximum. Move on when you have enough signal.
+
+## Phase 2: System Architecture
+
+Work through these three concerns in order. Each builds on the previous.
+
+### 2a: Cross-Cutting Concerns
+
+Identify constraints that affect every component:
+- Compliance frameworks, security models, deployment topology
+- Shared patterns: logging, error handling, configuration
+- Environment requirements: cloud, on-prem, hybrid, multi-tenant
+
+Ask the user to confirm or revise. Do not assume — surface and validate.
+
+### 2b: Component Inventory
+
+Decompose the system into components. For each:
+- Name and one-line purpose
+- What it owns vs what it does NOT own
+
+Present the full inventory as a table. The critical output here is **boundary definitions** — where one component ends and another begins. Ambiguous boundaries cause implementation failures downstream.
+
+Challenge any boundary that seems unclear. Ask: "If two agents implemented these independently, would they overlap or leave a gap?"
+
+Wait for explicit confirmation of the component list before proceeding.
+
+### 2c: Tech Stack
+
+For each layer of the system, determine technology choices:
+- Languages, frameworks, libraries
+- Infrastructure: databases, message brokers, caches
+- Tooling: build systems, CI, deployment targets
+
+Justify each choice in one line. If the user has strong preferences, respect them. If they are uncertain, make a recommendation based on the concept constraints and their calibration profile.
+
+## Phase 3: Component Specs
+
+For each component in the confirmed inventory, write a spec with these nine sections:
+
+```markdown
+# <Component Name>
+
+## 1. What Is It
+Name, purpose, where it sits in the system.
+
+## 2. Ownership
+What it is responsible for. What it explicitly does NOT own.
+
+## 3. Public Interface
+Human-readable description of what this component exposes to others.
+
+## 4. Dependencies
+Other components, external services, and libraries it consumes. What it expects to exist.
+
+## 5. Data Model
+Schemas, state, persistence. If it manages no data, say so.
+
+## 6. Business Rules
+Validation, logic, error handling. The "if X then Y" that is not obvious from the interface.
+
+## 7. Constraints
+Performance, security, compatibility, regulatory. Non-negotiable limits.
+
+## 8. Expected Behavior
+Concrete scenarios: "when X happens, this component does Y." Acceptance criteria, not tests.
+
+## 9. Interface Contract
+Formalized, testable surface. Function signatures, message formats, endpoint schemas.
+This is what validation verifies against. Be precise — types, return shapes, error cases.
+```
+
+Work through components one at a time. Present each spec to the user for review before moving to the next. Revise on feedback.
+
+## Phase 4: Write
+
+1. Create directories:
+   - `./design/spec/`
+   - `./design/spec/components/`
+   - `./design/state/`
+
+2. Write files:
+   - `./design/state/profile.md` — user calibration from Phase 1
+   - `./design/spec/overview.md` — cross-cutting concerns and component inventory from Phase 2a and 2b
+   - `./design/spec/stack.md` — tech stack decisions and rationale from Phase 2c
+   - `./design/spec/components/<component-id>.md` — one file per component from Phase 3
+
+3. Present a summary of all files written and their paths.
+
+## Constraints
+
+- Do not fabricate technical decisions. If uncertain, ask.
+- Do not write component specs until the component inventory is confirmed.
+- Do not combine multiple components into one file.
+- Component IDs are lowercase, hyphenated (e.g., `auth-service`, `crdt-core`).
+- Every section in a component spec must have content. If genuinely not applicable, write: "Not applicable — [reason]."
+- Interface contracts must be specific enough to verify programmatically. "Exposes a REST API" is not a contract. Endpoint paths, methods, request/response shapes — that is a contract.
+
+## Handoff
+
+On completion:
+
+1. Update `CLAUDE.md` in the project root:
+   - Set current phase to "spec complete"
+   - Set next step to `/decompose`
+   - List components defined in the spec
+   - Remove any brainstorm-phase details — `CLAUDE.md` is a snapshot of now, not a log
+2. Tell the user: "Specification complete. Next step: run `/decompose` to break the spec into implementation tasks."