aped-method 1.9.0 → 2.0.1

package/README.md

@@ -0,0 +1,229 @@
+# APED Method
+
+Zero-dependency CLI that scaffolds a complete dev pipeline into any [Claude Code](https://claude.ai/download) project.
+
+```
+npx aped-method
+```
+
+```
+     █████╗ ██████╗ ███████╗██████╗
+    ██╔══██╗██╔══██╗██╔════╝██╔══██╗
+    ███████║██████╔╝█████╗  ██║  ██║
+    ██╔══██║██╔═══╝ ██╔══╝  ██║  ██║
+    ██║  ██║██║     ███████╗██████╔╝
+    ╚═╝  ╚═╝╚═╝     ╚══════╝╚═════╝
+          M  E  T  H  O  D
+
+    Analyze → PRD → UX → Epics → Dev → Review
+```
+
+## What it does
+
+APED turns Claude Code into a disciplined dev pipeline. Instead of "code me an app", you get:
+
+1. **Analyze** — 3 parallel research agents (market, domain, technical) produce a product brief
+2. **PRD** — Autonomous generation with numbered FRs, validation scripts, domain detection
+3. **UX** — ANF framework: Assemble design DNA, Normalize with a live React prototype, Fill all screens with user validation
+4. **Epics** — Stories with ACs in Given/When/Then, FR coverage validation, ticket system integration
+5. **Dev** — TDD red-green-refactor with 5-condition gate, parallel agents for context gathering
+6. **Review** — Adversarial code review with minimum 3 findings, parallel agents (code-explorer + code-reviewer)
+
+A guardrail hook blocks you from skipping steps. A state machine tracks progress. Everything chains automatically.
+
+## Quick start
+
+```bash
+cd your-project
+npx aped-method
+```
+
+Interactive prompts ask for project name, author, languages, ticket system, and git provider. Or go non-interactive:
+
+```bash
+npx aped-method --yes --project=my-app --author=Jane --lang=french --tickets=linear --git=github
+```
+
+Then open Claude Code:
+
+```
+/aped-a    # Start with analysis
+/aped-all  # Or run the full pipeline
+```
+
+## Pipeline commands
+
+| Command | Phase | What it produces |
+|---------|-------|-----------------|
+| `/aped-a` | Analyze | Product brief from 3 parallel research agents |
+| `/aped-p` | PRD | PRD with numbered FRs/NFRs, validated by script |
+| `/aped-ux` | UX | Live React prototype (Vite), design spec, component catalog |
+| `/aped-e` | Epics | Stories with ACs, tasks, FR coverage map |
+| `/aped-d` | Dev | TDD implementation with 5-condition gate |
+| `/aped-r` | Review | Adversarial review, minimum 3 findings |
+
+## Utility commands
+
+| Command | What it does |
+|---------|-------------|
+| `/aped-s` | Sprint status dashboard — progress, blockers, next actions |
+| `/aped-c` | Correct course — manage scope changes with impact analysis |
+| `/aped-ctx` | Brownfield analysis — generate project context from existing code |
+| `/aped-qa` | Generate E2E and integration tests from acceptance criteria |
+| `/aped-quick` | Quick fix/feature bypassing the full pipeline |
+| `/aped-all` | Run the full pipeline A→P→UX→E→D→R with auto-resume |
+
+## What gets scaffolded
+
+```
+.aped/                              # Engine (immutable after install)
+├── config.yaml                     # Project settings, integrations
+├── hooks/guardrail.sh              # Pipeline coherence hook
+├── templates/                      # Document templates (brief, PRD, epics, story, quick-spec)
+├── aped-a/                         # Analyze skill
+│   ├── SKILL.md
+│   ├── scripts/validate-brief.sh
+│   └── references/research-prompts.md
+├── aped-p/                         # PRD skill
+│   ├── SKILL.md
+│   ├── scripts/validate-prd.sh
+│   └── references/fr-rules.md, *.csv
+├── aped-ux/                        # UX skill (ANF framework)
+│   ├── SKILL.md
+│   ├── scripts/validate-ux.sh
+│   └── references/ux-patterns.md   # 99 priority-ranked UX rules
+├── aped-e/                         # Epics skill
+│   ├── SKILL.md
+│   ├── scripts/validate-coverage.sh
+│   └── references/epic-rules.md
+├── aped-d/                         # Dev skill
+│   ├── SKILL.md
+│   ├── scripts/run-tests.sh
+│   └── references/tdd-engine.md, ticket-git-workflow.md
+├── aped-r/                         # Review skill
+│   ├── SKILL.md
+│   ├── scripts/git-audit.sh
+│   └── references/review-criteria.md
+├── aped-s/                         # Status dashboard
+│   ├── SKILL.md
+│   └── references/status-format.md
+├── aped-c/                         # Correct course
+│   ├── SKILL.md
+│   └── references/scope-change-guide.md
+├── aped-ctx/                       # Brownfield context
+│   ├── SKILL.md
+│   └── references/analysis-checklist.md
+├── aped-qa/                        # QA tests
+│   ├── SKILL.md
+│   └── references/test-patterns.md
+├── aped-quick/SKILL.md             # Quick fix
+└── aped-all/SKILL.md               # Orchestrator
+
+docs/aped/                          # Output (evolves during project)
+├── state.yaml                      # Pipeline state machine
+├── product-brief.md                # From /aped-a
+├── prd.md                          # From /aped-p
+├── ux/                             # From /aped-ux
+│   ├── design-spec.md
+│   ├── screen-inventory.md
+│   ├── components.md
+│   └── flows.md
+├── epics.md                        # From /aped-e
+├── stories/                        # One file per story
+└── quick-specs/                    # From /aped-quick
+
+.claude/
+├── commands/aped-*.md              # 12 slash commands
+└── settings.local.json             # Guardrail hook config
+```
+
+## Integrations
+
+### Ticket systems
+
+Configure during install or via `--tickets=`:
+
+| Provider | Commit format | Auto-link |
+|----------|--------------|-----------|
+| `linear` | `feat(TEAM-XX): description` | `Part of TEAM-XX` / `Fixes TEAM-XX` |
+| `jira` | `feat(PROJ-XX): description` | Smart commits |
+| `github-issues` | `feat(#XX): description` | `Closes #XX` / `Fixes #XX` |
+| `gitlab-issues` | `feat(#XX): description` | `Closes #XX` |
+| `none` | `feat: description` | — |
+
+### Git providers
+
+Configure via `--git=`:
+
+| Provider | PR/MR creation | Branch strategy |
+|----------|---------------|-----------------|
+| `github` | `gh pr create` | `feature/{ticket}-{slug}` |
+| `gitlab` | `glab mr create` | `feature/{ticket}-{slug}` |
+| `bitbucket` | Web UI | `feature/{ticket}-{slug}` |
+
+## UX phase — ANF framework
+
+The `/aped-ux` skill produces a live React prototype, not wireframes:
+
+- **Assemble** — Collect design DNA: user inspirations, UI library (shadcn, MUI, Radix...), design tokens, branding
+- **Normalize** — Scaffold Vite+React app with real PRD content (no lorem ipsum), working navigation, all screens
+- **Fill** — Complete interaction states, responsive (3 breakpoints), dark mode, accessibility, then user review cycles until approved
+
+The approved prototype becomes the UX spec that `/aped-e` consumes. Includes 99 priority-ranked UX rules and a pre-delivery checklist.
+
+## Guardrail hook
+
+Every prompt is intercepted by `guardrail.sh` which checks pipeline coherence:
+
+| Situation | Reaction |
+|-----------|----------|
+| Coding without epics | Warns: run A→P→E first |
+| PRD without brief | Warns: run /aped-a first |
+| Modifying PRD during dev | Warns: use /aped-c for scope changes |
+| Quick fix request | Bypasses (that's what /aped-quick is for) |
+
+The hook injects context — it doesn't block. Claude explains the issue and asks for confirmation.
+
+## Install / Update / Fresh
+
+```bash
+# First install
+npx aped-method
+
+# Re-run on existing project → auto-detects, offers:
+#   1. Update engine (preserve config + artifacts)
+#   2. Fresh install (delete everything, start over)
+#   3. Cancel
+
+# Non-interactive
+npx aped-method --yes              # Auto-update if exists
+npx aped-method --yes --update     # Explicit update
+npx aped-method --yes --fresh      # Nuke and redo
+
+# Version check
+npx aped-method --version          # Shows current version
+# If installed version < CLI version → "Upgrade available: v1.x → v2.x"
+```
+
+## Anthropic Skills Guide compliance
+
+All 12 skills follow the [Complete Guide to Building Skills for Claude](https://www.anthropic.com/engineering/claude-skills-guide):
+
+- YAML frontmatter with name, description (WHAT + WHEN + negative triggers), license, metadata
+- Progressive disclosure: frontmatter → SKILL.md body → references/
+- `disable-model-invocation: true` on side-effect skills (dev, review, correct, all)
+- `allowed-tools` restrictions on read-only skills (status, context)
+- Critical Rules section at top of pipeline skills
+- Examples and Common Issues in every skill
+- Validation scripts with clear exit codes
+- Skill tool chaining (not slash notation)
+- Third-person descriptions, <1024 chars, no XML tags
+
+## Requirements
+
+- [Claude Code](https://claude.ai/download)
+- Node.js 18+
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aped-method",
-  "version": "1.9.0",
+  "version": "2.0.1",
   "type": "module",
   "description": "Scaffold the APED pipeline (Analyze, PRD, Epics, Dev, Review) into any Claude Code project",
   "bin": {

package/src/templates/guardrail.js

@@ -7,85 +7,86 @@ export function guardrail(c) {
       executable: true,
       content: `#!/usr/bin/env bash
 # APED Guardrail — UserPromptSubmit hook
-# Validates prompt coherence against pipeline state, existing artifacts, and memories.
-# Returns JSON with "decision" and optionally "addToPrompt" to inject context.
+# Uses the official Claude Code hook output format.
+# See: https://code.claude.com/docs/hooks
 
-set -euo pipefail
+# NOT using set -e or pipefail — grep returns exit 1 on no match
+# which would kill the script. We handle errors explicitly.
 
-PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-STATE_FILE="$PROJECT_ROOT/${o}/state.yaml"
-CONFIG_FILE="$PROJECT_ROOT/${a}/config.yaml"
-OUTPUT_DIR="$PROJECT_ROOT/${o}"
+# ── Read stdin JSON ──
+INPUT=$(cat < /dev/stdin)
 
-# Read stdin (JSON: {"session_id":"...","prompt":"..."})
-INPUT=$(cat)
-PROMPT=$(echo "$INPUT" | grep -o '"prompt":"[^"]*"' | sed 's/"prompt":"//;s/"$//' || echo "")
+# Extract prompt using simple string parsing (no jq dependency)
+PROMPT=""
+if command -v jq &>/dev/null; then
+  PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || echo "")
+else
+  PROMPT=$(echo "$INPUT" | grep -o '"prompt":"[^"]*"' | sed 's/"prompt":"//;s/"$//' 2>/dev/null || echo "")
+fi
 
 # If no prompt or empty, allow
 if [[ -z "$PROMPT" ]]; then
   exit 0
 fi
 
+# ── Resolve paths ──
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+STATE_FILE="$PROJECT_ROOT/${o}/state.yaml"
+CONFIG_FILE="$PROJECT_ROOT/${a}/config.yaml"
+OUTPUT_DIR="$PROJECT_ROOT/${o}"
+
 # ── Read current phase from state.yaml ──
 CURRENT_PHASE="none"
 if [[ -f "$STATE_FILE" ]]; then
-  CURRENT_PHASE=$(grep 'current_phase:' "$STATE_FILE" | sed 's/.*current_phase:[[:space:]]*"\\{0,1\\}\\([^"]*\\)"\\{0,1\\}/\\1/' | tr -d ' ' || echo "none")
+  PHASE_LINE=$(grep 'current_phase:' "$STATE_FILE" 2>/dev/null || echo "")
+  if [[ -n "$PHASE_LINE" ]]; then
+    CURRENT_PHASE=$(echo "$PHASE_LINE" | sed 's/.*current_phase:[[:space:]]*//;s/"//g;s/^[[:space:]]*//;s/[[:space:]]*$//' || echo "none")
+  fi
 fi
 
 # ── Read communication language from config ──
-LANG="english"
+COMM_LANG="english"
 if [[ -f "$CONFIG_FILE" ]]; then
-  LANG=$(grep 'communication_language:' "$CONFIG_FILE" | sed 's/.*communication_language:[[:space:]]*//' | tr -d ' ' || echo "english")
+  LANG_LINE=$(grep 'communication_language:' "$CONFIG_FILE" 2>/dev/null || echo "")
+  if [[ -n "$LANG_LINE" ]]; then
+    COMM_LANG=$(echo "$LANG_LINE" | sed 's/.*communication_language:[[:space:]]*//' | tr -d ' ' || echo "english")
+  fi
 fi
 
-# ── Detect what the user is trying to do ──
+# ── Detect intent from prompt ──
 PROMPT_LOWER=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]')
 
-# Detect APED command invocations
 WANTS_ANALYZE=false
 WANTS_PRD=false
 WANTS_EPICS=false
 WANTS_DEV=false
 WANTS_REVIEW=false
 WANTS_ALL=false
-WANTS_CODE=false
-
-[[ "$PROMPT_LOWER" =~ (aped-a|/aped-a|analyze|analyse|research) ]] && WANTS_ANALYZE=true
-[[ "$PROMPT_LOWER" =~ (aped-p|/aped-p|prd|product.req) ]] && WANTS_PRD=true
-[[ "$PROMPT_LOWER" =~ (aped-e|/aped-e|epic|stories|story) ]] && WANTS_EPICS=true
-[[ "$PROMPT_LOWER" =~ (aped-d|/aped-d|dev|implement|code|build|create.*component|create.*service) ]] && WANTS_DEV=true
-[[ "$PROMPT_LOWER" =~ (aped-r|/aped-r|review|audit) ]] && WANTS_REVIEW=true
-[[ "$PROMPT_LOWER" =~ (aped-all|/aped-all|full.pipeline|start.from.scratch) ]] && WANTS_ALL=true
 WANTS_QUICK=false
+WANTS_CODE=false
 
-[[ "$PROMPT_LOWER" =~ (aped-quick|/aped-quick|quick.fix|quick.feature|hotfix) ]] && WANTS_QUICK=true
-[[ "$PROMPT_LOWER" =~ (code|implement|write.*function|create.*file|add.*feature|fix.*bug|refactor) ]] && WANTS_CODE=true
+echo "$PROMPT_LOWER" | grep -qE '(aped-a|/aped-a|analyze|analyse|research)' && WANTS_ANALYZE=true
+echo "$PROMPT_LOWER" | grep -qE '(aped-p|/aped-p|prd|product.req)' && WANTS_PRD=true
+echo "$PROMPT_LOWER" | grep -qE '(aped-e|/aped-e|epic|stories|story)' && WANTS_EPICS=true
+echo "$PROMPT_LOWER" | grep -qE '(aped-d|/aped-d|dev|implement|build|create.*component|create.*service)' && WANTS_DEV=true
+echo "$PROMPT_LOWER" | grep -qE '(aped-r|/aped-r|review|audit)' && WANTS_REVIEW=true
+echo "$PROMPT_LOWER" | grep -qE '(aped-all|/aped-all|full.pipeline|start.from.scratch)' && WANTS_ALL=true
+echo "$PROMPT_LOWER" | grep -qE '(aped-quick|/aped-quick|quick.fix|quick.feature|hotfix)' && WANTS_QUICK=true
+echo "$PROMPT_LOWER" | grep -qE '(code|implement|write.*function|create.*file|add.*feature|fix.*bug|refactor)' && WANTS_CODE=true
 
 # ── Check artifact existence ──
 HAS_BRIEF=false
 HAS_PRD=false
 HAS_EPICS=false
 
-[[ -n "$(find "$OUTPUT_DIR" -name '*brief*' -o -name '*product-brief*' 2>/dev/null | head -1)" ]] && HAS_BRIEF=true
-[[ -n "$(find "$OUTPUT_DIR" -name '*prd*' 2>/dev/null | head -1)" ]] && HAS_PRD=true
-[[ -n "$(find "$OUTPUT_DIR" -name '*epic*' 2>/dev/null | head -1)" ]] && HAS_EPICS=true
+if [[ -d "$OUTPUT_DIR" ]]; then
+  test -n "$(find "$OUTPUT_DIR" -maxdepth 1 -name '*brief*' 2>/dev/null | head -1)" && HAS_BRIEF=true
+  test -n "$(find "$OUTPUT_DIR" -maxdepth 1 -name '*prd*' 2>/dev/null | head -1)" && HAS_PRD=true
+  test -n "$(find "$OUTPUT_DIR" -maxdepth 1 -name '*epic*' 2>/dev/null | head -1)" && HAS_EPICS=true
+fi
 
 # ── Phase-aware guardrail logic ──
-WARNINGS=()
-
-# Phase transition map: none → analyze → prd → ux → epics → dev ↔ review → done
-PHASE_ORDER="none analyze prd ux epics dev review done"
-
-phase_index() {
-  local i=0
-  for p in $PHASE_ORDER; do
-    [[ "$p" == "$1" ]] && echo "$i" && return
-    i=$((i + 1))
-  done
-  echo "0"
-}
-
-CURRENT_IDX=$(phase_index "$CURRENT_PHASE")
+WARNINGS=""
 
 # Rule 0: Quick mode bypasses pipeline checks
 if [[ "$WANTS_QUICK" == "true" ]]; then
@@ -95,65 +96,66 @@ fi
 # Rule 1: Trying to code without epics/stories
 if [[ "$WANTS_CODE" == "true" || "$WANTS_DEV" == "true" ]] && [[ "$CURRENT_PHASE" != "dev" && "$CURRENT_PHASE" != "review" ]]; then
   if [[ "$HAS_EPICS" == "false" ]]; then
-    WARNINGS+=("SKIP_DETECTED: Attempting dev/code without epics. Current phase: $CURRENT_PHASE. Run /aped-a → /aped-p → /aped-e first.")
+    WARNINGS="$WARNINGS\\nSKIP_DETECTED: Attempting dev/code without epics. Current phase: $CURRENT_PHASE. Run /aped-a, /aped-p, /aped-e first."
   elif [[ "$HAS_PRD" == "false" ]]; then
-    WARNINGS+=("SKIP_DETECTED: Attempting dev/code without PRD. Current phase: $CURRENT_PHASE. Run /aped-a → /aped-p first.")
+    WARNINGS="$WARNINGS\\nSKIP_DETECTED: Attempting dev/code without PRD. Current phase: $CURRENT_PHASE. Run /aped-a, /aped-p first."
   fi
 fi
 
 # Rule 2: PRD without brief
 if [[ "$WANTS_PRD" == "true" ]] && [[ "$HAS_BRIEF" == "false" ]] && [[ "$CURRENT_PHASE" != "prd" ]]; then
-  WARNINGS+=("MISSING_ARTIFACT: No product brief found. Run /aped-a first to generate the brief.")
+  WARNINGS="$WARNINGS\\nMISSING_ARTIFACT: No product brief found. Run /aped-a first."
 fi
 
 # Rule 3: Epics without PRD
 if [[ "$WANTS_EPICS" == "true" ]] && [[ "$HAS_PRD" == "false" ]]; then
-  WARNINGS+=("MISSING_ARTIFACT: No PRD found. Run /aped-p first to generate the PRD.")
+  WARNINGS="$WARNINGS\\nMISSING_ARTIFACT: No PRD found. Run /aped-p first."
 fi
 
 # Rule 4: Review without dev
 if [[ "$WANTS_REVIEW" == "true" ]] && [[ "$CURRENT_PHASE" != "dev" && "$CURRENT_PHASE" != "review" ]]; then
-  WARNINGS+=("PREMATURE_REVIEW: No story has been developed yet. Run /aped-d first.")
+  WARNINGS="$WARNINGS\\nPREMATURE_REVIEW: No story developed yet. Run /aped-d first."
 fi
 
-# Rule 5: Trying to modify upstream artifacts during dev
+# Rule 5: Modifying upstream during dev
 if [[ "$CURRENT_PHASE" == "dev" || "$CURRENT_PHASE" == "review" ]]; then
   if [[ "$WANTS_PRD" == "true" || "$WANTS_ANALYZE" == "true" ]]; then
-    WARNINGS+=("SCOPE_CHANGE: You are in phase '$CURRENT_PHASE'. Modifying the PRD/brief now will invalidate existing epics and stories. Use /aped-r with correct-course protocol instead.")
+    WARNINGS="$WARNINGS\\nSCOPE_CHANGE: Phase is '$CURRENT_PHASE'. Modifying PRD/brief invalidates epics and stories. Use /aped-c instead."
   fi
 fi
 
 # Rule 6: Skipping phases
-if [[ "$WANTS_DEV" == "true" ]] && [[ "$CURRENT_IDX" -lt 3 ]] && [[ "$WANTS_ALL" == "false" ]]; then
+if [[ "$WANTS_DEV" == "true" ]] && [[ "$WANTS_ALL" == "false" ]]; then
   if [[ "$CURRENT_PHASE" == "none" || "$CURRENT_PHASE" == "analyze" ]]; then
-    WARNINGS+=("PHASE_SKIP: Jumping from '$CURRENT_PHASE' to dev skips critical pipeline steps. The pipeline ensures quality: Analyze → PRD → Epics → Dev.")
+    WARNINGS="$WARNINGS\\nPHASE_SKIP: Jumping from '$CURRENT_PHASE' to dev skips critical steps. Pipeline: Analyze -> PRD -> Epics -> Dev."
   fi
 fi
 
-# ── Build response ──
-if [[ \${#WARNINGS[@]} -eq 0 ]]; then
-  # No issues, allow silently
+# ── No warnings = allow silently ──
+if [[ -z "$WARNINGS" ]]; then
   exit 0
 fi
 
-# Build the addToPrompt context
-CONTEXT="[APED GUARDRAIL — Pipeline Coherence Check]\\n"
-CONTEXT+="Current phase: $CURRENT_PHASE\\n"
-CONTEXT+="Artifacts: brief=\${HAS_BRIEF}, prd=\${HAS_PRD}, epics=\${HAS_EPICS}\\n"
-CONTEXT+="\\nWarnings detected:\\n"
-
-for w in "\${WARNINGS[@]}"; do
-  CONTEXT+="  ⚠ $w\\n"
-done
+# ── Build context for Claude ──
+CONTEXT="[APED GUARDRAIL] Pipeline coherence check.\\nCurrent phase: $CURRENT_PHASE | Artifacts: brief=$HAS_BRIEF, prd=$HAS_PRD, epics=$HAS_EPICS\\nWarnings:$WARNINGS"
 
-if [[ "$LANG" == "french" ]] || [[ "$LANG" == "français" ]]; then
-  CONTEXT+="\\nINSTRUCTION: Signale ces avertissements à l'utilisateur en français AVANT d'exécuter quoi que ce soit. Explique le problème et propose le chemin correct dans le pipeline. Demande confirmation si l'utilisateur veut quand même continuer."
+if [[ "$COMM_LANG" == "french" ]] || [[ "$COMM_LANG" == "français" ]]; then
+  CONTEXT="$CONTEXT\\n\\nINSTRUCTION: Signale ces avertissements a l utilisateur en francais AVANT d executer quoi que ce soit. Explique le probleme et propose le chemin correct. Demande confirmation pour continuer."
 else
-  CONTEXT+="\\nINSTRUCTION: Report these warnings to the user BEFORE executing anything. Explain the issue and suggest the correct pipeline path. Ask for confirmation if the user wants to proceed anyway."
+  CONTEXT="$CONTEXT\\n\\nINSTRUCTION: Report these warnings to the user BEFORE executing anything. Explain the issue and suggest the correct pipeline path. Ask for confirmation to proceed."
 fi
 
-# Output JSON with addToPrompt — does not block, but injects context
-printf '{"addToPrompt": "%s"}' "$CONTEXT"
+# ── Output using official Claude Code hook format ──
+# UserPromptSubmit: use hookSpecificOutput.additionalContext to inject context
+# Does NOT block — injects context so Claude warns the user
+cat << HOOKEOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "$(echo "$CONTEXT" | sed 's/"/\\\\"/g')"
+  }
+}
+HOOKEOF
 `,
     },
     {

package/src/templates/references.js

@@ -66,6 +66,10 @@ export function references(c) {
       path: `${a}/aped-qa/references/test-patterns.md`,
       content: TEST_PATTERNS,
     },
+    {
+      path: `${a}/aped-d/references/ticket-git-workflow.md`,
+      content: TICKET_GIT_WORKFLOW,
+    },
   ];
 }
 
@@ -1111,3 +1115,192 @@ describe("{Endpoint/Service}", () => {
 - **Testing implementation**: Test behavior, not internal structure.
 - **No assertions**: Every test must assert something. \`expect(true).toBe(true)\` is not a test.
 `;
+
+const TICKET_GIT_WORKFLOW = `# Ticket System & Git Provider Integration
+
+Read \`ticket_system\` and \`git_provider\` from config.yaml to adapt all instructions below.
+
+---
+
+## Ticket System Sync Rules
+
+### If ticket_system = "none"
+Skip all ticket references. Use plain commit messages without ticket IDs.
+
+### If ticket_system = "linear"
+
+**BEFORE starting a story:**
+1. Find the corresponding Linear issue
+2. Move issue status to **In Progress**
+3. Use the **Linear-suggested git branch name** (from Linear UI: "Copy git branch name")
+4. Add a comment on the issue: what you're about to implement
+
+**DURING development:**
+- Reference the Linear issue ID in EVERY commit message
+- Use **Linear magic words** for auto-linking:
+  - \`Part of TEAM-XX\` — links without closing (use in intermediate commits)
+  - \`Fixes TEAM-XX\` — links and auto-closes issue on merge
+- Commit format: \`type(TEAM-XX): description\\n\\nPart of TEAM-XX\`
+
+**AFTER completing:**
+1. Create PR with issue ID: \`gh pr create --title "feat(TEAM-XX): Story X.Y - Description" --body "Fixes TEAM-XX"\`
+2. Move issue to **In Review**
+3. After merge: move to **Done**
+4. Update state.yaml to match
+
+### If ticket_system = "jira"
+
+**BEFORE:** Find JIRA issue (PROJ-XX), move to In Progress, use branch: \`feature/PROJ-XX-description\`
+
+**DURING:**
+- Reference JIRA issue ID in every commit: \`type(PROJ-XX): description\`
+- JIRA smart commits: \`PROJ-XX #in-progress\`, \`PROJ-XX #done\`
+
+**AFTER:**
+- PR title: \`feat(PROJ-XX): Story X.Y - Description\`
+- JIRA auto-links PRs via issue ID in branch name or commit
+
+### If ticket_system = "github-issues"
+
+**BEFORE:** Find GitHub issue #XX, assign yourself
+
+**DURING:**
+- Reference in commits: \`type(#XX): description\`
+- Use \`Closes #XX\` or \`Fixes #XX\` in final commit/PR body
+
+**AFTER:**
+- \`gh pr create --title "feat: Story X.Y" --body "Closes #XX"\`
+- Issue auto-closes when PR merges
+
+### If ticket_system = "gitlab-issues"
+
+**BEFORE:** Find GitLab issue #XX, assign yourself
+
+**DURING:**
+- Reference: \`type(#XX): description\`
+- Use \`Closes #XX\` in commit/MR body
+
+**AFTER:**
+- \`glab mr create --title "feat: Story X.Y" --description "Closes #XX"\`
+- Issue auto-closes when MR merges
+
+---
+
+## Git Provider Workflow
+
+### If git_provider = "github"
+
+**Branch strategy:**
+\`\`\`
+main (production)
+  └── develop (integration, if configured)
+        └── feature/{ticket-id}-description
+\`\`\`
+
+**Commands:**
+\`\`\`bash
+# Start story
+git checkout main  # or develop if exists
+git pull
+git checkout -b feature/{ticket-id}-description
+
+# During dev
+git add <specific-files>  # NEVER git add . or git add -A
+git commit -m "type({ticket-id}): description"
+
+# Complete
+git push -u origin feature/{ticket-id}-description
+gh pr create --base main --title "type({ticket-id}): Story X.Y - Title" --body "Fixes {ticket-id}"
+
+# After merge
+git checkout main && git pull
+git branch -d feature/{ticket-id}-description
+\`\`\`
+
+### If git_provider = "gitlab"
+
+**Commands:**
+\`\`\`bash
+# Start
+git checkout main && git pull
+git checkout -b feature/{ticket-id}-description
+
+# Complete
+git push -u origin feature/{ticket-id}-description
+glab mr create --base main --title "type({ticket-id}): Story X.Y" --description "Closes {ticket-id}"
+
+# After merge
+git checkout main && git pull
+git branch -d feature/{ticket-id}-description
+\`\`\`
+
+### If git_provider = "bitbucket"
+
+**Commands:**
+\`\`\`bash
+# Start
+git checkout main && git pull
+git checkout -b feature/{ticket-id}-description
+
+# Complete
+git push -u origin feature/{ticket-id}-description
+# Create PR via Bitbucket web UI or API
+\`\`\`
+
+---
+
+## Commit Message Format
+
+\`\`\`
+type({ticket-id}): short description
+
+[Optional body]
+
+{Magic word} {ticket-id}
+\`\`\`
+
+| Prefix | Usage |
+|--------|-------|
+| feat | New feature / story implementation |
+| fix | Bug fix |
+| refactor | Code restructuring (no behavior change) |
+| test | Adding or updating tests |
+| docs | Documentation changes |
+| chore | Build, config, tooling changes |
+
+---
+
+## State Sync
+
+Local state.yaml and ticket system MUST agree:
+
+| state.yaml | Linear | Jira | GitHub/GitLab Issues |
+|------------|--------|------|---------------------|
+| backlog | Backlog | Backlog | No label |
+| ready-for-dev | Todo | To Do | "ready" label |
+| in-progress | In Progress | In Progress | "in progress" label |
+| review | In Review | In Review | PR linked |
+| done | Done | Done | Closed |
+
+**If they diverge, the ticket system is the authority.** Update state.yaml to match.
+
+---
+
+## Epic/Milestone Tracking
+
+- When first story of an epic moves to In Progress → update epic/milestone status
+- When ALL stories in an epic are Done → mark milestone complete
+- Keep milestone descriptions updated if scope changes
+
+---
+
+## Critical Rules
+
+1. NEVER commit directly to main
+2. ALWAYS create feature branch before starting
+3. ALWAYS include ticket ID in every commit message
+4. ALWAYS update ticket status: In Progress → In Review → Done
+5. ALWAYS stage specific files — never \`git add .\` or \`git add -A\`
+6. ALWAYS use ticket system's suggested branch name when available
+7. NEVER commit secrets (.env, API keys, settings.local.json)
+`;

package/src/templates/scripts.js

@@ -92,8 +92,8 @@ for section in "\${REQUIRED_SECTIONS[@]}"; do
   fi
 done
 
-# Check FR format
-FR_LINES=$(grep -E '^FR[0-9]+:' "$FILE" 2>/dev/null || true)
+# Check FR format — accepts: FR1:, - FR1:, **FR1:**, * FR1:, etc.
+FR_LINES=$(grep -E '(^|[-*>[:space:]])\\*{0,2}FR[0-9]+\\*{0,2}\\s*:' "$FILE" 2>/dev/null || true)
 FR_COUNT=0
 if [[ -n "$FR_LINES" ]]; then
   FR_COUNT=$(echo "$FR_LINES" | wc -l | tr -d ' ')
@@ -111,7 +111,7 @@ fi
 ANTI_PATTERNS=("easy" "intuitive" "fast" "responsive" "simple" "multiple" "several" "various")
 
 for pattern in "\${ANTI_PATTERNS[@]}"; do
-  MATCHES=$(grep -inE "^FR[0-9]+:.*\\b\${pattern}\\b" "$FILE" 2>/dev/null || true)
+  MATCHES=$(grep -inE 'FR[0-9]+.*:.*\\b\${pattern}\\b' "$FILE" 2>/dev/null || true)
   if [[ -n "$MATCHES" ]]; then
     ISSUES+=("ANTI-PATTERN '$pattern' found in FR: $MATCHES")
   fi

package/src/templates/skills.js

@@ -335,13 +335,18 @@ Story files: \`${o}/stories/{story-key}.md\`
 
 ## Ticket System Integration
 
-Read \`ticket_system\` from config. If not \`none\`:
+Read \`ticket_system\` from config. Read \`${a}/aped-d/references/ticket-git-workflow.md\` for full guide.
+
+If \`ticket_system\` is not \`none\`:
 - Add ticket reference in each story header: \`**Ticket:** {{ticket_id}}\`
-- If \`jira\`: format as \`PROJ-###\` placeholder
-- If \`linear\`: format as \`TEAM-###\` placeholder
-- If \`github-issues\`: format as \`#issue_number\` placeholder
-- If \`gitlab-issues\`: format as \`#issue_number\` placeholder
+- Add suggested branch name: \`**Branch:** feature/{{ticket_id}}-{{story-slug}}\`
+- Format ticket ID per provider:
+  - \`linear\`: \`TEAM-###\` (e.g., \`KON-10\`)
+  - \`jira\`: \`PROJ-###\` (e.g., \`PROJ-42\`)
+  - \`github-issues\`: \`#issue_number\` (e.g., \`#10\`)
+  - \`gitlab-issues\`: \`#issue_number\` (e.g., \`#10\`)
 - Note: actual ticket creation is manual — these are reference placeholders
+- In Dev Notes, add: "Commit prefix: \`feat({{ticket_id}})\`"
 
 ## FR Coverage Map
 
@@ -469,11 +474,32 @@ Mark \`[x]\` ONLY when: tests exist, pass 100%, implementation matches, ACs sati
 
 **STOP and ask user if:** new dependency, 3 consecutive failures, missing config, ambiguity.
 
-## Git Commit Convention
+## Git & Ticket Workflow
+
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for full integration guide.
+
+Read \`ticket_system\` and \`git_provider\` from \`${a}/config.yaml\`.
+
+### Before Implementation
+If \`ticket_system\` is not \`none\`:
+1. Find the corresponding ticket/issue for this story
+2. Move ticket status to **In Progress**
+3. Create feature branch using ticket system's suggested name
+4. Add a comment on the ticket: implementation plan
+
+If \`ticket_system\` is \`none\`:
+1. Create branch: \`feature/{story-key}\`
 
-Read \`git_provider\` and \`ticket_system\` from config:
-- Commit message format: \`type(scope): description\`
-- If ticket system configured, append ticket ref: \`type(scope): description [TICKET-ID]\`
+### During Implementation
+- Include ticket ID in EVERY commit: \`type({ticket-id}): description\`
+- Use magic words for auto-linking (see reference doc)
+- NEVER use \`git add .\` — stage specific files only
+
+### After Implementation
+1. Push branch and create PR/MR (adapt to \`git_provider\`):
+   - \`github\`: \`gh pr create --title "feat({ticket-id}): Story X.Y" --body "Fixes {ticket-id}"\`
+   - \`gitlab\`: \`glab mr create --title "feat({ticket-id}): Story X.Y" --description "Closes {ticket-id}"\`
+2. Move ticket to **In Review**
 
 ## Completion
 
@@ -572,6 +598,20 @@ Severity: CRITICAL > HIGH > MEDIUM > LOW. Format: \`[Severity] Description [file
 - MEDIUM/LOW only: fix automatically, story — \`done\`
 - HIGH+: fix or add \`[AI-Review]\` items, story — \`in-progress\`
 
+## Ticket & Git Update
+
+Read \`ticket_system\` and \`git_provider\` from \`${a}/config.yaml\`.
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for details.
+
+If story → \`done\`:
+1. If PR exists: approve/merge (adapt to \`git_provider\`)
+2. If \`ticket_system\` is not \`none\`: move ticket to **Done**
+3. Cleanup: delete feature branch after merge
+
+If story → \`in-progress\` (review found HIGH+ issues):
+1. Add [AI-Review] items as comments on the PR
+2. Ticket stays in **In Review**
+
 ## State Update
 
 Update \`${o}/state.yaml\`. If more stories remain: invoke Skill tool with \`skill: "aped-d"\`. If all stories done: report pipeline completion.
@@ -966,11 +1006,20 @@ Based on current state, suggest the next logical command:
 - If all stories \`done\`: suggest pipeline complete
 - If blockers found: describe resolution path
 
-## Ticket System Integration
+## Ticket System Sync
+
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for status mapping.
 
 If \`ticket_system\` is not \`none\`:
-- Show ticket references alongside story statuses
-- Note any stories without ticket references
+- Show ticket ID alongside each story status
+- Flag any stories without ticket references
+- Check sync: compare state.yaml statuses with expected ticket statuses
+- If divergence detected: warn user — "state.yaml says X, ticket system should be Y"
+- Display mapping table:
+  - \`backlog\` → Backlog/Todo
+  - \`in-progress\` → In Progress
+  - \`review\` → In Review
+  - \`done\` → Done
 
 ## Output
 
@@ -1402,13 +1451,18 @@ Quick checklist — no full adversarial review:
 - [ ] No regressions in existing tests
 - [ ] AC from quick spec satisfied
 
-## Git Commit
+## Git & Ticket Workflow
 
 Read \`ticket_system\` and \`git_provider\` from config.
-- Format: \`type(scope): description\`
-- Append ticket ref if configured
-- If \`git_provider\` is \`github\`: suggest PR creation with \`gh pr create\`
-- If \`git_provider\` is \`gitlab\`: suggest MR creation with \`glab mr create\`
+Read \`${a}/aped-d/references/ticket-git-workflow.md\` for full guide.
+
+1. **Branch**: create \`fix/{ticket-id}-{slug}\` or \`feature/{ticket-id}-{slug}\`
+2. **Commits**: \`type({ticket-id}): description\` — include magic words per ticket provider
+3. **PR/MR**:
+   - \`github\`: \`gh pr create --title "fix({ticket-id}): description" --body "Fixes {ticket-id}"\`
+   - \`gitlab\`: \`glab mr create --title "fix({ticket-id}): description" --description "Closes {ticket-id}"\`
+   - \`bitbucket\`: push branch, create PR via web
+4. **Ticket**: move to Done after merge
 
 ## Output