diff --git a/CLAUDE.md b/CLAUDE.md index 300c763..7b5a476 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -44,7 +44,7 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name} ``` devflow/ -├── shared/skills/ # 31 skills (single source of truth) +├── shared/skills/ # 32 skills (single source of truth) ├── shared/agents/ # 10 shared agents (single source of truth) ├── plugins/devflow-*/ # 17 plugins (9 core + 8 optional language/ecosystem) ├── docs/reference/ # Detailed reference documentation @@ -94,7 +94,10 @@ Working memory files live in a dedicated `.memory/` directory: .memory/ ├── WORKING-MEMORY.md # Auto-maintained by Stop hook (overwritten each session) ├── PROJECT-PATTERNS.md # Accumulated patterns (merged, not overwritten) -└── backup.json # Pre-compact git state snapshot +├── backup.json # Pre-compact git state snapshot +└── knowledge/ + ├── decisions.md # Architectural decisions (ADR-NNN, append-only) + └── pitfalls.md # Known pitfalls (PF-NNN, area-specific gotchas) ``` **Naming conventions**: Timestamps as `YYYY-MM-DD_HHMM`, branch slugs replace `/` with `-`, topic slugs are lowercase-dashes. diff --git a/docs/reference/file-organization.md b/docs/reference/file-organization.md index c8e7a88..a802d6e 100644 --- a/docs/reference/file-organization.md +++ b/docs/reference/file-organization.md @@ -9,7 +9,7 @@ devflow/ ├── .claude-plugin/ # Marketplace registry (repo root) │ └── marketplace.json ├── shared/ -│ ├── skills/ # SINGLE SOURCE OF TRUTH (24 skills) +│ ├── skills/ # SINGLE SOURCE OF TRUTH (31 skills) │ │ ├── git-workflow/ │ │ │ ├── SKILL.md │ │ │ └── references/ @@ -20,7 +20,7 @@ devflow/ │ ├── synthesizer.md │ ├── coder.md │ └── ... -├── plugins/ # Plugin collection (8 plugins) +├── plugins/ # Plugin collection (17 plugins) │ ├── devflow-specify/ │ │ ├── .claude-plugin/ │ │ │ └── plugin.json @@ -40,10 +40,11 @@ devflow/ ├── scripts/ │ ├── build-plugins.ts │ ├── statusline.sh -│ └── hooks/ # Working Memory hooks +│ └── hooks/ # Working Memory + ambient hooks │ ├── stop-update-memory # Stop hook: writes WORKING-MEMORY.md │ ├── session-start-memory # SessionStart hook: injects memory + git state -│ └── pre-compact-memory # PreCompact hook: saves git state backup +│ ├── pre-compact-memory # PreCompact hook: saves git state backup +│ └── ambient-prompt.sh # UserPromptSubmit hook: ambient skill injection └── src/ └── cli/ ├── commands/ @@ -148,6 +149,17 @@ Three hooks in `scripts/hooks/` provide automatic session continuity. Toggleable Hooks auto-create `.memory/` on first run — no manual setup needed per project. +## Project Knowledge + +Knowledge files in `.memory/knowledge/` capture decisions and pitfalls that agents can't rediscover at runtime: + +| File | Format | Source | Purpose | +|------|--------|--------|---------| +| `decisions.md` | ADR-NNN (sequential) | `/implement` Phase 11.5 | Architectural decisions — why choices were made | +| `pitfalls.md` | PF-NNN (sequential) | `/code-review`, `/debug`, `/resolve` | Known gotchas, fragile areas, past bugs | + +Each file has a `` comment on line 1. SessionStart injects TL;DR headers only (~30-50 tokens). Agents read full files when relevant to their work. Cap: 50 entries per file. + ## Statusline Script The statusline (`scripts/statusline.sh`) displays: diff --git a/docs/reference/skills-architecture.md b/docs/reference/skills-architecture.md index 69909b6..4a5a7b4 100644 --- a/docs/reference/skills-architecture.md +++ b/docs/reference/skills-architecture.md @@ -21,6 +21,7 @@ Shared patterns used by multiple agents. | `github-patterns` | GitHub API patterns (rate limiting, PR comments, issues, releases) | Git | | `implementation-patterns` | CRUD, API endpoints, events, config, logging | Coder, Resolver | | `agent-teams` | Agent Teams patterns for peer-to-peer collaboration, debate, consensus | /code-review, /implement, /debug | +| `knowledge-persistence` | Record/load architectural decisions and pitfalls to `.memory/knowledge/` | /implement, /code-review, /resolve, /debug, /specify, /self-review | ### Tier 1b: Pattern Skills diff --git a/plugins/devflow-code-review/.claude-plugin/plugin.json b/plugins/devflow-code-review/.claude-plugin/plugin.json index 0084aa1..b593680 100644 --- a/plugins/devflow-code-review/.claude-plugin/plugin.json +++ b/plugins/devflow-code-review/.claude-plugin/plugin.json @@ -28,6 +28,7 @@ "database-patterns", "dependencies-patterns", "documentation-patterns", + "knowledge-persistence", "performance-patterns", "regression-patterns", "review-methodology", diff --git a/plugins/devflow-code-review/commands/code-review-teams.md b/plugins/devflow-code-review/commands/code-review-teams.md index a9d6866..def2ca7 100644 --- a/plugins/devflow-code-review/commands/code-review-teams.md +++ b/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 diff --git a/plugins/devflow-code-review/commands/code-review.md b/plugins/devflow-code-review/commands/code-review.md index 674f244..af7d274 100644 --- a/plugins/devflow-code-review/commands/code-review.md +++ b/plugins/devflow-code-review/commands/code-review.md @@ -117,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 ``` @@ -142,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 diff --git a/plugins/devflow-debug/.claude-plugin/plugin.json b/plugins/devflow-debug/.claude-plugin/plugin.json index 1e91afa..2c81941 100644 --- a/plugins/devflow-debug/.claude-plugin/plugin.json +++ b/plugins/devflow-debug/.claude-plugin/plugin.json @@ -19,6 +19,7 @@ ], "skills": [ "agent-teams", - "git-safety" + "git-safety", + "knowledge-persistence" ] } diff --git a/plugins/devflow-debug/commands/debug-teams.md b/plugins/devflow-debug/commands/debug-teams.md index 641689a..916acc0 100644 --- a/plugins/devflow-debug/commands/debug-teams.md +++ b/plugins/devflow-debug/commands/debug-teams.md @@ -23,7 +23,11 @@ Investigate bugs by spawning a team of agents, each pursuing a different hypothe ## Phases -### Phase 1: Context Gathering +### Phase 1: Load Project Knowledge + +Read `.memory/knowledge/decisions.md` and `.memory/knowledge/pitfalls.md`. Known pitfalls from prior debugging sessions and code reviews can directly inform hypothesis generation — pass their content as context to investigators in Phase 2. + +### Phase 2: Context Gathering If `$ARGUMENTS` starts with `#`, fetch the GitHub issue: @@ -39,7 +43,7 @@ Analyze the bug description (from arguments or issue) and identify 3-5 plausible - **Testable**: Can be confirmed or disproved by reading code/logs - **Distinct**: Does not overlap significantly with other hypotheses -### Phase 2: Spawn Investigation Team +### Phase 3: Spawn Investigation Team Create an agent team with one investigator per hypothesis: @@ -99,7 +103,7 @@ Spawn investigator teammates with self-contained prompts: (Add more investigators if bug complexity warrants 4-5 hypotheses — same pattern) ``` -### Phase 3: Investigation +### Phase 4: Investigation Teammates investigate in parallel: - Read relevant source files @@ -108,7 +112,7 @@ Teammates investigate in parallel: - Look for edge cases and race conditions - Build evidence for or against their hypothesis -### Phase 4: Adversarial Debate +### Phase 5: Adversarial Debate Lead initiates debate via broadcast: @@ -135,7 +139,7 @@ Teammates challenge each other directly using SendMessage: - `SendMessage(type: "message", recipient: "team-lead", summary: "Updated hypothesis")` "I've updated my hypothesis based on investigator-b's finding at..." -### Phase 5: Convergence +### Phase 6: Convergence After debate (max 2 rounds), lead collects results: @@ -147,7 +151,7 @@ Lead broadcast: - PARTIAL: Some aspects confirmed, others not (details)" ``` -### Phase 6: Cleanup +### Phase 7: Cleanup Shut down all investigator teammates explicitly: @@ -160,7 +164,7 @@ TeamDelete Verify TeamDelete succeeded. If failed, retry once after 5s. If retry fails, HALT. ``` -### Phase 7: Report +### Phase 8: Report Lead produces final report: @@ -189,30 +193,40 @@ Lead produces final report: {HIGH/MEDIUM/LOW based on consensus strength} ``` +### Phase 9: Record Pitfall (if root cause found) + +If root cause was identified with HIGH or MEDIUM confidence: +1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md` +2. Source field: `/debug {bug description}` + ## Architecture ``` /debug (orchestrator) │ -├─ Phase 1: Context gathering +├─ Phase 1: Load Project Knowledge +│ +├─ Phase 2: Context gathering │ └─ Git agent (fetch issue, if #N provided) │ -├─ Phase 2: Spawn investigation team +├─ Phase 3: Spawn investigation team │ └─ Create team with 3-5 hypothesis investigators │ -├─ Phase 3: Parallel investigation +├─ Phase 4: Parallel investigation │ └─ Each teammate investigates independently │ -├─ Phase 4: Adversarial debate +├─ Phase 5: Adversarial debate │ └─ Teammates challenge each other directly (max 2 rounds) │ -├─ Phase 5: Convergence +├─ Phase 6: Convergence │ └─ Teammates submit final hypothesis status │ -├─ Phase 6: Cleanup +├─ Phase 7: Cleanup │ └─ Shut down teammates, release resources │ -└─ Phase 7: Root cause report with confidence level +├─ Phase 8: Root cause report with confidence level +│ +└─ Phase 9: Record Pitfall (inline, if root cause found) ``` ## Principles diff --git a/plugins/devflow-debug/commands/debug.md b/plugins/devflow-debug/commands/debug.md index 76be0d6..4088be6 100644 --- a/plugins/devflow-debug/commands/debug.md +++ b/plugins/devflow-debug/commands/debug.md @@ -23,7 +23,11 @@ Investigate bugs by spawning parallel agents, each pursuing a different hypothes ## Phases -### Phase 1: Context Gathering +### Phase 1: Load Project Knowledge + +Read `.memory/knowledge/decisions.md` and `.memory/knowledge/pitfalls.md`. Known pitfalls from prior debugging sessions and code reviews can directly inform hypothesis generation — pass their content as context to investigators in Phase 2. + +### Phase 2: Context Gathering If `$ARGUMENTS` starts with `#`, fetch the GitHub issue: @@ -39,7 +43,7 @@ Analyze the bug description (from arguments or issue) and identify 3-5 plausible - **Testable**: Can be confirmed or disproved by reading code/logs - **Distinct**: Does not overlap significantly with other hypotheses -### Phase 2: Investigate (Parallel) +### Phase 3: Investigate (Parallel) Spawn one Explore agent per hypothesis in a **single message** (parallel execution): @@ -82,7 +86,7 @@ Focus area: {specific code area, mechanism, or condition} (Add more investigators if bug complexity warrants 4-5 hypotheses) ``` -### Phase 3: Synthesize +### Phase 4: Synthesize Once all investigators return, spawn a Synthesizer agent to aggregate findings: @@ -100,7 +104,7 @@ Instructions: 5. Assess confidence level based on evidence strength" ``` -### Phase 4: Report +### Phase 5: Report Produce the final report: @@ -129,21 +133,31 @@ Produce the final report: {HIGH/MEDIUM/LOW based on evidence strength and investigator agreement} ``` +### Phase 6: Record Pitfall (if root cause found) + +If root cause was identified with HIGH or MEDIUM confidence: +1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md` +2. Source field: `/debug {bug description}` + ## Architecture ``` /debug (orchestrator) │ -├─ Phase 1: Context gathering +├─ Phase 1: Load Project Knowledge +│ +├─ Phase 2: Context gathering │ └─ Git agent (fetch issue, if #N provided) │ -├─ Phase 2: Parallel investigation +├─ Phase 3: Parallel investigation │ └─ 3-5 Explore agents, one per hypothesis (single message) │ -├─ Phase 3: Synthesize +├─ Phase 4: Synthesize │ └─ Synthesizer aggregates and compares findings │ -└─ Phase 4: Root cause report with confidence level +├─ Phase 5: Root cause report with confidence level +│ +└─ Phase 6: Record Pitfall (inline, if root cause found) ``` ## Principles diff --git a/plugins/devflow-implement/.claude-plugin/plugin.json b/plugins/devflow-implement/.claude-plugin/plugin.json index 1409f3a..694c01e 100644 --- a/plugins/devflow-implement/.claude-plugin/plugin.json +++ b/plugins/devflow-implement/.claude-plugin/plugin.json @@ -29,6 +29,7 @@ "skills": [ "agent-teams", "implementation-patterns", + "knowledge-persistence", "self-review" ] } diff --git a/plugins/devflow-implement/commands/implement-teams.md b/plugins/devflow-implement/commands/implement-teams.md index 7c41aa2..f841cf5 100644 --- a/plugins/devflow-implement/commands/implement-teams.md +++ b/plugins/devflow-implement/commands/implement-teams.md @@ -46,7 +46,7 @@ Return the branch setup summary." - `ISSUE_CONTENT`: Full issue body including description (if provided) - `ACCEPTANCE_CRITERIA`: Extracted acceptance criteria from issue (if provided) -### Phase 1.5: Orient +### Phase 2: Orient Spawn Skimmer agent for codebase overview: @@ -56,7 +56,7 @@ Task(subagent_type="Skimmer"): Use skim to identify relevant files, functions, integration points" ``` -### Phase 2: Exploration Team +### Phase 3: Exploration Team Create an agent team for collaborative codebase exploration: @@ -69,48 +69,56 @@ Spawn exploration teammates with self-contained prompts: Prompt: | You are exploring a codebase for task: {task description} 1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md` - 2. Skimmer context (files/patterns already identified): + 2. Read `.memory/knowledge/decisions.md` and `.memory/knowledge/pitfalls.md` if they exist. + Consider prior decisions and known pitfalls relevant to this task. + 3. Skimmer context (files/patterns already identified): {skimmer output} - 3. Your deliverable: Find similar implementations, established patterns, + 4. Your deliverable: Find similar implementations, established patterns, module structure, and architectural conventions relevant to this task. - 4. Document findings with file:path references. - 5. Report completion: SendMessage(type: "message", recipient: "team-lead", + 5. Document findings with file:path references. + 6. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Architecture exploration done") - Name: "integration-explorer" Prompt: | You are exploring a codebase for task: {task description} 1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md` - 2. Skimmer context (files/patterns already identified): + 2. Read `.memory/knowledge/decisions.md` and `.memory/knowledge/pitfalls.md` if they exist. + Consider prior decisions and known pitfalls relevant to this task. + 3. Skimmer context (files/patterns already identified): {skimmer output} - 3. Your deliverable: Find entry points, services, database models, + 4. Your deliverable: Find entry points, services, database models, configuration, and integration points relevant to this task. - 4. Document findings with file:path references. - 5. Report completion: SendMessage(type: "message", recipient: "team-lead", + 5. Document findings with file:path references. + 6. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Integration exploration done") - Name: "reusable-code-explorer" Prompt: | You are exploring a codebase for task: {task description} 1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md` - 2. Skimmer context (files/patterns already identified): + 2. Read `.memory/knowledge/decisions.md` and `.memory/knowledge/pitfalls.md` if they exist. + Consider prior decisions and known pitfalls relevant to this task. + 3. Skimmer context (files/patterns already identified): {skimmer output} - 3. Your deliverable: Find utilities, helpers, validation patterns, + 4. Your deliverable: Find utilities, helpers, validation patterns, and error handling that can be reused for this task. - 4. Document findings with file:path references. - 5. Report completion: SendMessage(type: "message", recipient: "team-lead", + 5. Document findings with file:path references. + 6. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Reusable code exploration done") - Name: "edge-case-explorer" Prompt: | You are exploring a codebase for task: {task description} 1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md` - 2. Skimmer context (files/patterns already identified): + 2. Read `.memory/knowledge/decisions.md` and `.memory/knowledge/pitfalls.md` if they exist. + Consider prior decisions and known pitfalls relevant to this task. + 3. Skimmer context (files/patterns already identified): {skimmer output} - 3. Your deliverable: Find error scenarios, race conditions, permission + 4. Your deliverable: Find error scenarios, race conditions, permission failures, and boundary cases relevant to this task. - 4. Document findings with file:path references. - 5. Report completion: SendMessage(type: "message", recipient: "team-lead", + 5. Document findings with file:path references. + 6. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Edge case exploration done") After initial exploration, lead initiates debate: @@ -125,7 +133,7 @@ Max 2 debate rounds, then submit consensus exploration findings. **Exploration team output**: Consensus findings on patterns, integration points, reusable code, edge cases. -**Team Shutdown Protocol** (must complete before Phase 4): +**Team Shutdown Protocol** (must complete before Phase 5): ``` Step 1: Shutdown each teammate @@ -142,7 +150,7 @@ Step 3: GATE — Verify TeamDelete succeeded If retry failed → HALT and report: "Exploration team cleanup failed. Cannot create planning team." ``` -### Phase 3: Synthesize Exploration +### Phase 4: Synthesize Exploration **CRITICAL**: Do NOT synthesize outputs yourself in the main session. You MUST spawn the Synthesizer agent. @@ -155,7 +163,7 @@ Explorer consensus: {team exploration consensus output} Combine into: patterns, integration points, reusable code, edge cases" ``` -### Phase 4: Planning Team +### Phase 5: Planning Team Create an agent team for collaborative implementation planning: @@ -169,7 +177,7 @@ Spawn planning teammates with self-contained prompts: You are planning implementation for task: {task description} 1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md` 2. Exploration synthesis (what we know about the codebase): - {synthesis output from Phase 3} + {synthesis output from Phase 4} 3. Your deliverable: Step-by-step coding approach with specific files to create/modify, dependencies between steps, and execution order. 4. Report completion: SendMessage(type: "message", recipient: "team-lead", @@ -180,7 +188,7 @@ Spawn planning teammates with self-contained prompts: You are planning the test strategy for task: {task description} 1. Read your skill: `Read ~/.claude/skills/test-patterns/SKILL.md` 2. Exploration synthesis (what we know about the codebase): - {synthesis output from Phase 3} + {synthesis output from Phase 4} 3. Your deliverable: Test strategy — unit tests, integration tests, edge case coverage, testing patterns to follow from the codebase. 4. Report completion: SendMessage(type: "message", recipient: "team-lead", @@ -191,7 +199,7 @@ Spawn planning teammates with self-contained prompts: You are assessing risk and execution strategy for task: {task description} 1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md` 2. Exploration synthesis (what we know about the codebase): - {synthesis output from Phase 3} + {synthesis output from Phase 4} 3. Your deliverable: Risk assessment, rollback strategy, and execution strategy decision (SINGLE_CODER vs SEQUENTIAL_CODERS vs PARALLEL_CODERS) based on artifact independence, context capacity, and domain specialization. @@ -222,7 +230,7 @@ Max 2 debate rounds, then submit consensus plan. - **HIGH**: 20-30 files, multiple modules → SEQUENTIAL_CODERS (2-3 phases) - **CRITICAL**: >30 files, cross-cutting concerns → SEQUENTIAL_CODERS (more phases) -**Team Shutdown Protocol** (must complete before Phase 6): +**Team Shutdown Protocol** (must complete before Phase 7): ``` Step 1: Shutdown each teammate @@ -238,7 +246,7 @@ Step 3: GATE — Verify TeamDelete succeeded If retry failed → HALT and report: "Planning team cleanup failed. Cannot proceed to implementation." ``` -### Phase 5: Synthesize Planning +### Phase 6: Synthesize Planning **CRITICAL**: Do NOT synthesize outputs yourself in the main session. You MUST spawn the Synthesizer agent. @@ -257,9 +265,9 @@ Combine into: execution plan with strategy decision (SINGLE_CODER | SEQUENTIAL_C - Subtask breakdown with DOMAIN hints (if not SINGLE_CODER) - Implementation plan with dependencies -### Phase 6: Implement +### Phase 7: Implement -Based on Phase 5 synthesis, use the three-strategy framework: +Based on Phase 6 synthesis, use the three-strategy framework: **Strategy Selection** (from planning team consensus): @@ -352,7 +360,7 @@ DOMAIN: {subtask 2 domain}" - Different files/modules with no imports between them - Each subtask is self-contained -### Phase 6.5: Validate +### Phase 8: Validate After Coder completes, spawn Validator to verify correctness: @@ -377,12 +385,12 @@ Run build, typecheck, lint, test. Report pass/fail with failure details." SCOPE: Fix only the listed failures, no other changes CREATE_PR: false" ``` - - Loop back to Phase 6.5 (re-validate) + - Loop back to Phase 8 (re-validate) 4. If `validation_retry_count > 2`: Report failures to user and halt -**If PASS:** Continue to Phase 7 +**If PASS:** Continue to Phase 9 -### Phase 7: Simplify +### Phase 9: Simplify After validation passes, spawn Simplifier to polish the code: @@ -394,7 +402,7 @@ FILES_CHANGED: {list of files from Coder output} Focus on code modified by Coder, apply project standards, enhance clarity" ``` -### Phase 8: Self-Review +### Phase 10: Self-Review After Simplifier completes, spawn Scrutinizer as final quality gate: @@ -407,7 +415,7 @@ Evaluate 9 pillars, fix P0/P1 issues, report status" If Scrutinizer returns BLOCKED, report to user and halt. -### Phase 8.5: Re-Validate (if Scrutinizer made changes) +### Phase 11: Re-Validate (if Scrutinizer made changes) If Scrutinizer made code changes (status: FIXED), spawn Validator to verify: @@ -420,9 +428,9 @@ Verify Scrutinizer's fixes didn't break anything." **If FAIL:** Report to user - Scrutinizer broke tests, needs manual intervention. -**If PASS:** Continue to Phase 9 +**If PASS:** Continue to Phase 12 -### Phase 9: Shepherd↔Coder Dialogue +### Phase 12: Shepherd↔Coder Dialogue After Scrutinizer passes (and re-validation if needed), check alignment using direct dialogue: @@ -437,7 +445,7 @@ Spawn teammates with self-contained prompts: Prompt: | You are validating that the implementation aligns with the original request. ORIGINAL_REQUEST: {task description or issue content} - EXECUTION_PLAN: {synthesized plan from Phase 5} + EXECUTION_PLAN: {synthesized plan from Phase 6} FILES_CHANGED: {list of files from Coder output} ACCEPTANCE_CRITERIA: {extracted criteria if available} @@ -472,7 +480,7 @@ Spawn teammates with self-contained prompts: summary: "Alignment fixes complete") ``` -**Team Shutdown Protocol** (must complete before Phase 10): +**Team Shutdown Protocol** (must complete before Phase 13): ``` Step 1: Shutdown each teammate @@ -487,7 +495,7 @@ Step 3: GATE — Verify TeamDelete succeeded If retry failed → HALT and report: "Alignment team cleanup failed." ``` -**If ALIGNED:** Continue to Phase 10 +**If ALIGNED:** Continue to Phase 13 **If MISALIGNED:** 1. Extract misalignment details from Shepherd output @@ -510,19 +518,26 @@ Step 3: GATE — Verify TeamDelete succeeded VALIDATION_SCOPE: changed-only" ``` - If Validator FAIL: Report to user - - If Validator PASS: Loop back to Phase 9 (re-check alignment) + - If Validator PASS: Loop back to Phase 12 (re-check alignment) 4. If `alignment_fix_count > 2`: Report misalignments to user for decision -### Phase 10: Create PR +### Phase 13: Create PR **For SEQUENTIAL_CODERS or PARALLEL_CODERS**: The last sequential Coder (with CREATE_PR: true) handles PR creation. For parallel coders, create unified PR using `git-workflow` skill patterns. Push branch and run `gh pr create` with comprehensive description, targeting `BASE_BRANCH`. **For SINGLE_CODER**: PR is created by the Coder agent (CREATE_PR: true). -### Phase 11: Report +### Phase 14: Report Display completion summary with phase status, PR info, and next steps. +### Phase 15: Record Decisions (if any) + +If the Coder's report includes Key Decisions with architectural significance: +1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record decisions to `.memory/knowledge/decisions.md` +2. Source field: `/implement {TASK_ID}` +3. Skip entirely if no architectural decisions were made + ## Architecture ``` @@ -531,55 +546,57 @@ Display completion summary with phase status, PR info, and next steps. ├─ Phase 1: Setup │ └─ Git agent (operation: setup-task) - creates feature branch, fetches issue │ -├─ Phase 1.5: Orient +├─ Phase 2: Orient │ └─ Skimmer agent (codebase overview via skim) │ -├─ Phase 2: Exploration Team (Agent Teams) +├─ Phase 3: Exploration Team (Agent Teams) │ ├─ Architecture Explorer (teammate) │ ├─ Integration Explorer (teammate) │ ├─ Reusable Code Explorer (teammate) │ ├─ Edge Case Explorer (teammate) │ └─ Debate → consensus exploration findings │ -├─ Phase 3: Synthesize Exploration +├─ Phase 4: Synthesize Exploration │ └─ Synthesizer agent (mode: exploration) │ -├─ Phase 4: Planning Team (Agent Teams) +├─ Phase 5: Planning Team (Agent Teams) │ ├─ Implementation Planner (teammate) │ ├─ Testing Planner (teammate) │ ├─ Risk & Execution Planner (teammate) │ └─ Debate → consensus plan with strategy decision │ -├─ Phase 5: Synthesize Planning +├─ Phase 6: Synthesize Planning │ └─ Synthesizer agent (mode: planning) → returns strategy + DOMAIN hints │ -├─ Phase 6: Implement (3-strategy framework) +├─ Phase 7: Implement (3-strategy framework) │ ├─ SINGLE_CODER (80%): One Coder, full plan, CREATE_PR: true │ ├─ SEQUENTIAL_CODERS (15%): N Coders with handoff summaries │ └─ PARALLEL_CODERS (5%): N Coders in single message (rare) │ -├─ Phase 6.5: Validate +├─ Phase 8: Validate │ └─ Validator agent (build, typecheck, lint, test) │ └─ If FAIL: Coder fix loop (max 2 retries) → re-validate │ -├─ Phase 7: Simplify +├─ Phase 9: Simplify │ └─ Simplifier agent (refines code clarity and consistency) │ -├─ Phase 8: Self-Review +├─ Phase 10: Self-Review │ └─ Scrutinizer agent (final quality gate, fixes P0/P1) │ -├─ Phase 8.5: Re-Validate (if Scrutinizer made changes) +├─ Phase 11: Re-Validate (if Scrutinizer made changes) │ └─ Validator agent (verify Scrutinizer fixes) │ -├─ Phase 9: Shepherd↔Coder Dialogue (Agent Teams) +├─ Phase 12: Shepherd↔Coder Dialogue (Agent Teams) │ └─ Direct Shepherd↔Coder messaging (max 2 exchanges) │ -├─ Phase 10: Create PR (if needed) +├─ Phase 13: Create PR (if needed) │ └─ SINGLE_CODER: handled by Coder │ └─ SEQUENTIAL: handled by last Coder │ └─ PARALLEL: orchestrator creates unified PR │ -└─ Phase 11: Display agent outputs +├─ Phase 14: Display agent outputs +│ +└─ Phase 15: Record Decisions (inline, if any) ``` ## Principles diff --git a/plugins/devflow-implement/commands/implement.md b/plugins/devflow-implement/commands/implement.md index 2a3cfc0..2af9e09 100644 --- a/plugins/devflow-implement/commands/implement.md +++ b/plugins/devflow-implement/commands/implement.md @@ -46,7 +46,7 @@ Return the branch setup summary." - `ISSUE_CONTENT`: Full issue body including description (if provided) - `ACCEPTANCE_CRITERIA`: Extracted acceptance criteria from issue (if provided) -### Phase 1.5: Orient +### Phase 2: Orient Spawn Skimmer agent for codebase overview: @@ -56,7 +56,7 @@ Task(subagent_type="Skimmer"): Use skim to identify relevant files, functions, integration points" ``` -### Phase 2: Explore (Parallel) +### Phase 3: Explore (Parallel) Spawn 4 Explore agents **in a single message**, each with Skimmer context: @@ -69,9 +69,9 @@ Spawn 4 Explore agents **in a single message**, each with Skimmer context: Track success/failure of each explorer for synthesis context. -### Phase 3: Synthesize Exploration +### Phase 4: Synthesize Exploration -**WAIT** for Phase 2 to complete. +**WAIT** for Phase 3 to complete. **CRITICAL**: Do NOT synthesize outputs yourself in the main session. You MUST spawn the Synthesizer agent - "spawn Synthesizer" means delegate to the agent, not do the work yourself. @@ -85,7 +85,7 @@ Failed explorations: {any failures} Combine into: patterns, integration points, reusable code, edge cases" ``` -### Phase 4: Plan (Parallel) +### Phase 5: Plan (Parallel) Spawn 3 Plan agents **in a single message**, each with exploration synthesis: @@ -109,9 +109,9 @@ Spawn 3 Plan agents **in a single message**, each with exploration synthesis: - **HIGH**: 20-30 files, multiple modules → SEQUENTIAL_CODERS (2-3 phases) - **CRITICAL**: >30 files, cross-cutting concerns → SEQUENTIAL_CODERS (more phases) -### Phase 5: Synthesize Planning +### Phase 6: Synthesize Planning -**WAIT** for Phase 4 to complete. +**WAIT** for Phase 5 to complete. **CRITICAL**: Do NOT synthesize outputs yourself in the main session. You MUST spawn the Synthesizer agent - "spawn Synthesizer" means delegate to the agent, not do the work yourself. @@ -130,9 +130,9 @@ Combine into: execution plan with strategy decision (SINGLE_CODER | SEQUENTIAL_C - Subtask breakdown with DOMAIN hints (if not SINGLE_CODER) - Implementation plan with dependencies -### Phase 6: Implement +### Phase 7: Implement -Based on Phase 5 synthesis, use the three-strategy framework: +Based on Phase 6 synthesis, use the three-strategy framework: **Strategy Selection** (from Execution Strategy planner): @@ -225,7 +225,7 @@ DOMAIN: {subtask 2 domain}" - Different files/modules with no imports between them - Each subtask is self-contained -### Phase 6.5: Validate +### Phase 8: Validate After Coder completes, spawn Validator to verify correctness: @@ -250,12 +250,12 @@ Run build, typecheck, lint, test. Report pass/fail with failure details." SCOPE: Fix only the listed failures, no other changes CREATE_PR: false" ``` - - Loop back to Phase 6.5 (re-validate) + - Loop back to Phase 8 (re-validate) 4. If `validation_retry_count > 2`: Report failures to user and halt -**If PASS:** Continue to Phase 7 +**If PASS:** Continue to Phase 9 -### Phase 7: Simplify +### Phase 9: Simplify After validation passes, spawn Simplifier to polish the code: @@ -267,7 +267,7 @@ FILES_CHANGED: {list of files from Coder output} Focus on code modified by Coder, apply project standards, enhance clarity" ``` -### Phase 8: Self-Review +### Phase 10: Self-Review After Simplifier completes, spawn Scrutinizer as final quality gate: @@ -280,7 +280,7 @@ Evaluate 9 pillars, fix P0/P1 issues, report status" If Scrutinizer returns BLOCKED, report to user and halt. -### Phase 8.5: Re-Validate (if Scrutinizer made changes) +### Phase 11: Re-Validate (if Scrutinizer made changes) If Scrutinizer made code changes (status: FIXED), spawn Validator to verify: @@ -293,22 +293,22 @@ Verify Scrutinizer's fixes didn't break anything." **If FAIL:** Report to user - Scrutinizer broke tests, needs manual intervention. -**If PASS:** Continue to Phase 9 +**If PASS:** Continue to Phase 12 -### Phase 9: Alignment Check +### Phase 12: Alignment Check After Scrutinizer passes (and re-validation if needed), spawn Shepherd to validate alignment: ``` Task(subagent_type="Shepherd"): "ORIGINAL_REQUEST: {task description or issue content} -EXECUTION_PLAN: {synthesized plan from Phase 5} +EXECUTION_PLAN: {synthesized plan from Phase 6} FILES_CHANGED: {list of files from Coder output} ACCEPTANCE_CRITERIA: {extracted criteria if available} Validate alignment with request and plan. Report ALIGNED or MISALIGNED with details." ``` -**If ALIGNED:** Continue to Phase 10 +**If ALIGNED:** Continue to Phase 13 **If MISALIGNED:** 1. Extract misalignment details from Shepherd output @@ -331,19 +331,26 @@ Validate alignment with request and plan. Report ALIGNED or MISALIGNED with deta VALIDATION_SCOPE: changed-only" ``` - If Validator FAIL: Report to user - - If Validator PASS: Loop back to Phase 9 (re-check alignment) + - If Validator PASS: Loop back to Phase 12 (re-check alignment) 4. If `alignment_fix_count > 2`: Report misalignments to user for decision -### Phase 10: Create PR +### Phase 13: Create PR **For SEQUENTIAL_CODERS or PARALLEL_CODERS**: The last sequential Coder (with CREATE_PR: true) handles PR creation. For parallel coders, create unified PR using `git-workflow` skill patterns. Push branch and run `gh pr create` with comprehensive description, targeting `BASE_BRANCH`. **For SINGLE_CODER**: PR is created by the Coder agent (CREATE_PR: true). -### Phase 11: Report +### Phase 14: Report Display completion summary with phase status, PR info, and next steps. +### Phase 15: Record Decisions (if any) + +If the Coder's report includes Key Decisions with architectural significance: +1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record decisions to `.memory/knowledge/decisions.md` +2. Source field: `/implement {TASK_ID}` +3. Skip entirely if no architectural decisions were made + ## Architecture ``` @@ -352,54 +359,56 @@ Display completion summary with phase status, PR info, and next steps. ├─ Phase 1: Setup │ └─ Git agent (operation: setup-task) - creates feature branch, fetches issue │ -├─ Phase 1.5: Orient +├─ Phase 2: Orient │ └─ Skimmer agent (codebase overview via skim) │ -├─ Phase 2: Explore (PARALLEL, with Skimmer context) +├─ Phase 3: Explore (PARALLEL, with Skimmer context) │ ├─ Explore: Architecture │ ├─ Explore: Integration │ ├─ Explore: Reusable code │ └─ Explore: Edge cases │ -├─ Phase 3: Synthesize Exploration +├─ Phase 4: Synthesize Exploration │ └─ Synthesizer agent (mode: exploration) │ -├─ Phase 4: Plan (PARALLEL) +├─ Phase 5: Plan (PARALLEL) │ ├─ Plan: Implementation steps │ ├─ Plan: Testing strategy │ └─ Plan: Execution strategy (3-strategy decision) │ -├─ Phase 5: Synthesize Planning +├─ Phase 6: Synthesize Planning │ └─ Synthesizer agent (mode: planning) → returns strategy + DOMAIN hints │ -├─ Phase 6: Implement (3-strategy framework) +├─ Phase 7: Implement (3-strategy framework) │ ├─ SINGLE_CODER (80%): One Coder, full plan, CREATE_PR: true │ ├─ SEQUENTIAL_CODERS (15%): N Coders with handoff summaries │ └─ PARALLEL_CODERS (5%): N Coders in single message (rare) │ -├─ Phase 6.5: Validate +├─ Phase 8: Validate │ └─ Validator agent (build, typecheck, lint, test) │ └─ If FAIL: Coder fix loop (max 2 retries) → re-validate │ -├─ Phase 7: Simplify +├─ Phase 9: Simplify │ └─ Simplifier agent (refines code clarity and consistency) │ -├─ Phase 8: Self-Review +├─ Phase 10: Self-Review │ └─ Scrutinizer agent (final quality gate, fixes P0/P1) │ -├─ Phase 8.5: Re-Validate (if Scrutinizer made changes) +├─ Phase 11: Re-Validate (if Scrutinizer made changes) │ └─ Validator agent (verify Scrutinizer fixes) │ -├─ Phase 9: Alignment Check +├─ Phase 12: Alignment Check │ └─ Shepherd agent (validates alignment - reports only, no fixes) │ └─ If MISALIGNED: Coder fix loop (max 2 iterations) → Validator → re-check │ -├─ Phase 10: Create PR (if needed) +├─ Phase 13: Create PR (if needed) │ └─ SINGLE_CODER: handled by Coder │ └─ SEQUENTIAL: handled by last Coder │ └─ PARALLEL: orchestrator creates unified PR │ -└─ Phase 11: Display agent outputs +├─ Phase 14: Display agent outputs +│ +└─ Phase 15: Record Decisions (inline, if any) ``` ## Principles diff --git a/plugins/devflow-resolve/.claude-plugin/plugin.json b/plugins/devflow-resolve/.claude-plugin/plugin.json index 7268945..2fd8ec8 100644 --- a/plugins/devflow-resolve/.claude-plugin/plugin.json +++ b/plugins/devflow-resolve/.claude-plugin/plugin.json @@ -21,8 +21,9 @@ "simplifier" ], "skills": [ + "agent-teams", "implementation-patterns", - "security-patterns", - "agent-teams" + "knowledge-persistence", + "security-patterns" ] } diff --git a/plugins/devflow-resolve/commands/resolve-teams.md b/plugins/devflow-resolve/commands/resolve-teams.md index b8b5841..efb81da 100644 --- a/plugins/devflow-resolve/commands/resolve-teams.md +++ b/plugins/devflow-resolve/commands/resolve-teams.md @@ -150,7 +150,14 @@ Aggregate from all Resolvers: - **Deferred**: High-risk issues marked for tech debt - **Blocked**: Issues that couldn't be fixed -### Phase 6: Simplify +### Phase 6: Record Pitfalls (from tech debt deferrals) + +For each issue deferred as TECH_DEBT: +1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md` +2. Source field: `/resolve {branch}` +3. Skip entirely if no TECH_DEBT deferrals + +### Phase 7: Simplify If any fixes were made, spawn Simplifier agent to refine the changed code: @@ -161,7 +168,7 @@ FILES_CHANGED: {list of files modified by Resolvers} Simplify and refine the fixes for clarity and consistency" ``` -### Phase 7: Manage Tech Debt +### Phase 8: Manage Tech Debt If any issues were deferred, spawn Git agent: @@ -173,7 +180,7 @@ TIMESTAMP: {timestamp} Note: Deferred issues from resolution are already in resolution-summary.{timestamp}.md" ``` -### Phase 8: Report +### Phase 9: Report **Write the resolution summary** to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md` using Write tool, then display: @@ -228,13 +235,15 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta ├─ Phase 5: Collect results │ └─ Aggregate fixed, false positives, deferred, blocked │ -├─ Phase 6: Simplify +├─ Phase 6: Record Pitfalls (inline, from tech debt deferrals) +│ +├─ Phase 7: Simplify │ └─ Simplifier agent (refine fixes) │ -├─ Phase 7: Git agent (manage-debt) +├─ Phase 8: Git agent (manage-debt) │ └─ Add deferred items to Tech Debt Backlog │ -└─ Phase 8: Display resolution summary +└─ Phase 9: Display resolution summary ``` ## Edge Cases @@ -258,7 +267,7 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta ## Output Artifact -Written by orchestrator in Phase 8 to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md`: +Written by orchestrator in Phase 9 to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md`: ```markdown # Resolution Summary diff --git a/plugins/devflow-resolve/commands/resolve.md b/plugins/devflow-resolve/commands/resolve.md index 23a176c..37e7828 100644 --- a/plugins/devflow-resolve/commands/resolve.md +++ b/plugins/devflow-resolve/commands/resolve.md @@ -90,7 +90,14 @@ Aggregate from all Resolvers: - **Deferred**: High-risk issues marked for tech debt - **Blocked**: Issues that couldn't be fixed -### Phase 6: Simplify +### Phase 6: Record Pitfalls (from tech debt deferrals) + +For each issue deferred as TECH_DEBT: +1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md` +2. Source field: `/resolve {branch}` +3. Skip entirely if no TECH_DEBT deferrals + +### Phase 7: Simplify If any fixes were made, spawn Simplifier agent to refine the changed code: @@ -101,7 +108,7 @@ FILES_CHANGED: {list of files modified by Resolvers} Simplify and refine the fixes for clarity and consistency" ``` -### Phase 7: Manage Tech Debt +### Phase 8: Manage Tech Debt If any issues were deferred, spawn Git agent: @@ -113,7 +120,7 @@ TIMESTAMP: {timestamp} Note: Deferred issues from resolution are already in resolution-summary.{timestamp}.md" ``` -### Phase 8: Report +### Phase 9: Report **Write the resolution summary** to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md` using Write tool, then display: @@ -167,13 +174,15 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta ├─ Phase 5: Collect results │ └─ Aggregate fixed, false positives, deferred, blocked │ -├─ Phase 6: Simplify +├─ Phase 6: Record Pitfalls (inline, from tech debt deferrals) +│ +├─ Phase 7: Simplify │ └─ Simplifier agent (refine fixes) │ -├─ Phase 7: Git agent (manage-debt) +├─ Phase 8: Git agent (manage-debt) │ └─ Add deferred items to Tech Debt Backlog │ -└─ Phase 8: Display resolution summary +└─ Phase 9: Display resolution summary ``` ## Edge Cases @@ -197,7 +206,7 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta ## Output Artifact -Written by orchestrator in Phase 8 to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md`: +Written by orchestrator in Phase 9 to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md`: ```markdown # Resolution Summary diff --git a/plugins/devflow-self-review/commands/self-review.md b/plugins/devflow-self-review/commands/self-review.md index 15cae50..de4ba58 100644 --- a/plugins/devflow-self-review/commands/self-review.md +++ b/plugins/devflow-self-review/commands/self-review.md @@ -21,8 +21,9 @@ Detect changed files and build context: 2. Else run `git diff --name-only HEAD` + `git diff --name-only --cached` to get staged + unstaged 3. If no changes found, report "No changes to review" and exit 4. Build TASK_DESCRIPTION from recent commit messages or branch name +5. Read `.memory/knowledge/pitfalls.md` and `.memory/knowledge/decisions.md`. Pass as KNOWLEDGE_CONTEXT to Simplifier and Scrutinizer — known pitfalls help identify reintroduced issues, prior decisions help validate architectural consistency. -**Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string) +**Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), KNOWLEDGE_CONTEXT (string, optional) ### Phase 1: Simplifier (Code Refinement) @@ -31,7 +32,9 @@ Spawn Simplifier agent to refine code for clarity and consistency: Task(subagent_type="Simplifier", run_in_background=false): "TASK_DESCRIPTION: {task_description} FILES_CHANGED: {files_changed} -Simplify and refine the code for clarity and consistency while preserving functionality" +KNOWLEDGE_CONTEXT: {knowledge_context or 'None'} +Simplify and refine the code for clarity and consistency while preserving functionality. +If knowledge context is provided, verify no known pitfall patterns are being reintroduced." **Wait for completion.** Simplifier commits changes directly. @@ -42,7 +45,9 @@ Spawn Scrutinizer agent for quality evaluation and fixing: Task(subagent_type="Scrutinizer", run_in_background=false): "TASK_DESCRIPTION: {task_description} FILES_CHANGED: {files_changed} -Evaluate against 9-pillar framework. Fix P0/P1 issues. Return structured report." +KNOWLEDGE_CONTEXT: {knowledge_context or 'None'} +Evaluate against 9-pillar framework. Fix P0/P1 issues. Return structured report. +If knowledge context is provided, check whether any known pitfall patterns are being reintroduced and verify architectural consistency with prior decisions." **Wait for completion.** Extract: STATUS (PASS|FIXED|BLOCKED), changes_made (bool) @@ -93,7 +98,8 @@ Display summary: /self-review (orchestrator) │ ├─ Phase 0: Context gathering -│ └─ Git diff for changed files +│ ├─ Git diff for changed files +│ └─ Read project knowledge (decisions.md + pitfalls.md) │ ├─ Phase 1: Simplifier │ └─ Code refinement (commits directly) diff --git a/plugins/devflow-specify/commands/specify-teams.md b/plugins/devflow-specify/commands/specify-teams.md index bb86199..1779b95 100644 --- a/plugins/devflow-specify/commands/specify-teams.md +++ b/plugins/devflow-specify/commands/specify-teams.md @@ -57,7 +57,11 @@ Find: project structure, similar features, patterns, integration points Return: codebase context for requirements (not implementation details)" ``` -### Phase 3: Explore Requirements (Agent Teams) +### Phase 3: Load Project Knowledge + +Read `.memory/knowledge/decisions.md` and `.memory/knowledge/pitfalls.md`. Pass their content as context to the exploration team below — prior decisions constrain requirements, known pitfalls inform failure modes. + +### Phase 4: Explore Requirements (Agent Teams) Create an agent team for collaborative requirements exploration: @@ -122,7 +126,7 @@ Max 2 debate rounds, then submit consensus requirements findings. **Exploration team output**: Consensus findings on user needs, similar features, constraints, failure modes. -**Team Shutdown Protocol** (must complete before Phase 5): +**Team Shutdown Protocol** (must complete before Phase 6): ``` Step 1: Shutdown each teammate @@ -139,9 +143,9 @@ Step 3: GATE — Verify TeamDelete succeeded If retry failed → HALT and report: "Exploration team cleanup failed. Cannot create planning team." ``` -### Phase 4: Synthesize Exploration +### Phase 5: Synthesize Exploration -**WAIT** for Phase 3, then spawn Synthesizer: +**WAIT** for Phase 4, then spawn Synthesizer: ``` Task(subagent_type="Synthesizer"): @@ -151,7 +155,7 @@ Explorer consensus: {team exploration consensus output} Combine into: user needs, similar features, constraints, failure modes" ``` -### Phase 5: Plan Scope (Agent Teams) +### Phase 6: Plan Scope (Agent Teams) Create an agent team for collaborative scope planning: @@ -164,7 +168,7 @@ Spawn planning teammates with self-contained prompts: Prompt: | You are planning scope for feature: {feature} Exploration synthesis (what we know): - {synthesis output from Phase 4} + {synthesis output from Phase 5} Your deliverable: User stories in "As X, I want Y, so that Z" format. Cover all actors, actions, and outcomes identified in exploration. @@ -175,7 +179,7 @@ Spawn planning teammates with self-contained prompts: Prompt: | You are planning scope for feature: {feature} Exploration synthesis (what we know): - {synthesis output from Phase 4} + {synthesis output from Phase 5} Your deliverable: v1 MVP scope, v2 deferred items, explicitly out of scope, and dependencies on other features or systems. @@ -186,7 +190,7 @@ Spawn planning teammates with self-contained prompts: Prompt: | You are planning scope for feature: {feature} Exploration synthesis (what we know): - {synthesis output from Phase 4} + {synthesis output from Phase 5} Your deliverable: Testable acceptance criteria for success cases, failure cases, and edge cases. Every criterion must be verifiable. @@ -221,9 +225,9 @@ Step 3: GATE — Verify TeamDelete succeeded If retry failed → HALT and report: "Planning team cleanup failed. Cannot proceed to Gate 1." ``` -### Phase 6: Synthesize Planning +### Phase 7: Synthesize Planning -**WAIT** for Phase 5, then spawn Synthesizer: +**WAIT** for Phase 6, then spawn Synthesizer: ``` Task(subagent_type="Synthesizer"): @@ -233,7 +237,7 @@ Planner consensus: {team planning consensus output} Combine into: user stories, scope breakdown, acceptance criteria, open questions" ``` -### Phase 7: Gate 1 - Validate Scope +### Phase 8: Gate 1 - Validate Scope Use AskUserQuestion to validate: - Primary problem being solved @@ -241,14 +245,14 @@ Use AskUserQuestion to validate: - v1 scope selection (minimal/medium/full) - Explicit exclusions -### Phase 8: Gate 2 - Confirm Criteria +### Phase 9: Gate 2 - Confirm Criteria Present specification summary, then use AskUserQuestion for final confirmation: - Success UX pattern - Error handling approach - Ready to create issue / Needs changes / Cancel -### Phase 9: Create Issue +### Phase 10: Create Issue Create GitHub issue with `gh issue create`: - Title: feature name @@ -268,32 +272,35 @@ Report issue number and URL. ├─ Phase 2: Orient │ └─ Skimmer agent (codebase context via skim) │ -├─ Phase 3: Explore Requirements (Agent Teams) +├─ Phase 3: Load Project Knowledge +│ └─ Read decisions.md + pitfalls.md +│ +├─ Phase 4: Explore Requirements (Agent Teams) │ ├─ User Perspective Explorer (teammate) │ ├─ Similar Features Explorer (teammate) │ ├─ Constraints Explorer (teammate) │ ├─ Failure Mode Explorer (teammate) │ └─ Debate → consensus requirements findings │ -├─ Phase 4: Synthesize Exploration +├─ Phase 5: Synthesize Exploration │ └─ Synthesizer agent (mode: exploration) │ -├─ Phase 5: Plan Scope (Agent Teams) +├─ Phase 6: Plan Scope (Agent Teams) │ ├─ User Stories Planner (teammate) │ ├─ Scope Boundaries Planner (teammate) │ ├─ Acceptance Criteria Planner (teammate) │ └─ Debate → consensus scope plan │ -├─ Phase 6: Synthesize Planning +├─ Phase 7: Synthesize Planning │ └─ Synthesizer agent (mode: planning) │ -├─ Phase 7: GATE 1 - Validate Scope ⛔ MANDATORY +├─ Phase 8: GATE 1 - Validate Scope ⛔ MANDATORY │ └─ AskUserQuestion: Confirm scope and priorities │ -├─ Phase 8: GATE 2 - Confirm Criteria ⛔ MANDATORY +├─ Phase 9: GATE 2 - Confirm Criteria ⛔ MANDATORY │ └─ AskUserQuestion: Final spec approval │ -├─ Phase 9: Create Issue +├─ Phase 10: Create Issue │ └─ gh issue create │ └─ Report: Issue number, URL, /implement command diff --git a/plugins/devflow-specify/commands/specify.md b/plugins/devflow-specify/commands/specify.md index 57fd18d..d187e5c 100644 --- a/plugins/devflow-specify/commands/specify.md +++ b/plugins/devflow-specify/commands/specify.md @@ -57,20 +57,24 @@ Find: project structure, similar features, patterns, integration points Return: codebase context for requirements (not implementation details)" ``` -### Phase 3: Explore Requirements (Parallel) +### Phase 3: Load Project Knowledge -Spawn 4 Explore agents **in a single message**, each with Skimmer context: +Read `.memory/knowledge/decisions.md` and `.memory/knowledge/pitfalls.md`. Pass their content as context to the Explore agents below — prior decisions constrain requirements, known pitfalls inform failure modes. + +### Phase 4: Explore Requirements (Parallel) + +Spawn 4 Explore agents **in a single message**, each with Skimmer context and project knowledge (if loaded): | Focus | Thoroughness | Find | |-------|-------------|------| | User perspective | medium | Target users, goals, pain points, user journeys | | Similar features | medium | Comparable features, scope patterns, edge cases | -| Constraints | quick | Dependencies, business rules, security, performance | -| Failure modes | quick | Error states, edge cases, validation needs | +| Constraints | quick | Dependencies, business rules, security, performance, **prior architectural decisions** | +| Failure modes | quick | Error states, edge cases, validation needs, **known pitfalls** | -### Phase 4: Synthesize Exploration +### Phase 5: Synthesize Exploration -**WAIT** for Phase 3, then spawn Synthesizer: +**WAIT** for Phase 4, then spawn Synthesizer: ``` Task(subagent_type="Synthesizer"): @@ -79,7 +83,7 @@ Mode: exploration Combine into: user needs, similar features, constraints, failure modes" ``` -### Phase 5: Plan Scope (Parallel) +### Phase 6: Plan Scope (Parallel) Spawn 3 Plan agents **in a single message**, each with exploration synthesis: @@ -89,9 +93,9 @@ Spawn 3 Plan agents **in a single message**, each with exploration synthesis: | Scope boundaries | v1 MVP, v2 deferred, out of scope, dependencies | | Acceptance criteria | Success/failure/edge case criteria (testable) | -### Phase 6: Synthesize Planning +### Phase 7: Synthesize Planning -**WAIT** for Phase 5, then spawn Synthesizer: +**WAIT** for Phase 6, then spawn Synthesizer: ``` Task(subagent_type="Synthesizer"): @@ -100,7 +104,7 @@ Mode: planning Combine into: user stories, scope breakdown, acceptance criteria, open questions" ``` -### Phase 7: Gate 1 - Validate Scope +### Phase 8: Gate 1 - Validate Scope Use AskUserQuestion to validate: - Primary problem being solved @@ -108,14 +112,14 @@ Use AskUserQuestion to validate: - v1 scope selection (minimal/medium/full) - Explicit exclusions -### Phase 8: Gate 2 - Confirm Criteria +### Phase 9: Gate 2 - Confirm Criteria Present specification summary, then use AskUserQuestion for final confirmation: - Success UX pattern - Error handling approach - Ready to create issue / Needs changes / Cancel -### Phase 9: Create Issue +### Phase 10: Create Issue Create GitHub issue with `gh issue create`: - Title: feature name @@ -135,30 +139,33 @@ Report issue number and URL. ├─ Phase 2: Orient │ └─ Skimmer agent (codebase context via skim) │ -├─ Phase 3: Explore Requirements (PARALLEL) +├─ Phase 3: Load Project Knowledge +│ └─ Read decisions.md + pitfalls.md +│ +├─ Phase 4: Explore Requirements (PARALLEL) │ ├─ Explore: User perspective │ ├─ Explore: Similar features │ ├─ Explore: Constraints │ └─ Explore: Failure modes │ -├─ Phase 4: Synthesize Exploration +├─ Phase 5: Synthesize Exploration │ └─ Synthesizer agent (mode: exploration) │ -├─ Phase 5: Plan Scope (PARALLEL) +├─ Phase 6: Plan Scope (PARALLEL) │ ├─ Plan: User stories │ ├─ Plan: Scope boundaries │ └─ Plan: Acceptance criteria │ -├─ Phase 6: Synthesize Planning +├─ Phase 7: Synthesize Planning │ └─ Synthesizer agent (mode: planning) │ -├─ Phase 7: GATE 1 - Validate Scope ⛔ MANDATORY +├─ Phase 8: GATE 1 - Validate Scope ⛔ MANDATORY │ └─ AskUserQuestion: Confirm scope and priorities │ -├─ Phase 8: GATE 2 - Confirm Criteria ⛔ MANDATORY +├─ Phase 9: GATE 2 - Confirm Criteria ⛔ MANDATORY │ └─ AskUserQuestion: Final spec approval │ -├─ Phase 9: Create Issue +├─ Phase 10: Create Issue │ └─ gh issue create │ └─ Report: Issue number, URL, /implement command diff --git a/scripts/hooks/session-start-memory b/scripts/hooks/session-start-memory index 474d051..f70613e 100644 --- a/scripts/hooks/session-start-memory +++ b/scripts/hooks/session-start-memory @@ -119,6 +119,31 @@ ${COMPACT_NOTE}" fi fi +# --- Section 1.5: Project Knowledge TL;DR --- +KNOWLEDGE_DIR="$CWD/.memory/knowledge" +if [ -d "$KNOWLEDGE_DIR" ]; then + KNOWLEDGE_TLDR="" + for kf in "$KNOWLEDGE_DIR"/decisions.md "$KNOWLEDGE_DIR"/pitfalls.md; do + if [ -f "$kf" ]; then + TLDR_LINE=$(sed -n '1s//\1/p' "$kf") + if [ -n "$TLDR_LINE" ]; then + KNOWLEDGE_TLDR="${KNOWLEDGE_TLDR}${TLDR_LINE}\n" + fi + fi + done + if [ -n "$KNOWLEDGE_TLDR" ]; then + KNOWLEDGE_SECTION="--- PROJECT KNOWLEDGE (TL;DR) --- +$(printf '%b' "$KNOWLEDGE_TLDR")" + if [ -n "$CONTEXT" ]; then + CONTEXT="${CONTEXT} + +${KNOWLEDGE_SECTION}" + else + CONTEXT="$KNOWLEDGE_SECTION" + fi + fi +fi + # --- Section 2: Ambient Skill Injection --- # Inject ambient-router SKILL.md directly into context so Claude doesn't need a Read call. @@ -129,10 +154,15 @@ AMBIENT_SKILL_PATH="$HOME/.claude/skills/ambient-router/SKILL.md" SETTINGS_FILE="$HOME/.claude/settings.json" if [ -f "$AMBIENT_SKILL_PATH" ] && [ -f "$SETTINGS_FILE" ] && grep -q "ambient-prompt" "$SETTINGS_FILE" 2>/dev/null; then AMBIENT_SKILL_CONTENT=$(cat "$AMBIENT_SKILL_PATH") - CONTEXT="${CONTEXT} - ---- AMBIENT ROUTER (auto-loaded) --- + AMBIENT_SECTION="--- AMBIENT ROUTER (auto-loaded) --- ${AMBIENT_SKILL_CONTENT}" + if [ -n "$CONTEXT" ]; then + CONTEXT="${CONTEXT} + +${AMBIENT_SECTION}" + else + CONTEXT="$AMBIENT_SECTION" + fi fi # --- Output --- diff --git a/shared/agents/coder.md b/shared/agents/coder.md index c33dc97..962dc7e 100644 --- a/shared/agents/coder.md +++ b/shared/agents/coder.md @@ -35,6 +35,8 @@ You receive from orchestrator: - Cross-reference changed files against EXECUTION_PLAN to identify what's relevant to your task - Read those relevant files to understand interfaces, types, naming conventions, error handling, and testing patterns established by prior work - If PRIOR_PHASE_SUMMARY is provided, use it to validate your understanding — actual code is authoritative, summaries are supplementary + - If `.memory/knowledge/decisions.md` exists, read it. Apply prior architectural decisions relevant to this task. Avoid contradicting accepted decisions without documenting a new ADR. + - If `.memory/knowledge/pitfalls.md` exists, scan for pitfalls in files you're about to modify. 2. **Load domain skills**: Based on DOMAIN hint and files in scope, dynamically load relevant language/ecosystem skills by reading their SKILL.md. Only load skills that are installed: - `backend` (TypeScript): Read `~/.claude/skills/typescript/SKILL.md`, `~/.claude/skills/input-validation/SKILL.md` @@ -89,6 +91,9 @@ Return structured completion status: ### PR (if created) - URL: {pr_url} +### Key Decisions (if any) +- {Decision}: {rationale} + ### Blockers (if any) {Description of blocker or failure with recommendation} ``` diff --git a/shared/agents/reviewer.md b/shared/agents/reviewer.md index 95c4f5a..6eac4a0 100644 --- a/shared/agents/reviewer.md +++ b/shared/agents/reviewer.md @@ -42,15 +42,16 @@ 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. **Assess confidence** - Assign 0-100% confidence to each finding (see Confidence Scale below) -7. **Filter by confidence** - Only report findings ≥80% in main sections; lower-confidence items go to Suggestions -8. **Consolidate similar issues** - Group related findings to reduce noise (see Consolidation Rules) -9. **Generate report** - File:line references with suggested fixes -10. **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 diff --git a/shared/agents/skimmer.md b/shared/agents/skimmer.md index 284cdd7..c0c896f 100644 --- a/shared/agents/skimmer.md +++ b/shared/agents/skimmer.md @@ -20,6 +20,7 @@ You receive from orchestrator: 3. **Search for task-relevant code** - Find files matching task keywords 4. **Identify integration points** - Exports, entry points, import patterns 5. **Generate orientation summary** - Structured output for implementation planning +6. **Check project knowledge** - If `.memory/knowledge/decisions.md` exists, read its `` first-line comment and include active decision count in orientation under "### Active Decisions". Only the TL;DR is read here (not full entries) — this is intentional for token efficiency; agents that need full entries read the file themselves. ## Tool Invocation @@ -64,6 +65,9 @@ Always invoke skim via `npx rskim`. This works whether or not skim is globally i ### Patterns Observed {Existing patterns to follow} +### Active Decisions +{Count and key decisions from `.memory/knowledge/decisions.md` TL;DR, or "None found" if file missing} + ### Suggested Approach {Brief recommendation based on codebase structure} ``` diff --git a/shared/skills/docs-framework/SKILL.md b/shared/skills/docs-framework/SKILL.md index 4dbba0a..573b4b1 100644 --- a/shared/skills/docs-framework/SKILL.md +++ b/shared/skills/docs-framework/SKILL.md @@ -39,7 +39,10 @@ All generated documentation lives under `.docs/` in the project root: .memory/ ├── WORKING-MEMORY.md # Auto-maintained by Stop hook (overwritten) ├── PROJECT-PATTERNS.md # Accumulated patterns (merged across sessions) -└── backup.json # Pre-compact git state snapshot +├── backup.json # Pre-compact git state snapshot +└── knowledge/ + ├── decisions.md # Architectural decisions (ADR-NNN format) + └── pitfalls.md # Known pitfalls (PF-NNN format) ``` --- @@ -97,6 +100,8 @@ source .devflow/scripts/docs-helpers.sh 2>/dev/null || { |-------|-----------------|----------| | Reviewer | `.docs/reviews/{branch-slug}/{type}-report.{timestamp}.md` | Creates new | | Working Memory | `.memory/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) | +| Knowledge (decisions) | `.memory/knowledge/decisions.md` | Append-only (ADR-NNN sequential IDs) | +| Knowledge (pitfalls) | `.memory/knowledge/pitfalls.md` | Append-only (PF-NNN sequential IDs) | ### Agents That Don't Persist @@ -125,6 +130,7 @@ When creating or modifying persisting agents: This framework is used by: - **Review agents**: Creates review reports - **Working Memory hooks**: Auto-maintains `.memory/WORKING-MEMORY.md` +- **Command flows**: `/implement` appends ADRs to `decisions.md`; `/code-review`, `/debug`, `/resolve` append PFs to `pitfalls.md` All persisting agents should load this skill to ensure consistent documentation. diff --git a/shared/skills/knowledge-persistence/SKILL.md b/shared/skills/knowledge-persistence/SKILL.md new file mode 100644 index 0000000..f203548 --- /dev/null +++ b/shared/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): +``` + +# 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): +``` + +# 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 `` 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 diff --git a/shared/skills/knowledge-persistence/references/examples.md b/shared/skills/knowledge-persistence/references/examples.md new file mode 100644 index 0000000..ec78c86 --- /dev/null +++ b/shared/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. diff --git a/src/cli/plugins.ts b/src/cli/plugins.ts index 063c999..67cdc62 100644 --- a/src/cli/plugins.ts +++ b/src/cli/plugins.ts @@ -38,28 +38,28 @@ export const DEVFLOW_PLUGINS: PluginDefinition[] = [ description: 'Complete task implementation workflow', commands: ['/implement'], agents: ['git', 'skimmer', 'synthesizer', 'coder', 'simplifier', 'scrutinizer', 'shepherd', 'validator'], - skills: ['agent-teams', 'implementation-patterns', 'self-review'], + skills: ['agent-teams', 'implementation-patterns', 'knowledge-persistence', 'self-review'], }, { name: 'devflow-code-review', description: 'Comprehensive code review', commands: ['/code-review'], agents: ['git', 'reviewer', 'synthesizer'], - skills: ['agent-teams', 'architecture-patterns', 'complexity-patterns', 'consistency-patterns', 'database-patterns', 'dependencies-patterns', 'documentation-patterns', 'performance-patterns', 'regression-patterns', 'review-methodology', 'security-patterns', 'test-patterns'], + skills: ['agent-teams', 'architecture-patterns', 'complexity-patterns', 'consistency-patterns', 'database-patterns', 'dependencies-patterns', 'documentation-patterns', 'knowledge-persistence', 'performance-patterns', 'regression-patterns', 'review-methodology', 'security-patterns', 'test-patterns'], }, { name: 'devflow-resolve', description: 'Process and fix review issues', commands: ['/resolve'], agents: ['git', 'resolver', 'simplifier'], - skills: ['agent-teams', 'implementation-patterns', 'security-patterns'], + skills: ['agent-teams', 'implementation-patterns', 'knowledge-persistence', 'security-patterns'], }, { name: 'devflow-debug', description: 'Debugging with competing hypotheses', commands: ['/debug'], agents: ['git'], - skills: ['agent-teams', 'git-safety'], + skills: ['agent-teams', 'git-safety', 'knowledge-persistence'], }, { name: 'devflow-self-review', diff --git a/src/cli/utils/post-install.ts b/src/cli/utils/post-install.ts index 94b6fd6..6ed54d8 100644 --- a/src/cli/utils/post-install.ts +++ b/src/cli/utils/post-install.ts @@ -478,10 +478,15 @@ export async function createMemoryDir(verbose: boolean, cwd?: string): Promise { expect(stat.isDirectory()).toBe(true); }); + it('creates .memory/knowledge/ subdirectory', async () => { + await createMemoryDir(false, tmpDir); + const stat = await fs.stat(path.join(tmpDir, '.memory', 'knowledge')); + expect(stat.isDirectory()).toBe(true); + }); + it('is idempotent — calling twice succeeds without error', async () => { await createMemoryDir(false, tmpDir); await createMemoryDir(false, tmpDir); const stat = await fs.stat(path.join(tmpDir, '.memory')); expect(stat.isDirectory()).toBe(true); + const knowledgeStat = await fs.stat(path.join(tmpDir, '.memory', 'knowledge')); + expect(knowledgeStat.isDirectory()).toBe(true); + }); + + it('does not throw when path is invalid (verbose logs warning)', async () => { + // Create a file where the directory would go — mkdir will fail + const blockerPath = path.join(tmpDir, '.memory'); + await fs.writeFile(blockerPath, 'not a directory'); + + // Should not throw even though mkdir fails + await expect(createMemoryDir(false, tmpDir)).resolves.toBeUndefined(); }); }); @@ -334,3 +352,215 @@ describe('migrateMemoryFiles', () => { await expect(fs.access(path.join(docsDir, '.working-memory.lock'))).rejects.toThrow(); }); }); + +describe('knowledge file format', () => { + let tmpDir: string; + + beforeEach(async () => { + tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'devflow-test-')); + await fs.mkdir(path.join(tmpDir, '.memory', 'knowledge'), { recursive: true }); + }); + + afterEach(async () => { + await fs.rm(tmpDir, { recursive: true, force: true }); + }); + + it('parses TL;DR from decisions.md comment header', async () => { + const content = '\n# Architectural Decisions'; + await fs.writeFile(path.join(tmpDir, '.memory', 'knowledge', 'decisions.md'), content); + + const firstLine = (await fs.readFile(path.join(tmpDir, '.memory', 'knowledge', 'decisions.md'), 'utf-8')).split('\n')[0]; + const tldr = firstLine.replace('', ''); + + expect(tldr).toBe('2 decisions. Key: ADR-001 Result types, ADR-002 Single-coder'); + }); + + it('parses TL;DR from pitfalls.md comment header', async () => { + const content = '\n# Known Pitfalls'; + await fs.writeFile(path.join(tmpDir, '.memory', 'knowledge', 'pitfalls.md'), content); + + const firstLine = (await fs.readFile(path.join(tmpDir, '.memory', 'knowledge', 'pitfalls.md'), 'utf-8')).split('\n')[0]; + const tldr = firstLine.replace('', ''); + + expect(tldr).toBe('1 pitfall. Key: PF-001 Synthesizer glob'); + }); + + it('extracts highest ADR number via regex', async () => { + const content = [ + '', + '# Architectural Decisions', + '', + '## ADR-001: First decision', + '- **Status**: Accepted', + '', + '## ADR-002: Second decision', + '- **Status**: Accepted', + '', + '## ADR-003: Third decision', + '- **Status**: Accepted', + ].join('\n'); + await fs.writeFile(path.join(tmpDir, '.memory', 'knowledge', 'decisions.md'), content); + + const fileContent = await fs.readFile(path.join(tmpDir, '.memory', 'knowledge', 'decisions.md'), 'utf-8'); + const matches = [...fileContent.matchAll(/^## ADR-(\d+)/gm)]; + const highest = matches.length > 0 ? Math.max(...matches.map(m => parseInt(m[1], 10))) : 0; + + expect(highest).toBe(3); + }); + + it('returns 0 for empty file with no ADR entries', async () => { + const content = '\n# Architectural Decisions\n\nAppend-only.'; + await fs.writeFile(path.join(tmpDir, '.memory', 'knowledge', 'decisions.md'), content); + + const fileContent = await fs.readFile(path.join(tmpDir, '.memory', 'knowledge', 'decisions.md'), 'utf-8'); + const matches = [...fileContent.matchAll(/^## ADR-(\d+)/gm)]; + const highest = matches.length > 0 ? Math.max(...matches.map(m => parseInt(m[1], 10))) : 0; + + expect(highest).toBe(0); + }); + + it('detects duplicate pitfall by Area + Issue match', async () => { + const content = [ + '', + '# Known Pitfalls', + '', + '## PF-001: Synthesizer review glob matched zero files', + '- **Area**: shared/agents/synthesizer.md', + '- **Issue**: Glob didn\'t match reviewer output filenames', + ].join('\n'); + await fs.writeFile(path.join(tmpDir, '.memory', 'knowledge', 'pitfalls.md'), content); + + const fileContent = await fs.readFile(path.join(tmpDir, '.memory', 'knowledge', 'pitfalls.md'), 'utf-8'); + + // Check if an entry with matching Area and Issue already exists + const newArea = 'shared/agents/synthesizer.md'; + const newIssue = 'Glob didn\'t match reviewer output filenames'; + const isDuplicate = fileContent.includes(`**Area**: ${newArea}`) && fileContent.includes(`**Issue**: ${newIssue}`); + + expect(isDuplicate).toBe(true); + }); + + it('gracefully handles missing knowledge files', async () => { + // Verify no error when reading non-existent knowledge files + const knowledgeDir = path.join(tmpDir, '.memory', 'knowledge'); + const decisionsPath = path.join(knowledgeDir, 'decisions.md'); + const pitfallsPath = path.join(knowledgeDir, 'pitfalls.md'); + + // Simulate the graceful degradation pattern from session-start hook + let tldrLines: string[] = []; + for (const kf of [decisionsPath, pitfallsPath]) { + try { + await fs.access(kf); + const firstLine = (await fs.readFile(kf, 'utf-8')).split('\n')[0]; + if (firstLine.startsWith('', '')); + } + } catch { + // File doesn't exist — skip silently + } + } + + expect(tldrLines).toHaveLength(0); + }); + + it('updates TL;DR to reflect new entry count after append', async () => { + const content = [ + '', + '# Known Pitfalls', + '', + '## PF-001: Synthesizer review glob matched zero files', + '- **Area**: shared/agents/synthesizer.md', + '- **Issue**: Glob pattern mismatch', + ].join('\n'); + await fs.writeFile(path.join(tmpDir, '.memory', 'knowledge', 'pitfalls.md'), content); + + // Simulate appending a new entry and updating TL;DR + let fileContent = await fs.readFile(path.join(tmpDir, '.memory', 'knowledge', 'pitfalls.md'), 'utf-8'); + const newEntry = '\n\n## PF-002: Race condition in background hook\n- **Area**: scripts/hooks/stop-update-memory\n- **Issue**: Concurrent writes to memory file'; + fileContent += newEntry; + + // Update TL;DR + const matches = [...fileContent.matchAll(/^## PF-(\d+)/gm)]; + const count = matches.length; + const keys = matches.map(m => `PF-${m[1].padStart(3, '0')}`).join(', '); + fileContent = fileContent.replace(/^/, ``); + + await fs.writeFile(path.join(tmpDir, '.memory', 'knowledge', 'pitfalls.md'), fileContent); + + const updated = await fs.readFile(path.join(tmpDir, '.memory', 'knowledge', 'pitfalls.md'), 'utf-8'); + const updatedTldr = updated.split('\n')[0]; + + expect(updatedTldr).toBe(''); + expect(updated).toContain('## PF-002'); + }); +}); + +describe('session-start-memory hook integration', () => { + let tmpDir: string; + const hookPath = path.resolve(__dirname, '..', 'scripts', 'hooks', 'session-start-memory'); + + function runHook(cwd: string): Promise { + return new Promise((resolve, reject) => { + const child = exec(`bash "${hookPath}"`, { timeout: 5000 }, (err, stdout, stderr) => { + if (err) return reject(new Error(`Hook failed: ${err.message}\nstderr: ${stderr}`)); + resolve(stdout); + }); + child.stdin?.write(JSON.stringify({ cwd })); + child.stdin?.end(); + }); + } + + beforeEach(async () => { + tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'devflow-hook-test-')); + await fs.mkdir(path.join(tmpDir, '.memory', 'knowledge'), { recursive: true }); + }); + + afterEach(async () => { + await fs.rm(tmpDir, { recursive: true, force: true }); + }); + + it('injects PROJECT KNOWLEDGE TL;DR from knowledge files', async () => { + await fs.writeFile( + path.join(tmpDir, '.memory', 'knowledge', 'decisions.md'), + '\n# Architectural Decisions', + ); + await fs.writeFile( + path.join(tmpDir, '.memory', 'knowledge', 'pitfalls.md'), + '\n# Known Pitfalls', + ); + + const output = await runHook(tmpDir); + const json = JSON.parse(output); + const ctx = json.hookSpecificOutput.additionalContext; + + expect(ctx).toContain('PROJECT KNOWLEDGE (TL;DR)'); + expect(ctx).toContain('2 decisions. Key: ADR-001 Result types, ADR-002 Single-coder'); + expect(ctx).toContain('1 pitfall. Key: PF-001 Synthesizer glob'); + }); + + it('produces no leading newlines when only knowledge files exist (no working memory)', async () => { + await fs.writeFile( + path.join(tmpDir, '.memory', 'knowledge', 'decisions.md'), + '\n# Architectural Decisions', + ); + + const output = await runHook(tmpDir); + const json = JSON.parse(output); + const ctx = json.hookSpecificOutput.additionalContext; + + expect(ctx).not.toMatch(/^\n/); + expect(ctx).toMatch(/^---/); + }); + + it('does not include PROJECT KNOWLEDGE section when no knowledge files exist', async () => { + // Empty tmpDir with just the directories — no knowledge files + const output = await runHook(tmpDir); + // May still have ambient output depending on user settings, but should not have knowledge + if (output.trim()) { + const json = JSON.parse(output); + const ctx = json.hookSpecificOutput.additionalContext; + expect(ctx).not.toContain('PROJECT KNOWLEDGE'); + } + // If no output at all, that's also correct + }); +});