@kiwidata/grimoire 0.1.1

package/skills/grimoire-plan/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: grimoire-plan
+description: Derive implementation tasks from approved Gherkin features and MADR decisions. Use when features are approved and ready for task breakdown.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-plan
+
+Derive implementation tasks from approved Gherkin features and MADR decisions. The output must be detailed enough that any LLM can execute the tasks without further planning.
+
+## Triggers
+- User has approved a grimoire draft and wants to plan implementation
+- User asks to create tasks or plan work for a grimoire change
+- Loose match: "plan", "tasks" with a change reference
+
+## Routing
+- No approved change exists → `grimoire-draft` first
+- Change is Level 1 (trivial) → plan is optional; suggest applying directly with minimal tasks
+- User wants to review the design → `grimoire-review` (after plan, before apply)
+
+## Prerequisites
+- A change exists in `.grimoire/changes/<change-id>/` with:
+  - `manifest.md` (approved)
+  - At least one `.feature` file or decision record
+
+## Workflow
+
+### 1. Select Change
+- List active changes in `.grimoire/changes/`
+- If multiple, ask user which one to plan
+- If only one, confirm it
+
+### 2. Read All Artifacts
+
+**Grimoire docs first, codebase second.** The `.grimoire/docs/` directory is a pre-computed map of the codebase — it tells you where code lives, what utilities exist, what patterns to follow, and what the data layer looks like. Read these *instead of* exploring the raw codebase. Only read specific source files when the docs don't have what you need.
+
+**Always read:**
+- `manifest.md` for the change summary, **including complexity level, Assumptions, Pre-Mortem, and Prior Art sections**
+- All proposed `.feature` files
+- All proposed decision records, **including Cost of Ownership sections**
+- The current baseline (`features/`, `.grimoire/decisions/`) for context on what's changing
+
+**Validate the build-vs-buy decision:**
+- Check that `manifest.md` has a **Prior Art** section documenting what existing solutions were researched. If it's missing or empty, **stop and tell the user** — planning without a build-vs-buy analysis produces plans that ignore cheaper alternatives.
+- If the decision was to **adopt** a library/service, the plan tasks should focus on integration, configuration, and contract testing — not reimplementation.
+- If the decision was to **build custom**, verify the manifest documents (1) what existing tools were considered, (2) the specific requirements they don't meet, and (3) what design patterns are being borrowed from prior art.
+- If the decision was **hybrid** (adopt for part, build for part), ensure the boundary between adopted and custom code is clear in the tasks.
+
+**Read from grimoire docs (these replace codebase exploration):**
+- **`.grimoire/docs/<area>.md`** for each area the change touches — these contain: key files with responsibilities, reusable utilities (exact function names, file paths, line numbers), naming conventions, structural patterns, and "Where New Code Goes" guidance. This is the information that lets you write tasks with exact file paths without reading every source file.
+- **`.grimoire/docs/data/schema.yml`** — the full data model: every table/collection, field types, relationships, indexes, and external API contracts with `source:` pointers to ORM code. Read this instead of reading individual model files.
+- **`.grimoire/docs/context.yml`** — the project's deployment environment, related services, infrastructure dependencies, CI/CD pipelines, and observability setup. Read this to understand deployment constraints (e.g., Lambda means no long-running processes, Kubernetes means you may need health check endpoints), cross-service boundaries (e.g., auth is handled by a sibling service, not this project), and infrastructure available at runtime (e.g., Redis is available for caching, RabbitMQ for async tasks).
+- **`.grimoire/docs/.snapshot.json`** `duplicates` section if present — existing clones in areas you're touching, so tasks consolidate rather than add more.
+
+**Read proposed data changes:**
+- **`data.yml`** if present — proposed schema changes need migration and model tasks
+
+**Read specific source files only when:**
+- Area docs don't exist yet (tell the user to run `grimoire map` + `/grimoire:discover` first — planning without area docs produces worse tasks)
+- Area docs exist but you need to verify a specific implementation detail (e.g., exact function signature, exact import path)
+- You need to read existing step definitions to understand the test setup
+
+**Do NOT read the entire codebase** for "context." The plan skill's job is to produce tasks with specific file paths and specific assertions. Area docs + data schema give you this. Reading dozens of source files wastes context window and doesn't produce better plans.
+
+### 3. Check Specification Completeness
+
+Before generating tasks, evaluate whether the specifications are detailed enough to plan against. Underspecified requirements produce vague tasks, which produce wrong code.
+
+Review the specs through each persona's lens and flag gaps. **Only check personas relevant to the change** — don't manufacture issues.
+
+#### Outcome & Scope check
+- Does the manifest have a clear **Why** that describes the outcome, not just the mechanism? ("Users can reset passwords" not "Add password reset endpoint.")
+- Does the manifest have a **Non-goals** section? If missing or empty on a level 3-4 change, flag it — without non-goals, scope creep is invisible during implementation.
+- Do any scenarios appear to implement something listed as a non-goal? Flag as **blocker** — the draft contradicts itself.
+
+Evaluate through each relevant persona's lens — see `../references/elicitation-personas.md` for the full question set. In plan, you're checking completeness, not asking questions. Flag gaps as issues.
+
+**Key checks per persona:**
+- **Outcome & Scope**: Does the manifest have a clear Why (outcome, not mechanism)? Does it have Non-goals? Do any scenarios contradict non-goals?
+- **PM**: Scenarios for success AND errors? User stories on every feature? Specific Given/When/Then (not vague)?
+- **Engineer**: Unvalidated assumptions on critical path? Prior art patterns documented (if building custom)? Scenarios specific enough for concrete file paths?
+- **Security**: Input/auth/sensitive-data scenarios have corresponding error/abuse scenarios? Quality Attribute targets not blank?
+- **Data**: External APIs or new models without `data.yml`? Data constraints specified (required, unique, nullable)?
+- **QA**: Negative scenario for every happy path? Boundary values specified?
+
+**If issues are found:**
+
+1. Present findings grouped by persona, with a specific question for each gap
+2. Ask the user to choose:
+   - **Clarify now** — answer the questions and update the draft before continuing to task generation
+   - **Proceed anyway** — acknowledge the gaps and plan around them (tasks will note where assumptions were made)
+   - **Return to draft** — go back to `grimoire-draft` to fill in the gaps
+
+This is not a gate — level 1-2 changes (from manifest `complexity`) can proceed with minor gaps. Level 3-4 changes with multiple signals should strongly recommend clarification before planning.
+
+**If no issues are found**, proceed directly to task generation.
+
+### 4. Generate Tasks
+Create `.grimoire/changes/<change-id>/tasks.md`. **Every scenario must produce both production code AND tests.** Tasks are structured as pairs: step definitions first, then production code.
+
+**THE PLAN MUST RESPECT NON-GOALS.** Read the manifest's Non-goals section. If a task would touch, implement, or extend something listed as a non-goal, do not include it. If you think a non-goal should be reconsidered, flag it to the user — don't silently include it.
+
+**THE PLAN MUST BE SPECIFIC ENOUGH TO EXECUTE WITHOUT FURTHER PLANNING.**
+
+**THE PLAN MUST PREFER SIMPLICITY.** For each task, choose the approach with the least code, fewest new files, and smallest surface area. If a task can be solved by adding a few lines to an existing file, don't create a new module. If a standard library function does the job, don't pull in a dependency. If three lines of inline code are clearer than a helper, keep them inline. Flag any task that introduces a new abstraction, utility, or pattern — it needs a reason.
+
+**THE PLAN MUST USE PROVEN PATTERNS, NOT INVENT NEW ONES.** When the task fits a well-known pattern, name it and follow it:
+- **Data pipelines** → ETL (Extract, Transform, Load) or ELT. Name stages explicitly. Don't invent a bespoke "data flow."
+- **Web applications** → MVC, MVP, or MVVM depending on the framework's conventions. Follow the framework, don't fight it.
+- **APIs** → RESTful resource design, or the project's existing API style. Don't mix conventions.
+- **Background jobs** → Producer/consumer, pub/sub, or the framework's job/task pattern (e.g., Celery tasks, Bull queues).
+- **State management** → Use the framework's idiomatic approach (Redux, Vuex, signals, etc.), not a hand-rolled event system.
+- **Authentication & security** → Always recommend proven security processes: OAuth2/OIDC for auth flows, bcrypt/argon2 for password hashing, CSRF protection for forms, parameterized queries for database access. Never roll custom crypto, custom auth tokens, or custom session management when a battle-tested library exists.
+
+**THE PLAN MUST RESPECT SECURITY TAGS AND COMPLIANCE.**
+Check `.grimoire/config.yaml` under `project.compliance`. When scenarios have security tags, the plan must include corresponding tasks per `../references/security-compliance.md` (section "What Each Tag Requires — In planning").
+
+If no compliance frameworks are configured and no security tags are present, skip this.
+
+If no established pattern applies, state that explicitly in the task and explain why.
+
+**THE PLAN MUST ENFORCE SINGLE RESPONSIBILITY.** Each file, class, and function should do one thing:
+- A function that fetches data should not also format it for display
+- A class that manages database access should not also handle HTTP responses
+- A module that defines routes should not also contain business logic
+- If a task description combines two distinct responsibilities (e.g., "fetch and render", "validate and persist"), split it into separate tasks or explicitly call out the boundary in the task description
+- When planning new files, each file should have a clear, singular purpose. Name it after what it does, not what feature it supports
+
+**THE PLAN MUST USE CLEAR NAMING AND FLAT STRUCTURE.**
+- Variables, functions, classes, and files must have descriptive names that reveal intent — `calculate_invoice_total` not `calc`, `UserAuthenticationService` not `UAS`, `test_login_redirects_to_dashboard` not `test_login_1`
+- Avoid abbreviations unless they are universally understood in the domain (e.g., `URL`, `HTTP`, `ID`)
+- Avoid deep nesting: if a task would produce code with more than 3 levels of indentation, restructure it. Use early returns/guard clauses, extract helper functions, or use pipeline/chain patterns. The plan should call this out explicitly when the task involves conditional or iterative logic
+
+Each task must include:
+- **What file(s) to create or edit** — exact paths, not vague references
+- **What to implement** — specific functions, classes, views, routes, not just "implement the feature"
+- **Which scenario it satisfies** — traceability back to the .feature file
+- **What the step definition should assert** — the expected behavior, not just "write a test"
+
+Bad task (too vague — will trigger re-planning):
+```
+- [ ] 1.1 Implement login with 2FA
+```
+
+Good task (specific enough to execute):
+```
+- [ ] 1.1 Write step defs in `tests/step_defs/test_auth.py` for scenario: "Successful login with valid TOTP code" in `auth/login.feature`
+      - Given step: call `client.post('/login/', credentials)` to log in
+      - When step: call `client.post('/verify-totp/', {'code': valid_code})`
+      - Then step: assert response redirects to `/dashboard/` (status 302)
+- [ ] 1.2 Add TOTP verification to `auth/views.py`:
+      - Create `VerifyTOTPView` accepting POST with `code` field
+      - Validate code against user's TOTP secret using `pyotp`
+      - On success: complete login session, redirect to dashboard
+      - On failure: return to verification page with error message
+```
+
+**From feature scenarios:**
+- Each new scenario → step definition task + implementation task
+- Each modified scenario → update step def + update implementation
+- Group by capability/feature file
+- Step definitions come BEFORE production code (red-green BDD cycle)
+- **Use the project's configured BDD tool** — check `.grimoire/config.yaml` under `tools.bdd_test` for the test runner (e.g., `behave`, `pytest-bdd`, `cucumber-js`, `cucumber`). Step definitions must follow that tool's conventions:
+  - **behave** (Python): step defs in `features/steps/`, use `@given`, `@when`, `@then` decorators from `behave`
+  - **pytest-bdd** (Python): step defs alongside tests, use `@scenario`, `@given`, `@when`, `@then` from `pytest_bdd`
+  - **cucumber-js** (JS/TS): step defs in `features/step_definitions/`, use `Given`, `When`, `Then` from `@cucumber/cucumber`
+  - If no BDD tool is configured, check the existing test directory structure and imports to infer which framework is in use
+
+**From decisions:**
+- Each decision → implementation task(s) with specific files and changes
+- If the ADR has a Confirmation section → add a test/check task for it
+
+**Shared step definitions:**
+- Identify steps that will be reused across scenarios (Given steps especially)
+- These go in the project's common step location (check existing test setup)
+- Group by domain concept, NOT by feature file
+
+**From data.yml (if present):**
+- Each new model → migration task + ORM/schema task
+- Each modified field → migration task (specify: is it safe to run live? nullable? default?)
+- Each removed field → migration task with data cleanup if needed
+- Each new external API → client wrapper task referencing `schema_ref` for the full contract
+- Each new or modified external API → **contract validation test task** that asserts the client's request/response shapes match the contract documented in `data.yml` / `schema.yml`. The test should:
+  - Validate that every `required: true` response field is read and typed correctly in the client
+  - Validate that request payloads match the documented shape (required fields present, types correct)
+  - Validate error response handling matches the documented `error_response` shape
+  - Use a recorded/fixture response (not a live call) so the test runs locally without network access
+- Each modified external API client (existing API, changed usage) → **contract regression test** that catches if the client drifts from the documented contract. If the client starts reading a new field or stops sending a required field, the test must fail.
+- Data tasks come BEFORE feature implementation tasks — the models must exist before code that uses them
+- Order: schema/model changes → migrations → contract tests → seed data (if any) → then feature code
+
+**Mocking strategy for external services:**
+Follow the rules in `../references/testing-contracts.md`. Key points: mock at HTTP boundary (not client), fixtures must match `schema.yml`, include error fixtures. Each contract test task must specify: (1) which HTTP mocking library, (2) which fixture file, (3) what the fixture contains (from `schema.yml`).
+
+**From manifest Assumptions:**
+- Each unvalidated assumption on the critical path → a verification task (spike, proof-of-concept, or integration test that confirms the assumption holds)
+- If an assumption turns out to be wrong during planning, flag it to the user — it may invalidate the change
+
+**From manifest Pre-Mortem:**
+- Each failure mode with a mitigation → the mitigation becomes a task or an edge case to cover in an existing task
+- Each failure mode marked "accepted" → add a comment in the relevant code or test noting the accepted risk, so future developers understand the trade-off
+- Pre-mortem risks often reveal missing scenarios — if a failure mode isn't covered by any Gherkin scenario, consider whether it should be
+
+**From decision Cost of Ownership:**
+- Prefer implementation approaches that minimize the maintenance burden identified in the ADR
+- If the ADR identifies sunset criteria, add a task to document them where they'll be seen (e.g., a comment in config, a monitoring alert, or a calendar reminder)
+- If maintenance burden is high, prefer simpler alternatives even if they're less elegant
+
+**From manifest Prior Art (when building custom):**
+- If the manifest identifies design patterns borrowed from existing tools, tasks must follow those patterns — don't reinvent what the prior art already refined
+- If the manifest identifies specific data flows or API shapes from existing tools, reference them in the task descriptions so the implementing agent understands the intent
+- If the prior art research surfaced an existing tool that covers part of the need, consider whether the plan should adopt it for that part instead of building everything custom — flag this to the user as a simplification opportunity
+- If a library was rejected for a specific reason (e.g., doesn't support X), add a comment to the relevant task noting this so future developers don't re-evaluate the same option
+
+**Existing code to reuse:**
+- If `.grimoire/docs/` has area docs, check the Reusable Code tables for utilities that apply to this change
+- If the snapshot has duplicate data, check whether the area you're touching already has clones — tasks should consolidate rather than add more
+- Add a "Reuse" section at the top of tasks.md listing specific functions/classes to import instead of rewriting
+
+**Verification (always last):**
+- Run ALL feature files — new and existing
+- Run full project test suite
+- Validate ADR confirmation criteria (if applicable)
+
+### 5. Task Format
+The tasks file starts with a context block so any LLM can orient without re-reading every artifact. Each task section includes a `<!-- context: ... -->` block listing the exact files an agent should load before working on that section. This is critical for reducing context rot — each task or task group can run in a fresh session that loads only what it needs.
+
+```markdown
+# Tasks: <change-id>
+
+> **Change**: <one-line summary from manifest>
+> **Features**: <list of .feature files in this change>
+> **Decisions**: <list of ADRs in this change, or "none">
+> **Test command**: `<exact command to run feature tests, e.g., pytest tests/ -k "auth">`
+> **Status**: X/Y tasks complete
+
+## 1. <Capability/Area>
+<!-- context:
+  - .grimoire/changes/<change-id>/features/<capability>/<name>.feature
+  - .grimoire/docs/<area>.md
+  - src/<area>/<file-to-edit>.ts
+  - tests/<area>/<test-file>.ts
+-->
+- [ ] 1.1 Write step defs in `<exact path>` for scenario: "<scenario name>" in `<file>`
+      - Given: <what the step does, what it calls>
+      - When: <what the step does, what it calls>
+      - Then: <what to assert — specific expected values/states>
+- [ ] 1.2 Implement in `<exact path>`:
+      - <specific function/class/view to create or modify>
+      - <specific behavior to implement>
+      - <edge cases to handle>
+- [ ] 1.3 Write step defs in `<exact path>` for scenario: "<next scenario>"
+      ...
+- [ ] 1.4 Implement in `<exact path>`:
+      ...
+
+## 2. Shared Steps
+<!-- context:
+  - tests/step_defs/common.py
+  - .grimoire/changes/<change-id>/features/<all relevant .feature files>
+-->
+- [ ] 2.1 Add to `<exact path>`:
+      - Given "<step text>": <what it does>
+      - Given "<step text>": <what it does>
+
+## 3. Architecture
+<!-- context:
+  - .grimoire/changes/<change-id>/decisions/<nnnn-title>.md
+  - src/<files affected by decision>
+-->
+- [ ] 3.1 In `<exact path>`: <specific change from ADR>
+- [ ] 3.2 Add test in `<exact path>`: <ADR confirmation check — what to assert>
+
+## 4. Verification
+- [ ] 4.1 Run `<exact test command>` — all new scenarios green
+- [ ] 4.2 Run `<exact test command>` — no regressions
+- [ ] 4.3 Run `<exact test command>` — full project suite
+```
+
+**Context blocks are mandatory.** Every task section (except Verification) must have a `<!-- context: ... -->` listing the files needed. This serves two purposes:
+1. **Fresh sessions:** An agent starting a new session loads only the context block for its current section, avoiding accumulated noise from prior work
+2. **Subagent delegation:** In Claude Code, the parent agent passes the context list when spawning a subagent for a task group
+
+### 6. Quality Check
+Before presenting to the user, verify the plan:
+- [ ] Every task references a specific file path (no "implement the feature")
+- [ ] Every step definition task describes what to assert (no "write a test")
+- [ ] Every implementation task describes what to create/modify (no "add the code")
+- [ ] The verification section has the exact commands to run
+- [ ] Tasks are ordered: shared steps → step defs → production code → verification
+- [ ] No task requires the LLM to make architectural decisions — those should already be in the ADR
+
+If any task is too vague, make it more specific before presenting. Read more codebase if needed.
+
+### 7. Present to User
+- Present tasks to user
+- Confirm order and scope
+- Adjust based on feedback
+
+### 8. Design Review
+- Once the user approves the tasks, suggest running `grimoire-review` for a multi-perspective design review
+- **Complexity 1**: Skip review — suggest proceeding directly to `grimoire-apply`
+- **Complexity 2-3**: Review is **optional** — the user can skip it and go straight to `grimoire-apply`
+- **Complexity 4**: Review is **mandatory** — do not suggest skipping
+- If the user wants the review, hand off to the `grimoire-review` skill
+- Do NOT proceed to apply without user approval
+
+### Agent Configuration
+Check `.grimoire/config.yaml` for the configured agents:
+- **Planning** uses the `thinking` agent (`llm.thinking.command` / `llm.thinking.model`) — optimized for reasoning and design
+- **Implementation** uses the `coding` agent (`llm.coding.command` / `llm.coding.model`) — optimized for code generation
+- If the user has configured separate thinking/coding agents, note this in the tasks.md header so the apply stage knows which agent to use
+
+## Important
+- **Specificity is the whole point.** A vague plan is worse than no plan — it gives false confidence and the LLM will re-plan anyway. Every task must be executable without thinking.
+- Tasks should be small and specific — one logical unit of work each
+- Every task traces back to a scenario or decision
+- Order matters: dependencies first, verification last
+- Don't generate tasks for things that already work (check the baseline)
+- Read the actual codebase before writing tasks. Reference real file paths, real patterns, real conventions. Don't guess.
+
+## Done
+When the user approves the tasks, the workflow is complete. Suggest next steps based on complexity:
+- **Level 1**: Skip review, proceed to `grimoire-apply`
+- **Level 2-3**: Optionally run `grimoire-review`, or proceed to `grimoire-apply`
+- **Level 4**: `grimoire-review` is mandatory before `grimoire-apply`

package/skills/grimoire-pr/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: grimoire-pr
+description: Generate a pull request description from grimoire change artifacts with optional post-implementation LLM review. Use when the user is ready to create a PR.
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: kiwi-data
+  version: "0.1"
+---
+
+# grimoire-pr
+
+Generate a pull request description from grimoire change artifacts and optionally run a post-implementation review.
+
+## Triggers
+- User wants to create a PR for a completed grimoire change
+- User asks to generate a PR description
+- Loose match: "PR", "pull request", "ready to merge", "create PR"
+
+## Routing
+- Tasks incomplete → `grimoire-apply` first (or create a draft PR)
+- Haven't committed yet → `grimoire-commit` first
+- Want a pre-merge design review → this skill includes optional post-implementation review
+
+## Prerequisites
+- A change exists in `.grimoire/changes/<change-id>/` with:
+  - `manifest.md`
+  - `tasks.md` with all (or most) tasks checked
+  - Feature files and/or decision records
+- The change should be on a feature branch (created during apply)
+
+## Workflow
+
+### 1. Select Change
+- List active changes in `.grimoire/changes/`
+- If multiple, ask user which one to create a PR for
+- If only one, confirm it
+
+### 2. Gather Artifacts
+Read all change artifacts:
+- `manifest.md` — change summary, scope, and why
+- `tasks.md` — implementation checklist (check completion status)
+- All `.feature` files — scenario names for the test plan
+- All decision records — ADR titles for the description
+- Read `.grimoire/config.yaml` for commit style
+
+### 3. Generate PR Description
+Compose the PR body from grimoire artifacts:
+
+```markdown
+## Summary
+<from manifest's "Why" section — 1-3 sentences>
+
+## Changes
+<from manifest's "Feature Changes" section>
+- **ADDED** `capability/name.feature` — description
+- **MODIFIED** `capability/name.feature` — what changed
+
+## Scenarios
+<list all scenario names from the feature files>
+- "Scenario name" (`feature/file.feature`)
+- "Scenario name" (`feature/file.feature`)
+
+## Decisions
+<list ADR titles, or "None" if no architectural decisions>
+- 0005: Use PostgreSQL for vector storage
+
+## Test Plan
+- [ ] All new feature scenarios pass
+- [ ] No regressions in existing tests
+- [ ] ADR confirmation criteria met (if applicable)
+<additional items from tasks.md verification section>
+
+## Security
+<only include this section if the change has security-tagged scenarios or touches security-relevant code>
+- Tags: `@security`, `@auth`, `@pii`, etc. (list all security tags from the feature files)
+- Compliance: <list applicable frameworks from config, or "none configured">
+- Security-tagged scenarios verified: X/Y
+<if any security findings from review/verify exist, summarize the resolution>
+
+Change: <change-id>
+```
+
+**PR title:** Derive from manifest heading, following the project's commit style:
+- conventional: `feat: add two-factor authentication`
+- angular: `feat(auth): add two-factor authentication`
+
+### 4. Post-Implementation Review (Optional)
+If the user wants a review, run a quick automated pass on the actual diff:
+
+1. Get the diff: `git diff main...HEAD` (or the base branch)
+2. Read `.grimoire/config.yaml` for `project.compliance` and check feature files for security tags
+3. Feed the diff + PR description to the LLM with this prompt:
+
+> Review this pull request for issues that the design review might have missed now that real code exists. Focus on:
+> - Implementation doesn't match the scenarios described
+> - Missing error handling for edge cases in the scenarios
+> - Dependencies added that weren't in the plan
+> - Files changed that aren't covered by the task list (scope creep)
+> - Test quality: are step definitions making real assertions?
+>
+> **Security review** — scan changed files per `../references/security-compliance.md`: OWASP surface scan, security tag verification, compliance verification. Tag findings with OWASP/CWE.
+> Flag issues as **blocker** or **suggestion**. Be concise.
+
+4. Present findings alongside the PR description.
+
+### 5. Create PR
+Offer to create the PR:
+- **Preview only** (default): Output the PR title + body for the user to copy
+- **Create via gh**: If the user confirms and `gh` is available, run:
+  ```
+  gh pr create --title "<title>" --body "<body>"
+  ```
+- **Create via glab**: If the project uses GitLab and `glab` is available:
+  ```
+  glab mr create --title "<title>" --description "<body>"
+  ```
+
+Check that the branch is pushed to the remote before creating. If not, offer to push first.
+
+### 6. Link Back
+After PR creation:
+- Update manifest's status to `complete` if not already
+- Add the PR URL to the manifest as a comment or field
+- Suggest running `grimoire archive <change-id>` to complete the lifecycle
+
+## Important
+- The PR description must trace back to grimoire artifacts — this is what makes the audit trail work.
+- Include the `Change: <change-id>` line at the bottom so `grimoire trace` can find it.
+- Don't pad the description with boilerplate. Keep it factual: what changed, why, how to verify.
+- The post-implementation review is optional and quick — it's not a replacement for the design review, just a sanity check on the actual code.
+- If tasks are incomplete, warn the user but don't block PR creation — they may want a draft PR.
+
+## Done
+When the PR is created (or description is presented for manual creation), the workflow is complete. Suggest `grimoire archive <change-id>` to complete the lifecycle.