@groupby/ai-dev 0.5.1 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupby/ai-dev",
-  "version": "0.5.1",
+  "version": "0.5.4",
   "description": "Interactive installer for Rezolve Ai development content",
   "type": "module",
   "bin": {

package/teams/fhr-core/github/pull_request_template.md

@@ -0,0 +1,19 @@
+<!--
+PR TITLE must follow: FHR-<number>: <description>
+Example: FHR-7113: Add AI-first development workflow for FAS
+The pull-request.yml CI check will fail if the format is wrong.
+-->
+
+## Jira ticket
+
+[FHR-XXXX](https://attraqt.atlassian.net/browse/FHR-XXXX)
+
+## AI Development Checklist
+
+- [ ] Specification file present
+- [ ] Unit tests present and passing
+- [ ] Documentation file present
+- [ ] AI tool used: _Claude Code / Copilot / Agent / Other_
+- [ ] Tests generated/refined with AI (failing tests written before implementation)
+- [ ] AI review pass completed (visible in PR comments)
+- [ ] Repo context files (`CLAUDE.md`, `AGENTS.md`, `architecture.md`, `coding-guidelines.md`, `glossary.md`) still accurate

package/teams/fhr-core/resources/spec-template.md

@@ -0,0 +1,22 @@
+# FHR-XXXX TITLE
+
+> Task description, including background context, user stories, and so on.
+
+## Acceptance Criteria
+
+**Functional requirements**
+> - criteria 1
+> - criteria 2
+> - ...
+
+**Non-Functional requirements**
+> - criteria 1
+> - criteria 2
+
+
+## Design and Implementation Plan
+
+> Fill with the design and implementation plan.
+> List of user acceptance tests
+> List of unit tests
+

package/teams/fhr-core/skills/jira-ticket/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: jira-ticket
+description: Fetch a Jira ticket by number using the Atlassian MCP and report a summary. Use when the user says "jira", "ticket", or provides a ticket number like FHR-1234 or FAS-5678.
+tools: mcp__atlassian__getJiraIssue, mcp__atlassian__getAccessibleAtlassianResources
+---
+
+# Jira Ticket Summary
+
+Fetch a Jira ticket via the Atlassian MCP and return a structured summary.
+
+## Prerequisites
+
+The `atlassian` MCP server must be connected and authenticated. If the MCP tools are unavailable, tell the user:
+> The Atlassian MCP isn't connected. Run `/mcp` to connect and authenticate, then try again.
+
+## Steps
+
+1. **Validate input**: the ticket number comes from `$ARGUMENTS` (e.g. `FHR-6921`). If empty, ask the user for one.
+
+2. **Fetch the ticket** with the `mcp__atlassian__getJiraIssue` tool:
+   - `cloudId`: `attraqt.atlassian.net`
+   - `issueIdOrKey`: the ticket number from `$ARGUMENTS`
+   - `responseContentFormat`: `markdown` (so the description comes back as plain text, not ADF JSON)
+   - `fields`: `["summary", "status", "assignee", "reporter", "description", "labels", "components", "issuetype", "priority", "issuelinks", "fixVersions"]`
+
+   If the call fails with a cloudId/site error, call `mcp__atlassian__getAccessibleAtlassianResources` to find the correct cloudId, then retry with that value.
+
+3. **Check for errors**: if the tool returns an error (e.g. issue not found, no access), report it clearly and stop.
+
+4. **Report** a structured summary using these fields from the response:
+
+   - **Ticket**: `key` — `fields.summary`
+   - **Type / Priority**: `fields.issuetype.name` / `fields.priority.name`
+   - **Status**: `fields.status.name`
+   - **Assignee**: `fields.assignee.displayName` (or "Unassigned")
+   - **Reporter**: `fields.reporter.displayName`
+   - **Labels**: `fields.labels[]` joined, or "none"
+   - **Components**: `fields.components[].name` joined, or "none"
+   - **Fix Version**: `fields.fixVersions[].name`, or "none"
+   - **Description**: synthesise `fields.description` into 3–6 readable sentences
+   - **Linked tickets**: for each entry in `fields.issuelinks[]`, show the link type and the linked issue key + summary
+
+## Notes
+
+- Authentication is handled by the MCP's OAuth session — no API tokens or `CONFLUENCE_USER`/`CONFLUENCE_PASS` env vars are needed.
+- Never print the raw JSON. Synthesise a clean human-readable summary from the parsed fields.
+- If the description is empty or null, say "No description provided."

package/teams/fhr-core/skills/plan-spec/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: plan-spec
+description: Read a spec file and produce a detailed design and implementation plan — with BDD acceptance tests and TDD test cases per task — written into the spec's "Design and Implementation Plan" section, then committed. Use when user references a spec file and wants a plan, implementation design, or test specifications derived from requirements.
+arguments: spec-file
+---
+
+# Plan Spec
+
+Turns a refined spec into a concrete design and implementation plan with tests, committed to git.
+
+## Quick start
+
+```
+/plan-spec suggest-docs/src/main/docs/plans/FHR-XXXX-feature-name.md
+```
+
+## Workflow
+
+1. **Enter Plan mode** — call `EnterPlanMode` immediately; stay in it while producing the plan
+
+2. **Load context**
+   - Read the spec file passed as argument
+   - Read `glossary.md` from the project root for ubiquitous language
+   - Read `architecture.md` from the project root for architecture guidelines
+
+3. **Produce the plan**
+   - Break the feature into discrete implementation tasks
+   - For each task, use this format:
+     ```
+     ### Task: <name>
+     - [ ] Acceptance tests
+     - [ ] Unit tests
+     - [ ] Production code
+
+     **Acceptance tests (BDD)**
+     - Given ... When ... Then ...
+
+     **Unit tests (TDD)**
+     - should ... when ...
+     ```
+   - Respect module boundaries and patterns from `architecture.md`
+   - Use only domain terms from `glossary.md`
+
+4. **Exit Plan mode and write into spec** — call `ExitPlanMode`, then update the spec file
+   - Write the full plan under the `## Design and Implementation Plan` section
+   - Create the section if it does not already exist
+
+5. **Commit**
+   - Stage the spec file
+   - Commit with message (replace XXXX with the actual ticket number from the spec file): `FHR-XXXX: add design and implementation plan`
+
+## Constraints
+
+- Do NOT touch any source code
+- Do NOT implement anything — plan only
+- Use only ubiquitous language from the glossary
+- Follow architecture patterns (module boundaries, event bus, DI, interfaces) from `architecture.md`

package/teams/fhr-core/skills/refine-spec/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: refine-spec
+description: Conduct a structured requirements-refinement interview against a spec file, using the project's ubiquitous language from glossary.md, until scope and acceptance criteria are clear, then update the spec file in place. Use when user references a spec file and wants to clarify requirements, define scope, or sharpen acceptance criteria — but not write code or tests.
+arguments: spec-file
+---
+
+# Refine Spec
+
+Requirements-refinement session: interview the user until scope and acceptance criteria are clear, then rewrite the spec in place.
+
+## Quick start
+
+```
+/refine-spec suggest-docs/src/main/docs/plans/FHR-XXXX-feature-name.md
+```
+
+## Workflow
+
+1. **Enter Plan mode** — call `EnterPlanMode` immediately; stay in it through the entire interview
+
+2. **Load context**
+   - Read the spec file passed as argument
+   - Read `glossary.md` from the project root for ubiquitous language
+
+3. **Assess current state**
+   - Identify what is clear, what is vague, and what is missing
+   - Flag any terminology that drifts from the glossary
+
+4. **Interview loop**
+   - Ask focused, one-topic-at-a-time questions (scope, edge cases, acceptance criteria)
+   - Use only domain terms from the glossary — never invent synonyms
+   - Continue until scope is unambiguous, acceptance criteria are testable, no open questions remain
+
+5. **Exit Plan mode and update spec** — call `ExitPlanMode`, then rewrite the spec file in place
+   - Preserve original structure; add/update sections as needed
+   - Use only ubiquitous language from the glossary
+
+6. **Commit**
+   - Stage the spec file
+   - Commit with message (replace XXXX with the actual ticket number from the spec file): `FHR-XXXX: refine the requirements`
+
+## Constraints
+
+- Do NOT touch any source code
+- Do NOT discuss unit tests or implementation details
+- Do NOT propose solutions — only clarify requirements
+- Stop interviewing once all sections are clear

package/teams/fhr-core/skills/tdd-green/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: tdd-green
+description: Implement production code (green phase) for the next incomplete task in a spec file's Design and Implementation Plan, writing only enough code to make the failing tests pass, then refactor while keeping tests green, mark the Production code sub-task done, and commit the green and refactor work separately. Use when user references a spec file and wants to implement a feature, or says "green phase", "make tests pass", "tdd green", or "green and refactor".
+arguments: spec-file
+---
+
+# TDD Green
+
+Implements the production code to make the failing tests pass. Run after `/tdd-red`.
+
+## Quick start
+
+```
+/tdd-green suggest-docs/src/main/docs/plans/FHR-XXXX-feature-name.md
+```
+
+## Workflow
+
+1. **Load context**
+   - Read the spec file passed as argument
+   - Read `glossary.md` from the project root for ubiquitous language
+   - Read `coding-guidelines.md` from the project root for coding conventions
+   - Read `architecture.md` from the project root for module boundaries and patterns
+
+2. **Find the next incomplete task**
+   - Scan the `## Design and Implementation Plan` section for the first task whose `- [ ] Production code` checkbox is unchecked
+   - Work on that task only — do not advance to subsequent tasks
+
+3. **Implement production code**
+   - Write only enough production code to make the failing tests pass
+   - Follow all conventions in `coding-guidelines.md`
+   - Respect module boundaries from `architecture.md`
+   - Use only domain terms from `glossary.md`
+   - This is the **green phase**: no refactoring, no gold-plating — just passing tests
+
+4. **Run the tests**
+   - Unit tests
+   - Acceptance tests (JGiven)
+   - All tests must pass before proceeding
+
+5. **Commit (green)**
+   - Stage all changed production files
+   - Commit with message (replace XXXX with the actual ticket number from the spec file): `FHR-XXXX: implement <task name> (green)`
+
+6. **Refactor**
+   - Remove duplication, clarify intent, simplify structure
+   - Do NOT change behaviour; no new logic, no new tests
+   - Do NOT modify test code
+   - Run all tests; they must remain green. In case of any failure, stop immediately and ask the user what to do next (rollback; make the test pass; ...)
+
+7. **Mark task done**
+   - In the spec file, check off `- [x] Production code` for the completed task
+
+8. **Commit (refactor)**
+   - Stage all changed production files and the updated spec file
+   - Commit with message (replace XXXX with the actual ticket number from the spec file): `FHR-XXXX: refactor <task name> (refactor)`
+## Constraints
+
+- Do NOT modify test code
+- Do NOT advance past the first incomplete task
+- Write the minimum code needed to make tests pass

package/teams/fhr-core/skills/tdd-red/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: tdd-red
+description: Write failing tests (red phase) for the next incomplete task in a spec file's Design and Implementation Plan — acceptance tests (JGiven BDD) and unit tests (JUnit Jupiter) — then mark the Acceptance tests and Unit tests sub-tasks done and commit. Use when user references a spec file and wants to write the failing tests before implementing a feature, or says "red phase", "write tests", or "tdd red".
+arguments: spec-file
+---
+
+# TDD Red
+
+Writes the failing tests for the next incomplete task in the plan. Run after `/plan-spec`.
+
+## Quick start
+
+```
+/tdd-red suggest-docs/src/main/docs/plans/FHR-XXXX-feature-name.md
+```
+
+## Workflow
+
+1. **Load context**
+    - Read the spec file passed as argument
+    - Read `glossary.md` from the project root for ubiquitous language
+    - Read `coding-guidelines.md` from the project root for test conventions
+
+2. **Find the next incomplete task**
+    - Scan the `## Design and Implementation Plan` section for the first task whose `- [ ] Acceptance tests` or `- [ ] Unit tests` checkbox is unchecked
+    - Work on that task only — do not advance to subsequent tasks
+
+3. **Write the tests**
+    - Write acceptance tests (JGiven BDD style) and unit tests (JUnit Jupiter) as described for that task in the plan
+    - Follow all conventions in `coding-guidelines.md`: EasyMock for mocking, stage classes named `Given*`/`When*`/`Then*`, test methods named as scenario descriptions
+    - Use only domain terms from `glossary.md`
+    - This is the **red phase**: write only tests, no production code
+
+4. **Run the tests**
+    - Run unit tests
+    - Run acceptance tests (JGiven)
+    - Confirm the suite is red (fails) before proceeding
+
+5. **Mark task done**
+    - In the spec file, check off `- [x] Acceptance tests` and `- [x] Unit tests` for the completed task
+
+6. **Commit**
+    - Stage all new test files and the updated spec file
+    - Commit with message (replace XXXX with the actual ticket number from the spec file): `FHR-XXXX: add failing tests for <task name> (red)`
+
+## Constraints
+
+- Do NOT write any production code
+- Do NOT advance past the first incomplete task
+- Use only ubiquitous language from the glossary

package/teams/fhr-core/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: tdd-workflow
+description: Drive the full red-green-refactor TDD cycle across every task in a spec file's Design and Implementation Plan — picking the next incomplete task, then running the red, green, and refactor phases for it, then looping to the next task until the plan is complete. Use when user references a spec file and wants to implement the whole plan end to end, or says "run the tdd workflow", "implement the plan", or "tdd workflow".
+arguments: spec-file
+---
+
+# TDD Workflow
+
+Automates the per-task red → green → refactor cycle for an entire plan by orchestrating the
+`tdd-red` and `tdd-green` skills. Run after `/plan-spec`.
+
+## Quick start
+
+```
+/tdd-workflow suggest-docs/src/main/docs/plans/FHR-XXXX-feature-name.md
+```
+
+## Workflow
+
+1. **Load context**
+   - Read the spec file passed as argument
+   - Locate the `## Design and Implementation Plan` section and its list of `### Task:` blocks
+
+2. **Pick the next task**
+   - Find the first `### Task:` whose checkboxes are not all checked
+     (`- [ ] Acceptance tests`, `- [ ] Unit tests`, `- [ ] Production code`)
+   - This task is the current task. If every task is fully checked, stop; the plan is complete
+
+3. **Red phase (if needed)**
+   - If `Acceptance tests` or `Unit tests` is unchecked for the current task, invoke `tdd-red` with the spec file
+   - Wait for it to finish before continuing
+
+4. **Green/Refactor phase (if needed)**
+   - If `Production code` is unchecked for the current task, invoke `tdd-green` with the spec file
+   - Wait for it to finish before continuing
+
+5. **Loop to the next task**
+   - Re-read the spec file and return to step 2
+   - Continue until no incomplete task remains
+
+6. **Report**
+   - Summarise which tasks were implemented and confirm the plan is fully checked off
+
+## Constraints
+
+- Always run the phases in order (red before green/refactor) for a given task
+- Do NOT start the next task until the current one is fully complete
+- If a phase’s checkbox is already checked for the current task, treat that phase as already complete (do not re-run it)
+- Let each sub-skill enforce its own rules (tests-only in red, minimal code + refactor in green); this skill only sequences them
+- Each invoked sub-skill commits its own work; do not add extra commits between skill invocations
+- Stop and surface the problem if any phase fails (e.g. tests will not pass) rather than advancing

package/teams/snpd/skills/README.md

@@ -0,0 +1,306 @@
+# SNPD Team — SDLC Skills
+
+A set of explicitly-invoked skills that walk a code change through the full
+software-development lifecycle — from a Jira ticket to a draft pull request —
+with a clean, auditable artifact at every step.
+
+Each skill does **one** job, hands off a file, and **stops**. Nothing runs
+automatically; every command must be explicitly invoked (`/jira-spec`,
+`/draft-plan`, etc.). The human stays in control of every transition, and each
+stage leaves a durable artifact the next stage reads.
+
+---
+
+## The Pipeline
+
+```
+   Jira ticket
+       │
+       ▼
+┌──────────────┐   writes    .claude/artifacts/{KEY}_{slug}-spec.md
+│  jira-spec   │ ──────────▶  (verbatim ticket + AI repo context)
+└──────────────┘
+       │
+       ▼
+┌──────────────┐   reads spec, discusses, writes on approval
+│  draft-plan  │ ──────────▶  .claude/artifacts/{KEY}_{slug}-plan.md
+└──────────────┘              (high-level plan, no code)
+       │
+       ▼
+┌──────────────────┐  reads plan, branch + strict TDD, local commits
+│  tdd-implement   │ ─────▶   feature branch {KEY}-{slug}
+└──────────────────┘          + appends Impl Details / Post-Mortem to plan
+       │
+       ▼
+┌──────────────────┐  3 LLM models review the diff, vote on findings
+│ council-review   │ ─────▶   consensus-ranked review (in chat)
+└──────────────────┘
+       │
+       ▼
+┌──────────────┐  pushes branch, opens DRAFT PR on GitHub
+│  draft-pr    │ ─────▶  draft pull request
+└──────────────┘
+
+       ┌─────────────┐
+       │  docs-init   │  (independent — runs on any repo at any time)
+       └─────────────┘
+```
+
+The first five skills form a **linear pipeline** where each stage's output
+becomes the next stage's input. `docs-init` is **independent** and can be run
+on any repo to initialize or refresh project documentation.
+
+---
+
+## Skills
+
+### 1. `jira-spec` — Capture the ticket
+
+| | |
+|---|---|
+| **Trigger** | `/jira-spec S4R-1234` or a Jira URL |
+| **Reads** | Jira ticket (via Atlassian MCP, go-jira CLI, or curl) |
+| **Produces** | `.claude/artifacts/{KEY}_{slug}-spec.md` |
+| **Stops before** | Planning |
+
+Fetches a Jira ticket and writes a development spec. The spec preserves the
+original ticket description **verbatim** (for audit) and adds AI-gathered
+repo context (touch points, patterns, test surface) from a **medium-depth**
+repo scan. If Jira is unreachable, the skill refuses to proceed — it never
+fabricates ticket content.
+
+**Key rules:**
+- Verbatim means verbatim — no paraphrasing the Jira description
+- One spec file per ticket
+- No invented metadata or acceptance criteria
+- Does not start coding or planning
+
+---
+
+### 2. `draft-plan` — Decide the approach
+
+| | |
+|---|---|
+| **Trigger** | `/draft-plan S4R-1234` or path to spec file |
+| **Reads** | `…-spec.md` from `.claude/artifacts/` |
+| **Produces** | `.claude/artifacts/{KEY}_{slug}-plan.md` |
+| **Stops before** | Implementation |
+
+Turns a spec into a discussed, approved, high-level implementation plan.
+Performs a **deep** codebase review (deeper than jira-spec) — reads relevant
+files end-to-end, traces data flow across layers, checks architecture and
+conventions docs. Presents the plan in chat (Goal, Approach, Affected areas,
+Sequencing, Test strategy, Risks, Out of scope) and **discusses it with the
+user** before writing.
+
+**Key rules:**
+- High-level by default — no line numbers, no code snippets
+- Every cited file path is verified to exist in the repo
+- The plan must trace back to the spec's acceptance criteria
+- Only writes the plan file on explicit user approval
+- Never starts implementation
+
+---
+
+### 3. `tdd-implement` — Build with strict TDD
+
+| | |
+|---|---|
+| **Trigger** | `/tdd-implement S4R-1234` or path to plan file |
+| **Reads** | `…-plan.md` from `.claude/artifacts/` + `docs/conventions.md`, `docs/architecture.md` |
+| **Produces** | Feature branch `{KEY}-{slug}` with squashed commit; plan file updated with Implementation Details + Post-Mortem |
+| **Stops before** | Push / PR |
+
+Implements an approved plan using strict, phase-bound TDD on a feature
+branch. For each phase: writes failing tests → commits → implements until
+green → commits. Supports resuming interrupted sessions. Runs the project's
+full verification gate before declaring completion.
+
+**Key rules:**
+- Never assumes the default branch is `main` — detects dynamically
+- Strict TDD per phase (never batch tests up-front)
+- Every commit message starts with `{KEY}:`
+- Discoveries classified as trivial/plan-affecting/spec-affecting with
+  appropriate handling
+- Never pushes, never opens a PR
+- Squash via `git reset --soft`, not interactive rebase
+
+---
+
+### 4. `council-review` — Multi-model review before the PR
+
+| | |
+|---|---|
+| **Trigger** | `/council-review`, "council review my changes", "multi-model review" |
+| **Reads** | The diff (local changes, staged, branch, last N commits, or a PR) + repo config/conventions |
+| **Produces** | A single consensus-ranked review **in chat** (no file artifact) |
+| **Stops before** | Pushing / opening a PR |
+
+Runs a high-signal, consensus-driven code review by spawning **three
+independent `code-review` sub-agents on different LLM models**
+(`claude-opus-4.8`, `gpt-5.3-codex`, `gpt-5.5`) — inspired by
+[Karpathy's LLM Council](https://github.com/karpathy/llm-council). All three
+get the **identical** prompt and diff, then their findings are deduplicated,
+scored by agreement (🟢 unanimous / 🟡 majority / 🔵 solo), and ranked by
+agreement then severity. Different models catch different things, so requiring
+consensus drops noise and raises signal.
+
+This is the **quality gate between `tdd-implement` and `draft-pr`**: review the
+implemented diff, address the findings, then open the draft PR with confidence.
+
+**Key rules:**
+- Identical prompts for all reviewers — fair comparison is the whole point
+- No model bias — agreement count is the only ranking signal
+- Always launches all 3 agents in parallel, never sequentially
+- Always shows which models agreed on each finding (transparency)
+- Never generates hallucinated replacement code during synthesis
+- On severity disagreement, uses the highest severity any reviewer assigned
+
+---
+
+### 5. `draft-pr` — Open the draft PR
+
+| | |
+|---|---|
+| **Trigger** | `/draft-pr` |
+| **Reads** | Plan file (preferred), spec file (for AC), or commit history (fallback) |
+| **Produces** | Draft pull request on GitHub |
+| **Stops before** | Marking ready / assigning reviewers |
+
+Pushes the current branch and opens a **draft** pull request on GitHub.
+Resolves the PR template (`.github/PULL_REQUEST_TEMPLATE.md`), derives
+content from the plan and spec files, shows a full preview for confirmation,
+then pushes (fast-forward only) and creates the draft PR.
+
+**Key rules:**
+- Always `--draft` — never marks the PR ready
+- Shows a full preview before any push or PR creation
+- Leaves all template `- [ ]` checkboxes unchecked
+- Never assigns reviewers, labels, or milestones
+- Never force-pushes
+- Never invents acceptance criteria or test results
+
+---
+
+### 6. `docs-init` — Initialize or refresh project docs
+
+| | |
+|---|---|
+| **Trigger** | `/docs-init` or "update the docs", "refresh project documentation" |
+| **Reads** | The entire repo (build files, source, CI, deploy configs, etc.) |
+| **Produces** | `README.md`, `CLAUDE.md`, and `docs/` folder (architecture, local-setup, conventions, operations, decisions) |
+| **Stops before** | Writing anything — presents an audit report first |
+
+Initializes or refreshes the canonical documentation structure. Works in
+two modes:
+
+- **Init mode** — `docs/` is missing or incomplete. Drafts all seven
+  canonical files from a fresh repo scan.
+- **Refresh mode** — `docs/` exists. Audits each file for outdated content,
+  drift, and new opportunities.
+
+Includes a **verification checklist** — every command, config key, directory
+description, and workflow trigger is confirmed against actual source files
+before inclusion. Presents a human-readable audit report and applies changes
+only after explicit user approval.
+
+**Key rules:**
+- Never writes files before user approval
+- `decisions.md` is append-only
+- Preserves `> **Scope:**` blocks on every edit
+- Verifies every factual claim against source
+- `CLAUDE.md` ≤ 40 lines, `README.md` ≤ 30 lines
+
+---
+
+## How the Skills Connect
+
+### Artifact Flow
+
+```
+Jira Ticket
+    │
+    │  /jira-spec
+    ▼
+{KEY}_{slug}-spec.md          ◄── verbatim ticket + shallow repo context
+    │
+    │  /draft-plan
+    ▼
+{KEY}_{slug}-plan.md          ◄── approved high-level plan
+    │
+    │  /tdd-implement
+    ├──▶ feature branch       ◄── squashed commit with code changes
+    ▼
+{KEY}_{slug}-plan.md          ◄── updated with Implementation Details + Post-Mortem
+    │
+    │  /council-review
+    ▼
+Consensus review (in chat)    ◄── 3 models vote; address findings before the PR
+    │
+    │  /draft-pr
+    ▼
+Draft Pull Request            ◄── body sourced from plan + spec
+```
+
+All spec and plan artifacts live in `.claude/artifacts/` within the repo,
+using a consistent naming convention: `{KEY}_{slug}-spec.md` →
+`{KEY}_{slug}-plan.md`. The `-spec` and `-plan` suffixes are mandatory.
+
+### Separation of Concerns
+
+| Boundary | Meaning |
+|---|---|
+| Spec ≠ Plan | The spec records *what the ticket asks*; the plan decides *how to build it* |
+| Plan ≠ Code | The plan describes the approach at the level of files and phases — no code |
+| Build ≠ Ship | Implementation produces a local branch only — no push, no PR |
+| Code ≠ Review | The council reviews the diff and surfaces findings — it never edits code or ships |
+| PR ≠ Merge | The PR is always a *draft* — marking ready is the human's call |
+
+Each boundary is a **human checkpoint**. No skill silently rolls into the
+next. Approval at one stage authorizes *only* that stage's output.
+
+### docs-init Integration
+
+`docs-init` is not part of the linear pipeline but supports it:
+
+- **draft-plan** reads `docs/architecture.md`, `docs/conventions.md`, and
+  `docs/decisions.md` during its deep codebase review.
+- **tdd-implement** loads `docs/conventions.md` and `docs/architecture.md`
+  before writing any code, and references them for style and patterns.
+- **tdd-implement** may suggest entries for `docs/decisions.md` in its
+  Post-Mortem section (but never writes them directly).
+
+Running `/docs-init` on a repo before starting the pipeline ensures the
+plan and implementation stages have reliable documentation to reference.
+
+---
+
+## Typical End-to-End Run
+
+```bash
+/jira-spec S4R-10453            # → S4R-10453_mongo-cluster-routing-spec.md
+/draft-plan S4R-10453           # discuss → approve → …-plan.md
+/tdd-implement S4R-10453        # branch + TDD + squash; plan updated
+/council-review                 # 3-model review of the diff; address findings
+/draft-pr                       # confirm → draft PR on GitHub
+```
+
+---
+
+## Conventions Shared Across All Skills
+
+- **Explicit invocation only.** None auto-trigger on keywords.
+- **Artifacts live in the repo.** All specs and plans go to
+  `.claude/artifacts/`, never `~/.claude/`.
+- **Each stage stops at a human checkpoint.** No skill silently continues
+  into the next.
+- **No fabrication.** Ticket text, acceptance criteria, file paths, and test
+  results are verified or quoted — never invented.
+- **Source control hygiene.** Commits start with the Jira key (`{KEY}: …`).
+
+---
+
+## Also in This Folder
+
+- `../github/PULL_REQUEST_TEMPLATE.md` — the SNPD team's PR template,
+  used by `draft-pr` when resolving templates.