@kiwidata/grimoire 0.1.1

package/skills/grimoire-discover/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: grimoire-discover
+description: Generate area docs and data schema from a codebase snapshot. Use when initializing grimoire on an existing project or when codebase structure has changed significantly.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-discover
+
+Generate a structured project map in `.grimoire/docs/` from a codebase snapshot. This map helps LLMs understand the codebase layout, find reusable code, and follow existing patterns — preventing duplicate code and misplaced files.
+
+## Triggers
+- User wants to document or map the codebase structure
+- User asks about coding standards, patterns, or conventions
+- User wants to prevent duplicate code or find existing utilities
+- Loose match: "discover", "map", "standards", "conventions", "DRY", "utilities", "codebase layout"
+
+## Routing
+- Want to document existing behavior as Gherkin features → `grimoire-audit`
+- Want to find undocumented features and decisions → `grimoire-audit` (run discover first, then audit)
+- Want to draft new functionality → `grimoire-draft`
+
+## Prerequisites
+
+**Structural snapshot:** Run `grimoire map` first. This produces `.grimoire/docs/.snapshot.json` — a structural scan of the directory tree, key files, and file extension counts. The snapshot is the input for directory structure; this skill adds the semantic layer.
+
+If `.snapshot.json` doesn't exist or is stale, tell the user to run `grimoire map` (or `grimoire map --refresh` to diff against existing docs).
+
+**Symbol intelligence (recommended):** If `codebase-memory-mcp` is available as an MCP server, use its graph tools (`search_graph`, `get_architecture`, `query_graph`) to query symbols, call graphs, and architecture instead of reading source files manually. This provides AST-parsed symbols across 66 languages, call-path tracing, and dead code detection — far more accurate than regex extraction.
+
+If `codebase-memory-mcp` is not available, fall back to reading source files directly to identify symbols and patterns.
+
+## What It Produces
+
+`.grimoire/docs/` with:
+- **`index.yml`** — master index of all documented areas with descriptions and directory mappings
+- **Area docs** — one markdown file per area of the codebase, each covering:
+  - Purpose and boundaries of the module/area
+  - Key files and their responsibilities
+  - Reusable utilities, helpers, and shared functions (the "reuse inventory")
+  - Naming conventions and patterns in use
+  - Where new code of this type should go
+  - Example references (point to specific files as exemplars, don't duplicate code)
+
+## Workflow
+
+### 1. Load Snapshot and Graph
+Read `.grimoire/docs/.snapshot.json`. This gives you:
+- **directories** — every directory with file counts, extensions, key files, and subdirectories
+- **keyFiles** — significant files (entry points, configs, route files, etc.) with their detected type
+- **undocumented** — directories not yet covered by existing docs (only present on `--refresh`)
+- **removed** — directories that have docs but no longer exist (only present on `--refresh`)
+
+Use this as your roadmap. The snapshot tells you WHERE to look; you add WHAT it means.
+
+If the snapshot includes a `duplicates` section (from `grimoire map --duplicates`), use it to populate "Known Duplicates" sections in area docs. This tells the plan skill where code is already duplicated so it can consolidate rather than add more.
+
+**If `codebase-memory-mcp` is available**, also query the graph for each area:
+- `search_graph` — find all symbols (functions, classes, types) in a directory
+- `trace_call_path` — understand how modules connect (inbound/outbound calls)
+- `get_architecture` — get a high-level module/dependency overview
+- `query_graph` — Cypher-like queries for specific relationships (e.g., `MATCH (f:Function)-[:CALLS]->(g) WHERE f.file STARTS WITH 'src/api/' RETURN f.name, g.name`)
+
+This replaces the need to manually read every source file to extract symbols. The graph gives you AST-accurate function signatures, call relationships, and dead code detection across 66 languages.
+
+### 2. Determine Scope
+Ask the user what to document:
+- **Full scan** — document all areas from the snapshot (default for first run)
+- **Area scan** — document specific directories (e.g., "just the API layer")
+- **Gap fill** — only document areas flagged as `undocumented` in the snapshot
+
+Check `.grimoire/docs/index.yml` if it exists — don't redo work unless refreshing.
+
+### 3. Analyze Each Area
+For each directory cluster in the snapshot, read the actual code to understand:
+
+**From the snapshot (already known):**
+- Directory path and file counts
+- File extensions (tells you the language/type mix)
+- Key files (tells you what framework patterns are in use)
+
+**From `codebase-memory-mcp` graph (if available):**
+- All symbols in the area: functions, classes, types, constants with signatures
+- Call graph: what calls what, both inbound and outbound
+- Dead code: functions with zero callers
+- Cross-service HTTP links: REST routes and their callers
+
+**From reading the code (your job — or to supplement the graph):**
+- What the module/area is responsible for
+- Reusable functions, classes, utilities that other code should import
+- Naming conventions and structural patterns
+- Where new code of this type should be created
+- Import relationships with other areas
+- **Data models and schemas** in or owned by this area (see Data Layer below)
+
+### 4. Generate Area Docs
+For each significant area, create a doc file in `.grimoire/docs/`.
+
+**Area doc format:**
+
+```markdown
+# <Area Name>
+
+## Purpose
+<1-2 sentences: what this area of the codebase is responsible for>
+
+## Boundaries
+<What belongs here and what doesn't. Where related code lives instead.>
+
+## Key Files
+| File | Responsibility |
+|------|---------------|
+| `path/to/file.py` | <what it does> |
+| `path/to/other.py` | <what it does> |
+
+## Reusable Code
+Utilities and helpers in this area that MUST be reused (not re-implemented):
+
+| Function/Class | Location | What It Does |
+|----------------|----------|-------------|
+| `format_currency()` | `utils/formatters.py:42` | Formats decimal as currency string |
+| `BaseAPIView` | `api/base.py:15` | Base view with auth, pagination, error handling |
+
+## Patterns
+<How things are done in this area. Reference specific files as exemplars.>
+
+### Naming
+- <naming convention with example>
+
+### Structure
+- <structural pattern with example file>
+
+## Where New Code Goes
+- New <type> → `path/to/directory/`
+- New <type> → `path/to/other/`
+
+## Known Duplicates
+<Only if duplicates data exists in snapshot. List clones that touch this area.>
+
+| Files | Lines | What's Duplicated |
+|-------|-------|------------------|
+| `views.py:42-68` ↔ `api/views.py:15-41` | 26 | Request validation logic |
+```
+
+### 5. Generate Data Schema
+
+Scan the codebase for data models, ORM definitions, migration files, and schema declarations. Produce `.grimoire/docs/data/schema.yml` documenting the current data layer.
+
+**Where to look:**
+- ORM models: Django `models.py`, SQLAlchemy models, Prisma `schema.prisma`, TypeORM entities, Mongoose schemas
+- Migrations: `migrations/`, `alembic/versions/`, `prisma/migrations/`
+- Raw SQL: `*.sql` files, schema definitions
+- NoSQL: Mongoose schemas, DynamoDB table definitions, Firestore rules
+- API schemas: GraphQL `.graphql` files, protobuf `.proto` files, JSON Schema
+- External APIs: OpenAPI/Swagger specs, Postman collections, API client wrappers, SDK config files
+- Message formats: Avro `.avsc`, protobuf `.proto`, JSON Schema for events/messages
+
+**Schema format:** See `../references/schema-format.md` for the full YAML format with examples covering tables, nested objects, relationships, and external APIs.
+
+**Rules:**
+- Document what exists in the code, not what the database actually contains
+- Use `source:` to point back to the ORM model or migration file — the schema.yml is a summary, the code is the truth
+- Use `type: table` for SQL, `type: collection` for Mongo/document stores, `type: document` for nested sub-documents
+- Use `type: external_api` for APIs you consume or produce but don't own the schema for
+- Nested `fields` for embedded objects/arrays (common in document DBs and JSON columns)
+- Include `note:` only when the field name isn't self-explanatory
+- Include `relationships` when the ORM defines them explicitly
+- For external APIs: `schema_ref` is the most important field — point to the OpenAPI spec, Swagger URL, API docs page, or local spec file so the LLM (and humans) know where to get the full contract
+- For external APIs: `client` points to where the codebase calls the API — this is where changes happen when the API changes
+- Don't duplicate entire OpenAPI specs into schema.yml — summarize the endpoints you actually use with key fields, and point to the full spec via `schema_ref`
+- If the project has no data layer, skip this step entirely
+
+If `.grimoire/docs/data/` already exists, update it rather than regenerating. Diff against existing schema.yml to flag new models or removed fields.
+
+### 6. Generate Project Context
+
+Scan the codebase for deployment and infrastructure artifacts, then populate `.grimoire/docs/context.yml`. This file captures the project's ecosystem — how it's deployed, what services it talks to, and what infrastructure it depends on. If `context.yml` doesn't exist, copy it from the template first (`grimoire init` creates it, but this handles projects initialized before this feature).
+
+**Where to look:**
+
+| Artifact | What it tells you |
+|----------|------------------|
+| `Dockerfile`, `docker-compose.yml` | Containerized deployment; compose reveals linked services, databases, caches |
+| `k8s/`, `kubernetes/`, `Chart.yaml`, `helmfile.yaml` | Kubernetes deployment; manifests reveal services, ingresses, config maps |
+| `*.tf`, `terraform/`, `cdk.json`, `serverless.yml` | Infrastructure-as-code; reveals cloud provider, services, and architecture |
+| `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/` | CI/CD platform and deploy triggers |
+| `Procfile`, `app.json`, `vercel.json`, `netlify.toml` | PaaS deployment target |
+| `fly.toml`, `render.yaml`, `railway.json` | PaaS deployment target |
+| `.env.example`, `.env.template` | Environment variables reveal infrastructure dependencies (DB hosts, cache URLs, API keys) |
+| `docker-compose.yml` services | Related services, databases, caches, queues running locally |
+| API client wrappers, SDK config | Internal service dependencies |
+
+**Workflow:**
+1. Scan for the artifacts above — note what exists
+2. Read `docker-compose.yml` (if present) — it's the richest source of service and infrastructure dependencies
+3. Read `.env.example` (if present) — environment variables reveal what the project connects to
+4. Read CI/CD config files — identify the platform, key workflows, and deploy triggers
+5. Read IaC files (Terraform, CDK, etc.) — identify cloud provider and provisioned resources
+6. Populate `context.yml` with what you found — fill in real values, remove unused commented sections
+7. Present findings to the user for confirmation — they'll know about services and infrastructure that aren't discoverable from code alone (e.g., a shared auth service, a data warehouse they push to)
+
+**Rules:**
+- Only populate sections where you found evidence. Leave sections empty (with comments) rather than guessing.
+- Use environment variable references (`${DATABASE_HOST}`) for hostnames and credentials — never hardcode real values.
+- The `services` section is for **internal/sibling services** your org owns. Third-party APIs (Stripe, Twilio, etc.) belong in `schema.yml` under `external_api`.
+- If `context.yml` already exists and has content, update it rather than overwriting — the user may have manually added entries.
+- Ask the user about anything you can't determine from code: "I see a Redis connection in docker-compose but I'm not sure if it's just cache or also used for sessions — which is it?"
+
+### 7. Generate Index
+Create or update `.grimoire/docs/index.yml`:
+
+```yaml
+# Grimoire Project Map
+# Auto-generated by /grimoire:discover
+# Last updated: YYYY-MM-DD
+
+areas:
+  - name: api
+    path: .grimoire/docs/api.md
+    directory: src/api
+    description: REST API layer — views, serializers, URL routing
+  - name: models
+    path: .grimoire/docs/models.md
+    directory: src/models
+    description: Data models, managers, querysets
+  - name: utils
+    path: .grimoire/docs/utils.md
+    directory: src/utils
+    description: Shared utilities, helpers, formatters
+```
+
+The `directory` field links each doc back to the source directory — this is what `grimoire map --refresh` uses to detect gaps.
+
+### Freshness Tracking
+
+Every area doc and the data schema must include a `Last updated` date in a comment or header. This lets other skills (plan, apply) judge whether the docs are trustworthy or stale.
+
+**In `index.yml`**, track freshness per area:
+```yaml
+areas:
+  - name: api
+    path: .grimoire/docs/api.md
+    directory: src/api
+    description: REST API layer — views, serializers, URL routing
+    last_updated: 2026-04-05
+```
+
+**In each area doc**, include a last-updated line at the top:
+```markdown
+# API Layer
+> Last updated: 2026-04-05
+```
+
+**In `schema.yml`**, the `Last updated` comment at the top already serves this purpose.
+
+**Staleness rule:** If an area doc is older than the most recent commit touching that directory (check via `git log -1 --format=%ci <directory>`), it's potentially stale. When running a full scan or gap fill, flag stale docs and offer to refresh them.
+
+**Why this matters:** Area docs are the primary mechanism for reducing context window usage and preventing hallucinations. Stale docs are worse than no docs — they give the agent confident but wrong information about file paths, function names, and patterns. Freshness tracking lets other skills know when to trust the docs vs. when to fall back to reading source files.
+
+### 8. Present Summary
+After generating, show the user:
+- How many areas documented
+- How many reusable utilities inventoried
+- Any areas that seem under-organized or have pattern inconsistencies
+- Suggest which area docs are most critical for the plan skill to read
+
+## Config Files
+
+Users can customize what gets scanned by editing files in `.grimoire/`:
+
+- **`.grimoire/mapignore`** — directories/patterns to skip during scanning (like .gitignore). Edit to exclude vendor code, generated files, etc.
+- **`.grimoire/mapkeys`** — key file definitions (format: `filename = type`). Edit to add project-specific indicators like `factories.py = test-factories` or `signals.py = django-signals`.
+
+These are read by `grimoire map` and affect the snapshot this skill consumes.
+
+## Integration with Other Skills
+
+- The **plan** skill should read `.grimoire/docs/` before generating tasks — look for existing utilities in the reuse inventory, follow documented patterns
+- The **verify** skill can check new code against documented patterns
+- The **audit** skill can trigger a discover pass as part of onboarding
+- Run `grimoire map --refresh` periodically to detect new undocumented areas, then `/grimoire:discover` to fill the gaps
+
+## Important
+- **Start from the snapshot.** Don't scan the filesystem yourself — `grimoire map` already did that. Read `.snapshot.json` for structure, then use `codebase-memory-mcp` graph queries for symbols and call graphs (if available), and read actual code files for meaning.
+- **Prefer graph queries over file reads.** If `codebase-memory-mcp` is available, use `search_graph` and `query_graph` to find symbols, call paths, and architecture rather than reading every source file. This is faster, more accurate (AST-parsed), and uses fewer tokens.
+- **Document what IS, not what should be.** This is a map of the actual codebase, not aspirational standards. If the code is inconsistent, note it — don't paper over it.
+- **Point, don't copy.** Reference files and line numbers as exemplars. Don't duplicate code into the docs — it goes stale.
+- **Focus on what helps LLMs.** The goal is preventing duplicate code and misplaced files. Prioritize: reusable utilities > file placement > naming conventions > architectural patterns.
+- **Keep docs lean.** Each area doc should be scannable in 30 seconds. If it's too long, split it.
+- **The reuse inventory is the most valuable output.** An LLM that knows `format_currency()` exists in `utils/formatters.py` won't write a new one.
+- **Don't document the obvious.** Skip areas that are self-explanatory from file names alone. Focus on areas where an LLM would make mistakes.
+- **Update, don't accumulate.** When refreshing, replace stale docs rather than appending. The docs should reflect the current codebase, not its history.
+
+## Done
+When area docs, schema, context, and index are generated, the workflow is complete. Suggest `grimoire-audit` to document existing features and decisions as Gherkin specs and ADRs.

package/skills/grimoire-draft/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: grimoire-draft
+description: Draft or update Gherkin features and MADR architecture decisions collaboratively with the user. Use when the user describes new functionality, requirements, or architecture choices.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-draft
+
+Draft or update Gherkin features and MADR architecture decisions collaboratively with the user.
+
+## Triggers
+- User describes new functionality, behavior changes, or feature requests
+- User asks to create/update a feature spec or requirement
+- User describes a technology choice, architecture decision, or trade-off
+- Loose match: contains "feature", "requirement", "spec", "decision", "grimoire" with "create", "draft", "plan", "start", "new"
+
+## Routing
+- Bug report ("something is broken") → `grimoire-bug` or `grimoire-bug-report`
+- Pure refactoring (no behavior change) → no grimoire artifact needed. Suggest an ADR only if architecturally significant.
+- Config, deps, formatting → not grimoire territory. Just do it.
+- If unclear after one clarifying question, default to drafting a feature.
+
+## Workflow
+
+### 1. Qualify the Request
+Before doing anything, determine what kind of change this is:
+
+- **Behavioral** (Given/When/Then expressible) → draft `.feature` files
+- **Architectural** (trade-off, choice, structural) → draft MADR decision record
+- **Both** → draft features AND decision records
+- **Bug fix** → STOP. Tell the user: "The feature file already describes the correct behavior. Let's just fix the code."
+- **Refactoring** → STOP. No behavior change = no grimoire artifact. Suggest an ADR only if it's a significant architectural shift.
+- **Config/deps/formatting** → STOP. Not grimoire territory.
+
+If unclear, ask the user one clarifying question to route correctly.
+
+### 2. Score Complexity
+
+Assess the change's complexity to determine how much ceremony is appropriate. Score based on these signals:
+
+| Level | Label | Signals | Ceremony |
+|-------|-------|---------|----------|
+| 1 | **Trivial** | Config, typo, copy change, single-file fix | Skip research (step 3). Minimal manifest (Why + Feature/Decision list only). No Pre-Mortem. |
+| 2 | **Simple** | Single capability, ≤3 files, no architecture decisions, no data changes | Light research (step 3 — check built-ins and first-party only). Standard manifest. |
+| 3 | **Moderate** | Multiple capabilities, architecture decisions, data model changes, new dependencies | Full research (step 3). Full manifest with Assumptions and Pre-Mortem. |
+| 4 | **Complex** | Cross-cutting concerns, multiple services/systems, security-sensitive, new infrastructure | Full research (step 3). Full manifest. Mandatory `grimoire-review` after plan (not optional). |
+
+Record the level in `manifest.md` frontmatter as `complexity: <1-4>`. Downstream skills use this:
+- **Plan** adjusts task granularity (level 1-2: coarser tasks; level 3-4: fine-grained with context blocks)
+- **Review** adjusts persona depth (level 1: skip review; level 2: Senior Engineer only; level 3: all relevant personas; level 4: all personas mandatory)
+
+If unsure between two levels, pick the higher one. The user can override: "this is simpler than you think" or "treat this as complex."
+
+### 3. Research Existing Solutions
+Before designing, research what already exists. Do not ask the user to research — do it yourself.
+
+- **Level 1**: Skip this step.
+- **Level 2**: Light research — check built-ins and first-party ecosystem only.
+- **Level 3-4**: Full research across all categories.
+
+Follow the methodology in `../references/build-vs-buy.md`. Present findings to the user and wait for agreement before proceeding.
+
+### 4. Elicit Requirements
+Now that you know whether you're building, adopting, or going hybrid, surface the requirements the user hasn't specified.
+
+- **Level 1**: Skip this step.
+- **Level 2+**: Follow `../references/elicitation-personas.md` at the depth matching your complexity level.
+
+The build-vs-buy outcome shapes which questions matter:
+- **Adopting**: Focus on integration — how it fits, what config is needed. Skip deep business-rule elicitation.
+- **Building custom**: Full elicitation — business rules, edge cases, data contracts, security, NFRs.
+- **Hybrid**: Elicit deeply for custom parts. For adopted parts, focus on integration boundaries.
+
+Present a Requirements Summary (template in the reference) and wait for user confirmation before proceeding.
+
+### 5. Check Existing State
+- Read `features/` to understand the current behavioral baseline
+- Read `.grimoire/decisions/` to understand existing architecture decisions
+- Read `.grimoire/docs/context.yml` (if it exists) to understand the deployment environment, related services, and infrastructure — this tells you what's available (caches, queues, sibling services) and what constraints apply (deployment target, environments)
+- Check `.grimoire/changes/` for any in-progress changes that might overlap
+- If there's a conflict with an active change, flag it
+
+### 6. Scaffold the Change
+- Choose a `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`)
+- Create `.grimoire/changes/<change-id>/`
+
+### 7. Draft Artifacts
+**For behavioral changes:**
+- Write proposed `.feature` files in `.grimoire/changes/<change-id>/features/<capability>/`
+- If modifying an existing feature, copy the current baseline first, then modify
+- Follow Gherkin best practices:
+  - Feature title + user story (As a / I want / So that)
+  - Background for shared preconditions
+  - One scenario per behavior
+  - Given/When/Then — describe WHAT, never HOW
+  - No implementation details in feature files
+
+**Security tags on scenarios:**
+Apply Gherkin tags per `../references/security-compliance.md` (section "Security Tags"). Tags drive stricter checks in plan, review, and verify stages. Apply compliance-specific tags only when `project.compliance` is configured. If no compliance frameworks and no security surface, don't add tags.
+
+**For architecture decisions:**
+- Write MADR record in `.grimoire/changes/<change-id>/decisions/`
+- Use the template from `.grimoire/decisions/template.md` or the AGENTS.md format
+- Include considered options, decision drivers, and consequences
+
+**For changes that touch data:**
+- Check `.grimoire/docs/data/schema.yml` for the current data schema (if it exists)
+- If the change adds, modifies, or removes data models, fields, indexes, or external API integrations, write a `data.yml` in `.grimoire/changes/<change-id>/` showing the proposed schema changes
+- Use the same YAML format as `schema.yml` but only include what's changing — new models, added/removed fields, new external API integrations
+- Mark changes clearly with `action:` on each entry:
+
+```yaml
+# Proposed data changes for: add-user-profiles
+
+users:
+  action: modify
+  source: src/models/user.py
+  fields:
+    avatar_url:                    # new field
+      action: add
+      type: varchar
+      nullable: true
+    legacy_name:                   # removing a field
+      action: remove
+
+profiles:
+  action: add                      # entirely new model
+  type: collection
+  fields:
+    user_id: { type: objectId, ref: users }
+    bio: { type: string, max_length: 500 }
+    social_links:
+      type: array
+      items:
+        platform: { type: string }
+        url: { type: string }
+
+github_api:
+  action: add                      # new external API dependency
+  type: external_api
+  provider: GitHub
+  schema_ref: https://docs.github.com/en/rest
+  client: src/integrations/github.py
+  endpoints:
+    get_user:
+      method: GET
+      path: /users/{username}
+      request:                       # document what you send
+        headers:
+          Authorization: "Bearer {token}"
+      response:                      # document what you expect back
+        login: { type: string, required: true }
+        avatar_url: { type: string, required: true }
+        name: { type: string, nullable: true }
+      error_response:                # document known error shapes
+        message: { type: string }
+        status: { type: integer }
+```
+
+**Contract documentation is mandatory for external APIs.** Every endpoint entry must include:
+- **`request`**: headers, query params, or body fields your client sends
+- **`response`**: fields your client reads, with types and `required: true` for fields your code depends on
+- **`error_response`**: the error shape your client handles
+
+This is the contract. Downstream skills (plan, review, verify) use it to generate contract tests and detect breaking changes. If you don't know the exact shape, reference the `schema_ref` and document what your client actually uses — that subset is the contract.
+
+- If the change has no data impact, skip `data.yml` entirely — don't create an empty one
+
+**For all changes:**
+- Write `manifest.md` listing all artifacts, what's added/modified/removed, and why
+- Include `complexity: <1-4>` in the manifest frontmatter (from step 2)
+- **Level 1-2**: Assumptions and Pre-Mortem sections are optional (include if relevant)
+- **Level 3-4**: Include an **Assumptions** section: list what must be true for this change to succeed. For each assumption, note whether there is evidence or it is unvalidated. Unvalidated assumptions on the critical path should be flagged to the user.
+- **Level 3-4**: Include a **Pre-Mortem** section: imagine this change has failed or caused a production incident 6 months from now — what went wrong? List 2-5 plausible failure modes with mitigations or "accepted" if the risk is acknowledged.
+- The manifest must include a **Prior Art** section summarizing the research from step 3: what was found, what was evaluated, and why the chosen direction (adopt, build, or hybrid) was selected. If the decision was to build, include what's being borrowed from existing implementations. This section is consumed by the plan and review stages — without it, reviewers can't validate the build-vs-buy decision.
+
+### 8. Collaborate
+- Present the draft to the user
+- Iterate based on feedback
+- Do NOT proceed to plan stage without user approval
+
+### 9. Validate
+- Verify `.feature` files have valid Gherkin syntax
+- Verify MADR records have valid YAML frontmatter (status, date)
+- Verify manifest is complete and accurate
+- Every Feature has a user story
+- Every Scenario has at least Given + When + Then
+- No implementation details leaked into features
+
+## Important
+- ONE change at a time. Don't combine unrelated changes.
+- Features describe behavior, not implementation. If you catch yourself writing step-level implementation details, you've gone too far.
+- The manifest is lightweight glue — don't over-document. Just enough to capture why.
+- Always check if a capability/feature already exists before creating a new one.
+
+## Done
+When the user approves the draft, the workflow is complete. Present the change directory path and suggest next steps:
+- `grimoire-plan` to generate implementation tasks
+- Or further iteration if the user wants changes