devflow-kit 1.5.0 → 1.6.1

package/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

package/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,12 +43,12 @@ 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):
 
 ```
-Task(subagent_type="Explore", name="investigator-a"):
+Task(subagent_type="Explore"):
 "Investigate this bug: {bug_description}
 
 Hypothesis: {hypothesis A description}
@@ -63,7 +67,7 @@ Return a structured report:
 - Evidence AGAINST: [list with file:line refs]
 - Key finding: {one-sentence summary}"
 
-Task(subagent_type="Explore", name="investigator-b"):
+Task(subagent_type="Explore"):
 "Investigate this bug: {bug_description}
 
 Hypothesis: {hypothesis B description}
@@ -71,7 +75,7 @@ Focus area: {specific code area, mechanism, or condition}
 
 [same steps and return format]"
 
-Task(subagent_type="Explore", name="investigator-c"):
+Task(subagent_type="Explore"):
 "Investigate this bug: {bug_description}
 
 Hypothesis: {hypothesis C description}
@@ -82,12 +86,12 @@ 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:
 
 ```
-Task(subagent_type="general-purpose", name="synthesizer"):
+Task(subagent_type="Synthesizer"):
 "You are a root cause analyst. Synthesize these investigation reports:
 
 {paste all investigator reports}
@@ -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

package/plugins/devflow-debug/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-debug/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.

package/plugins/devflow-frontend-design/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.5.0",
+  "version": "1.6.1",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

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

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.5.0",
+  "version": "1.6.1",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

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

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.5.0",
+  "version": "1.6.1",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",
@@ -29,6 +29,7 @@
   "skills": [
     "agent-teams",
     "implementation-patterns",
+    "knowledge-persistence",
     "self-review"
   ]
 }

package/plugins/devflow-implement/agents/coder.md

@@ -2,7 +2,7 @@
 name: Coder
 description: Autonomous task implementation on feature branch. Implements, tests, and commits.
 model: inherit
-skills: core-patterns, git-safety, implementation-patterns, git-workflow, test-patterns, input-validation
+skills: core-patterns, git-safety, implementation-patterns, git-workflow, test-patterns, test-driven-development, search-first, input-validation
 ---
 
 # Coder Agent
@@ -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}
 ```

package/plugins/devflow-implement/agents/simplifier.md

@@ -1,6 +1,7 @@
 ---
 name: Simplifier
 description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.
+skills: core-patterns
 model: inherit
 ---
 
@@ -59,4 +60,34 @@ Your refinement process:
 5. Verify the refined code is simpler and more maintainable
 6. Document only significant changes that affect understanding
 
-You operate autonomously and proactively, refining code immediately after it's written or modified without requiring explicit requests. Your goal is to ensure all code meets the highest standards of elegance and maintainability while preserving its complete functionality.
+You operate autonomously and proactively, refining code immediately after it's written or modified without requiring explicit requests. Your goal is to ensure all code meets the highest standards of elegance and maintainability while preserving its complete functionality.
+
+## Output
+
+Return structured completion status:
+
+```markdown
+## Simplification Report
+
+### Changes Applied
+- {file}: {description of simplification}
+
+### Changes Skipped
+- {reason not simplified — would change behavior / already clean}
+
+### Files Modified
+- {file} ({change description})
+```
+
+## Boundaries
+
+**Escalate to orchestrator:**
+- Changes that would alter observable behavior or break tests
+- Simplifications requiring new dependencies or architectural changes
+- Files outside the recently modified scope (unless instructed)
+
+**Handle autonomously:**
+- Naming improvements, dead code removal, nesting reduction
+- Import sorting and organization
+- Redundant abstraction elimination
+- Comment cleanup (remove obvious, keep non-obvious)

package/plugins/devflow-implement/agents/skimmer.md

@@ -1,6 +1,7 @@
 ---
 name: Skimmer
 description: Codebase orientation using skim to identify relevant files, functions, and patterns for a feature or task
+skills: knowledge-persistence
 model: inherit
 ---
 
@@ -20,6 +21,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 `<!-- TL;DR: ... -->` 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 +66,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}
 ```