aped-method 2.0.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": "2.0.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/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