devflow-kit 1.4.0 → 1.6.0

package/plugins/devflow-ambient/skills/implementation-orchestration/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: implementation-orchestration
+description: Agent orchestration for IMPLEMENT intent — pre-flight, Coder, quality gates
+user-invocable: false
+allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion
+---
+
+# Implementation Orchestration
+
+Agent pipeline for IMPLEMENT intent in ambient ORCHESTRATED mode. Pre-flight checks, plan synthesis, Coder execution, and quality gates.
+
+This is a lightweight variant of `/implement` for ambient ORCHESTRATED mode. Excluded: strategy selection (single/sequential/parallel Coders), retry loops, PR creation, knowledge loading.
+
+## Iron Law
+
+> **QUALITY GATES ARE NON-NEGOTIABLE**
+>
+> Every Coder output passes through Validator → Simplifier → Scrutinizer → re-Validate → Shepherd.
+> Skipping a gate because "it looks fine" is never acceptable. The pipeline runs to completion
+> or halts on failure — there is no shortcut.
+
+---
+
+## Phase 1: Pre-flight — Branch Safety
+
+Detect branch type before spawning Coder:
+
+- **Work branches** (`feat/`, `fix/`, `chore/`, `refactor/`, `docs/` prefix): proceed on current branch.
+- **Protected branches** (`main`, `master`, `develop`, `release/*`, `staging`, `production`): ask user via AskUserQuestion with 2-3 suggested branch names following `{type}/{ticket}-{slug}` convention. Include ticket number if available from conversation context.
+- **If user declines branch creation**: proceed on the protected branch. Respect the user's choice.
+
+## Phase 2: Plan Synthesis
+
+Synthesize conversation context into a structured EXECUTION_PLAN for Coder:
+
+- **If a plan exists** in conversation context (from plan mode — accepted in-session or injected after "accept and clear") → use the plan as-is.
+- **Otherwise** → synthesize from conversation: what to build, files/modules affected, constraints, decisions made during discussion.
+
+Format as structured markdown with: Goal, Steps, Files, Constraints, Decisions.
+
+## Phase 3: Coder Execution
+
+Record git SHA before first Coder: `git rev-parse HEAD`
+
+Spawn `Task(subagent_type="Coder")` with input variables:
+- **TASK_ID**: Generated from timestamp (e.g., `task-2026-03-19_1430`)
+- **TASK_DESCRIPTION**: From conversation context
+- **BASE_BRANCH**: Current branch (or newly created branch from Phase 1)
+- **EXECUTION_PLAN**: From Phase 2
+- **PATTERNS**: Codebase patterns from conversation context
+- **CREATE_PR**: `false` (commit only, no push)
+- **DOMAIN**: Inferred from files in scope (`backend`, `frontend`, `tests`, `fullstack`)
+
+**Execution strategy**: Single sequential Coder by default. Parallel Coders only when tasks are self-contained — zero shared contracts, no integration points, different files/modules with no imports between them.
+
+If Coder returns **BLOCKED**, halt the pipeline and report to user.
+
+## Phase 4: FILES_CHANGED Detection
+
+After Coder completes, detect changed files:
+
+```bash
+git diff --name-only {starting_sha}...HEAD
+```
+
+Pass FILES_CHANGED to all quality gate agents.
+
+## Phase 5: Quality Gates
+
+Run sequentially — each gate must pass before the next:
+
+1. `Task(subagent_type="Validator")` (build + typecheck + lint + tests) — retry up to 2× on failure (Coder fixes between retries)
+2. `Task(subagent_type="Simplifier")` — code clarity and maintainability pass on FILES_CHANGED
+3. `Task(subagent_type="Scrutinizer")` — 9-pillar quality evaluation on FILES_CHANGED
+4. `Task(subagent_type="Validator")` (re-validate after Simplifier/Scrutinizer changes)
+5. `Task(subagent_type="Shepherd")` — verify implementation matches original request — retry up to 2× if misalignment found
+
+If any gate exhausts retries, halt pipeline and report what passed and what failed.
+
+## Phase 6: Completion
+
+Report results:
+- Commits created (from Coder)
+- Files changed
+- Quality gate results (pass/fail per gate)
+- No push — user decides when to push
+
+## Error Handling
+
+- **Coder BLOCKED**: Halt immediately, report blocker to user
+- **Validator fails after retries**: Report specific failures, halt pipeline
+- **Shepherd misalignment after retries**: Report misalignment details, let user decide next steps

package/plugins/devflow-ambient/skills/plan-orchestration/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: plan-orchestration
+description: Agent orchestration for PLAN intent — codebase orientation, design exploration, gap validation
+user-invocable: false
+allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion
+---
+
+# Plan Orchestration
+
+Agent pipeline for PLAN intent in ambient ORCHESTRATED mode. Codebase orientation, targeted exploration, architecture design, and gap validation.
+
+This is a lightweight variant of the Plan phase in `/implement` for ambient ORCHESTRATED mode.
+
+## Iron Law
+
+> **PLANS WITHOUT CODEBASE GROUNDING ARE FANTASIES**
+>
+> Orient before architecting. Every design decision must reference existing patterns,
+> real file structures, and actual integration points. A plan that ignores the codebase
+> will fail on contact with implementation.
+
+---
+
+## Phase 1: Orient
+
+Spawn `Task(subagent_type="Skimmer")` to get codebase overview relevant to the planning question:
+
+- Existing patterns and conventions in the affected area
+- File structure and module boundaries
+- Test patterns and coverage approach
+- Related prior implementations (similar features, analogous patterns)
+
+## Phase 2: Explore
+
+Based on Skimmer findings, spawn 2-3 `Task(subagent_type="Explore")` agents **in a single message** (parallel execution):
+
+- **Integration explorer**: Examine integration points — APIs, shared types, module boundaries the plan must respect
+- **Pattern explorer**: Find existing implementations of similar features to follow as templates
+- **Constraint explorer**: Identify constraints — test infrastructure, build system, CI requirements, deployment concerns
+
+Adjust explorer focus based on the specific planning question.
+
+## Phase 3: Design
+
+Spawn `Task(subagent_type="Plan")` with combined Skimmer + Explore findings:
+
+- Design implementation approach with file-level specificity
+- Reference existing patterns discovered in Phase 1-2
+- Include: architecture decisions, file changes, new files needed, test strategy
+- Flag any areas where existing patterns conflict with the proposed approach
+
+## Phase 4: Validate
+
+Main session reviews the plan for:
+
+- **Gaps**: Missing files, unhandled edge cases, integration points not addressed
+- **Risks**: Areas where the plan deviates from existing patterns, potential regressions
+- **Ambiguities**: Design choices that need user input
+
+Present plan to user with identified risks. Use AskUserQuestion for any ambiguous design choices.
+
+## Output
+
+Structured plan ready to feed into IMPLEMENT/ORCHESTRATED if user proceeds:
+
+- Goal and scope
+- Architecture decisions with rationale
+- File-level change list (create/modify/delete)
+- Test strategy
+- Risks and mitigations
+- Open questions (if any)

package/plugins/devflow-audit-claude/.claude-plugin/plugin.json

@@ -4,7 +4,16 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.4.0",
+  "version": "1.6.0",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": [
+    "audit",
+    "claude-md",
+    "best-practices",
+    "lint"
+  ],
   "agents": [],
   "skills": []
 }

package/plugins/devflow-audit-claude/commands/audit-claude.md

@@ -1,3 +1,7 @@
+---
+description: Audit CLAUDE.md files against Anthropic best practices
+---
+
 # Command: /audit-claude
 
 ## Description

package/plugins/devflow-code-review/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.4.0",
+  "version": "1.6.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",
@@ -28,6 +28,7 @@
     "database-patterns",
     "dependencies-patterns",
     "documentation-patterns",
+    "knowledge-persistence",
     "performance-patterns",
     "regression-patterns",
     "review-methodology",

package/plugins/devflow-code-review/agents/reviewer.md

@@ -42,12 +42,38 @@ The orchestrator provides:
 ## Responsibilities
 
 1. **Load focus skill** - Read the pattern skill file for your focus area from the table above. This gives you detection rules and patterns specific to your review type.
-2. **Identify changed lines** - Get diff against base branch (main/master/develop)
-3. **Apply 3-category classification** - Sort issues by where they occur
-4. **Apply focus-specific analysis** - Use pattern skill detection rules from the loaded skill file
-5. **Assign severity** - CRITICAL, HIGH, MEDIUM, LOW based on impact
-6. **Generate report** - File:line references with suggested fixes
-7. **Determine merge recommendation** - Based on blocking issues
+2. **Check known pitfalls** - If `.memory/knowledge/pitfalls.md` exists, read it. Check if any pitfall Areas overlap with files in the current diff. Verify the Resolution was applied. Flag if a known pitfall pattern is being reintroduced.
+3. **Identify changed lines** - Get diff against base branch (main/master/develop)
+4. **Apply 3-category classification** - Sort issues by where they occur
+5. **Apply focus-specific analysis** - Use pattern skill detection rules from the loaded skill file
+6. **Assign severity** - CRITICAL, HIGH, MEDIUM, LOW based on impact
+7. **Assess confidence** - Assign 0-100% confidence to each finding (see Confidence Scale below)
+8. **Filter by confidence** - Only report findings ≥80% in main sections; lower-confidence items go to Suggestions
+9. **Consolidate similar issues** - Group related findings to reduce noise (see Consolidation Rules)
+10. **Generate report** - File:line references with suggested fixes
+11. **Determine merge recommendation** - Based on blocking issues
+
+## Confidence Scale
+
+Assess how certain you are that each finding is a real issue (not a false positive):
+
+| Range | Label | Meaning |
+|-------|-------|---------|
+| 90-100% | Certain | Clearly a bug, vulnerability, or violation — no ambiguity |
+| 80-89% | High | Very likely an issue, but minor chance of false positive |
+| 60-79% | Medium | Plausible issue, but depends on context you may not fully see |
+| < 60% | Low | Possible concern, but likely a matter of style or interpretation |
+
+<!-- Confidence threshold also in: shared/agents/synthesizer.md, plugins/devflow-code-review/commands/code-review.md -->
+**Threshold**: Only report findings with ≥80% confidence in Blocking, Should-Fix, and Pre-existing sections. Findings with 60-79% confidence go to the Suggestions section. Findings < 60% are dropped entirely.
+
+## Consolidation Rules
+
+Before writing your report, apply these noise reduction rules:
+
+1. **Group similar issues** — If 3+ instances of the same pattern appear (e.g., "missing error handling" in multiple functions), consolidate into 1 finding listing all locations rather than N separate findings
+2. **Skip stylistic preferences** — Do not flag formatting, naming style, or code organization choices unless they violate explicit project conventions found in CLAUDE.md, .editorconfig, or linter configs
+3. **Skip issues in unchanged code** — Pre-existing issues in lines you did NOT change should only be reported if CRITICAL severity (security vulnerabilities, data loss risks)
 
 ## Issue Categories (from review-methodology)
 
@@ -76,17 +102,29 @@ Report format for `{output_path}`:
 
 ### CRITICAL
 **{Issue}** - `file.ts:123`
+**Confidence**: {n}%
 - Problem: {description}
 - Fix: {suggestion with code}
 
+**{Issue Title} ({N} occurrences)** — Confidence: {n}%
+- `file1.ts:12`, `file2.ts:45`, `file3.ts:89`
+- Problem: {description of the shared pattern}
+- Fix: {suggestion that applies to all occurrences}
+
 ### HIGH
-{issues...}
+{issues with **Confidence**: {n}% each...}
 
 ## Issues in Code You Touched (Should Fix)
-{issues with file:line...}
+{issues with file:line and **Confidence**: {n}% each...}
 
 ## Pre-existing Issues (Not Blocking)
-{informational issues...}
+{informational issues with **Confidence**: {n}% each...}
+
+## Suggestions (Lower Confidence)
+
+{Max 3 items with 60-79% confidence. Brief description only — no code fixes.}
+
+- **{Issue}** - `file.ts:456` (Confidence: {n}%) — {brief description}
 
 ## Summary
 | Category | CRITICAL | HIGH | MEDIUM | LOW |

package/plugins/devflow-code-review/agents/synthesizer.md

@@ -128,10 +128,14 @@ Analyze 3 axes to determine strategy:
 Synthesize outputs from multiple Reviewer agents. Apply strict merge rules.
 
 **Process:**
-1. Read all review reports from `${REVIEW_BASE_DIR}/*-report.*.md`
-2. Categorize issues into 3 buckets (from review-methodology)
-3. Count by severity (CRITICAL, HIGH, MEDIUM, LOW)
-4. Determine merge recommendation based on blocking issues
+1. Read all review reports from `${REVIEW_BASE_DIR}/*.md` (exclude your own output `review-summary.*.md`)
+2. Extract confidence percentages from each finding
+3. Apply confidence-aware aggregation: when multiple reviewers flag the same file:line, boost confidence by 10% per additional reviewer (cap at 100%)
+<!-- Confidence threshold also in: shared/agents/reviewer.md, plugins/devflow-code-review/commands/code-review.md -->
+4. Maintain ≥80% confidence threshold in final output
+5. Categorize issues into 3 buckets (from review-methodology)
+6. Count by severity (CRITICAL, HIGH, MEDIUM, LOW)
+7. Determine merge recommendation based on blocking issues
 
 **Issue Categories:**
 - **Blocking** (Category 1): Issues in YOUR changes - CRITICAL/HIGH must block
@@ -172,7 +176,10 @@ Report format:
 | Pre-existing | - | - | {n} | {n} | {n} |
 
 ## Blocking Issues
-{List with file:line and suggested fix}
+{List with file:line, confidence %, and suggested fix}
+
+## Suggestions (Lower Confidence)
+{Max 5 items across all reviewers with 60-79% confidence. Brief descriptions only.}
 
 ## Action Plan
 1. {Priority fix}

package/plugins/devflow-code-review/commands/code-review-teams.md

@@ -85,39 +85,42 @@ Spawn review teammates with self-contained prompts:
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
     1. Read your skill: `Read ~/.claude/skills/security-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
-    3. Get the diff: `git diff {base_branch}...HEAD`
-    4. Apply the 6-step review process from review-methodology
-    5. Focus: injection, auth bypass, crypto misuse, OWASP vulnerabilities
-    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
-    7. Include file:line references for every finding
-    8. Write your report: `Write to .docs/reviews/{branch_slug}/security.md`
-    9. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Security review done")
+    3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
+    4. Get the diff: `git diff {base_branch}...HEAD`
+    5. Apply the 6-step review process from review-methodology
+    6. Focus: injection, auth bypass, crypto misuse, OWASP vulnerabilities
+    7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    8. Include file:line references for every finding
+    9. Write your report: `Write to .docs/reviews/{branch_slug}/security.md`
+    10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Security review done")
 
 - Name: "architecture-reviewer"
   Prompt: |
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
     1. Read your skill: `Read ~/.claude/skills/architecture-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
-    3. Get the diff: `git diff {base_branch}...HEAD`
-    4. Apply the 6-step review process from review-methodology
-    5. Focus: SOLID violations, coupling, layering issues, modularity problems
-    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
-    7. Include file:line references for every finding
-    8. Write your report: `Write to .docs/reviews/{branch_slug}/architecture.md`
-    9. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Architecture review done")
+    3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
+    4. Get the diff: `git diff {base_branch}...HEAD`
+    5. Apply the 6-step review process from review-methodology
+    6. Focus: SOLID violations, coupling, layering issues, modularity problems
+    7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    8. Include file:line references for every finding
+    9. Write your report: `Write to .docs/reviews/{branch_slug}/architecture.md`
+    10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Architecture review done")
 
 - Name: "performance-reviewer"
   Prompt: |
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
     1. Read your skill: `Read ~/.claude/skills/performance-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
-    3. Get the diff: `git diff {base_branch}...HEAD`
-    4. Apply the 6-step review process from review-methodology
-    5. Focus: N+1 queries, memory leaks, algorithm issues, I/O bottlenecks
-    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
-    7. Include file:line references for every finding
-    8. Write your report: `Write to .docs/reviews/{branch_slug}/performance.md`
-    9. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Performance review done")
+    3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
+    4. Get the diff: `git diff {base_branch}...HEAD`
+    5. Apply the 6-step review process from review-methodology
+    6. Focus: N+1 queries, memory leaks, algorithm issues, I/O bottlenecks
+    7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    8. Include file:line references for every finding
+    9. Write your report: `Write to .docs/reviews/{branch_slug}/performance.md`
+    10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Performance review done")
 
 - Name: "quality-reviewer"
   Prompt: |
@@ -128,13 +131,14 @@ Spawn review teammates with self-contained prompts:
        - `Read ~/.claude/skills/test-patterns/SKILL.md`
        - `Read ~/.claude/skills/regression-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
-    3. Get the diff: `git diff {base_branch}...HEAD`
-    4. Apply the 6-step review process from review-methodology
-    5. Focus: complexity, test gaps, pattern violations, regressions, naming
-    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
-    7. Include file:line references for every finding
-    8. Write your report: `Write to .docs/reviews/{branch_slug}/quality.md`
-    9. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Quality review done")
+    3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
+    4. Get the diff: `git diff {base_branch}...HEAD`
+    5. Apply the 6-step review process from review-methodology
+    6. Focus: complexity, test gaps, pattern violations, regressions, naming
+    7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    8. Include file:line references for every finding
+    9. Write your report: `Write to .docs/reviews/{branch_slug}/quality.md`
+    10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Quality review done")
 
 [Add conditional perspectives based on Phase 1 — follow same pattern:
  explicit skill path, diff command, output path, SendMessage for completion]
@@ -212,7 +216,14 @@ Include confidence levels from debate consensus."
 {Key exchanges that changed findings}
 ```
 
-### Phase 5: Cleanup and Report
+### Phase 5: Record Pitfalls (if blocking issues found)
+
+If the review summary contains CRITICAL or HIGH blocking issues:
+1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md`
+2. Source field: `/code-review {branch}`
+3. Skip entirely if no CRITICAL/HIGH blocking issues
+
+### Phase 6: Cleanup and Report
 
 Shut down all review teammates explicitly:
 
@@ -257,7 +268,9 @@ Display results:
 │  ├─ Git agent (comment-pr with consensus findings)
 │  └─ Lead writes review-summary with confidence levels
 │
-└─ Phase 5: Cleanup and display results
+├─ Phase 5: Record Pitfalls (inline, if blocking issues)
+│
+└─ Phase 6: Cleanup and display results
 ```
 
 ## Principles

package/plugins/devflow-code-review/commands/code-review.md

@@ -95,7 +95,10 @@ IMPORTANT: Write report to .docs/reviews/{branch-slug}/{focus}.md using Write to
 Task(subagent_type="Git", run_in_background=false):
 "OPERATION: comment-pr
 Read reviews from .docs/reviews/{branch-slug}/
-Create inline PR comments, deduplicate, consolidate skipped into summary"
+<!-- Confidence threshold also in: shared/agents/reviewer.md, shared/agents/synthesizer.md -->
+Create inline PR comments for findings with ≥80% confidence only.
+Lower-confidence suggestions (60-79%) go in the summary comment, not as inline comments.
+Deduplicate findings across reviewers, consolidate skipped into summary."
 ```
 
 **Synthesizer Agent**:
@@ -114,6 +117,13 @@ Display results from all agents:
 - PR comments created/skipped (from Git)
 - Artifact paths
 
+### Phase 5: Record Pitfalls (if blocking issues found)
+
+If the review summary contains CRITICAL or HIGH blocking issues:
+1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md`
+2. Source field: `/code-review {branch}`
+3. Skip entirely if no CRITICAL/HIGH blocking issues
+
 ## Architecture
 
 ```
@@ -139,7 +149,9 @@ Display results from all agents:
 │  ├─ Git agent (comment-pr)
 │  └─ Synthesizer agent (mode: review)
 │
-└─ Phase 4: Display results
+├─ Phase 4: Display results
+│
+└─ Phase 5: Record Pitfalls (inline, if blocking issues)
 ```
 
 ## Principles

package/plugins/devflow-code-review/skills/knowledge-persistence/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: knowledge-persistence
+description: >-
+  This skill should be used when recording architectural decisions or pitfalls
+  to project knowledge files, or when loading prior decisions and known pitfalls
+  for context during investigation, specification, or review.
+user-invocable: false
+allowed-tools: Read, Write, Bash
+---
+
+# Knowledge Persistence
+
+Record architectural decisions and pitfalls to `.memory/knowledge/` files. This is the single source of truth for the extraction procedure — commands reference this skill instead of inlining the steps.
+
+## Iron Law
+
+> **SINGLE SOURCE OF TRUTH**
+>
+> All knowledge extraction follows this procedure exactly. Commands never inline
+> their own extraction steps — they read this skill and follow it.
+
+---
+
+## File Locations
+
+```
+.memory/knowledge/
+├── decisions.md    # ADR entries (append-only)
+└── pitfalls.md     # PF entries (area-specific gotchas)
+```
+
+## File Formats
+
+### decisions.md (ADR entries)
+
+**Template header** (create if file missing):
+```
+<!-- TL;DR: 0 decisions. Key: -->
+# Architectural Decisions
+
+Append-only. Status changes allowed; deletions prohibited.
+```
+
+**Entry format**:
+```markdown
+## ADR-{NNN}: {Title}
+
+- **Date**: {YYYY-MM-DD}
+- **Status**: Accepted
+- **Context**: {Why this decision was needed}
+- **Decision**: {What was decided}
+- **Consequences**: {Tradeoffs and implications}
+- **Source**: {command and identifier, e.g. `/implement TASK-123`}
+```
+
+### pitfalls.md (PF entries)
+
+**Template header** (create if file missing):
+```
+<!-- TL;DR: 0 pitfalls. Key: -->
+# Known Pitfalls
+
+Area-specific gotchas, fragile areas, and past bugs.
+```
+
+**Entry format**:
+```markdown
+## PF-{NNN}: {Short description}
+
+- **Area**: {file paths or module names}
+- **Issue**: {What goes wrong}
+- **Impact**: {Consequences if hit}
+- **Resolution**: {How to fix or avoid}
+- **Source**: {command and identifier, e.g. `/code-review branch-name`}
+```
+
+---
+
+## Extraction Procedure
+
+Follow these steps when recording decisions or pitfalls:
+
+1. **Read** the target file (`.memory/knowledge/decisions.md` or `.memory/knowledge/pitfalls.md`). If it doesn't exist, create it with the template header above.
+2. **Check capacity** — count `## ADR-` or `## PF-` headings. If >=50, log "Knowledge base at capacity — skipping new entry" and stop.
+3. **Find next ID** — find highest NNN via regex (`/^## ADR-(\d+)/` or `/^## PF-(\d+)/`), default to 0. Increment by 1.
+4. **Deduplicate** (pitfalls only) — skip if an entry with the same Area + Issue already exists.
+5. **Append** the new entry using the format above.
+6. **Update TL;DR** — rewrite the `<!-- TL;DR: ... -->` comment on line 1 to reflect the new count and key topics.
+
+## Lock Protocol
+
+When writing, use a mkdir-based lock:
+- Lock path: `.memory/.knowledge.lock`
+- Timeout: 30 seconds (fail if lock not acquired)
+- Stale recovery: if lock directory is >60 seconds old, remove it and retry
+- Release lock after write completes (remove lock directory)
+
+## Loading Knowledge for Context
+
+When a command needs prior knowledge as input (not recording):
+
+1. Read `.memory/knowledge/decisions.md` if it exists
+2. Read `.memory/knowledge/pitfalls.md` if it exists
+3. Pass content as context to downstream agents — prior decisions constrain scope, known pitfalls inform investigation
+
+If neither file exists, skip silently. No error, no empty-file creation.
+
+## Operation Budget
+
+Recording: do inline (no agent spawn), 2-3 Read/Write operations total.
+Loading: 1-2 Read operations, pass as context string.
+
+---
+
+## Extended References
+
+For entry examples and status lifecycle details:
+- `references/examples.md` - Full decision and pitfall entry examples
+
+---
+
+## Success Criteria
+
+- [ ] Entry appended with correct sequential ID
+- [ ] No duplicate pitfalls (same Area + Issue)
+- [ ] TL;DR comment updated with current count
+- [ ] Lock acquired before write, released after
+- [ ] Capacity limit (50) respected

package/plugins/devflow-code-review/skills/knowledge-persistence/references/examples.md

@@ -0,0 +1,44 @@
+# Knowledge Persistence Examples
+
+## Decision Entry Example
+
+```markdown
+## ADR-001: Use mkdir-based locks for concurrent session serialization
+
+- **Date**: 2026-03-03
+- **Status**: Accepted
+- **Context**: Multiple Claude Code sessions can run on the same project simultaneously (different terminals, SSH, etc.). Memory writes must serialize to prevent corruption.
+- **Decision**: Use `mkdir` as an atomic lock primitive. Lock directory at `.memory/.knowledge.lock`. 30-second timeout with 60-second stale recovery.
+- **Consequences**: Simple, cross-platform, no external dependencies. Cannot detect holder PID if lock is stale — relies on age-based recovery. Sufficient for low-contention writes.
+- **Source**: `/implement #99`
+```
+
+## Pitfall Entry Example
+
+```markdown
+## PF-001: Orphaned teams variants silently skipped
+
+- **Area**: plugins/devflow-*/commands/*-teams.md, src/cli/installer
+- **Issue**: The installer iterates base `.md` files and looks up matching `-teams.md` variants. A `-teams.md` file without a corresponding base `.md` is silently ignored during installation.
+- **Impact**: Teams variant appears committed but never installs. Users on `--teams` mode silently get no command.
+- **Resolution**: Always create the base `.md` file first. CI should validate that every `-teams.md` has a matching base file.
+- **Source**: `/code-review feat/agent-teams`
+```
+
+## Status Lifecycle (Decisions Only)
+
+Decisions support status transitions:
+- `Accepted` — current, in effect
+- `Superseded by ADR-NNN` — replaced by a newer decision
+- `Deprecated` — no longer relevant, kept for history
+
+Pitfalls have no status field — they remain until manually removed.
+
+## Deduplication Logic (Pitfalls Only)
+
+Before appending a new pitfall, check existing entries:
+1. Extract `Area` and `Issue` from the new entry
+2. Compare against all existing `PF-*` entries
+3. If both Area AND Issue match an existing entry (case-insensitive substring), skip
+
+This prevents recording the same gotcha from multiple review cycles.