devflow-kit 1.4.0 → 1.6.0

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.4.0",
+  "version": "1.6.0",
   "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.4.0",
+  "version": "1.6.0",
   "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.4.0",
+  "version": "1.6.0",
   "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
@@ -29,11 +29,16 @@ You receive from orchestrator:
 
 ## Responsibilities
 
-1. **Orient on branch state**: Check git log for commits from previous Coders (if sequential). Read files created by prior phases - **do not trust summaries alone**. Identify patterns from actual code: naming conventions, error handling approach, testing style.
+1. **Orient on branch state** (always, before any implementation):
+   - Run `git log --oneline --stat -n 10` to scan recent commit history on this branch
+   - Run `git status` and `git diff --stat` and `git diff --cached --stat` to see uncommitted/unstaged work
+   - 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. **Reference handoff** (if PRIOR_PHASE_SUMMARY provided): Use summary to validate your understanding of prior work, not as the sole source of truth. The actual code is authoritative.
-
-3. **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:
+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`
    - `backend` (Go): Read `~/.claude/skills/go/SKILL.md`
    - `backend` (Java): Read `~/.claude/skills/java/SKILL.md`
@@ -44,22 +49,22 @@ You receive from orchestrator:
    - `fullstack`: Combine backend + frontend skills
    - If a Read fails (skill not installed), skip it silently and continue.
 
-4. **Implement the plan**: Work through execution steps systematically, creating and modifying files. Follow existing patterns. Type everything. Use Result types if codebase uses them.
+3. **Implement the plan**: Work through execution steps systematically, creating and modifying files. Follow existing patterns. Type everything. Use Result types if codebase uses them.
 
-5. **Write tests**: Add tests for new functionality. Cover happy path, error cases, and edge cases. Follow existing test patterns.
+4. **Write tests**: Add tests for new functionality. Cover happy path, error cases, and edge cases. Follow existing test patterns.
 
-6. **Run tests**: Execute the test suite. Fix any failures. All tests must pass before proceeding.
+5. **Run tests**: Execute the test suite. Fix any failures. All tests must pass before proceeding.
 
-7. **Commit and push**: Create atomic commits with clear messages. Reference TASK_ID. Push to remote.
+6. **Commit and push**: Create atomic commits with clear messages. Reference TASK_ID. Push to remote.
 
-8. **Create PR** (if CREATE_PR=true): Create pull request against BASE_BRANCH with summary and testing notes.
+7. **Create PR** (if CREATE_PR=true): Create pull request against BASE_BRANCH with summary and testing notes.
 
-9. **Generate handoff** (if HANDOFF_REQUIRED=true): Include implementation summary for next Coder (see Output section).
+8. **Generate handoff** (if HANDOFF_REQUIRED=true): Include implementation summary for next Coder (see Output section).
 
 ## Principles
 
 1. **Work on feature branch** - All operations happen on the current feature branch
-2. **Branch orientation first** - In sequential execution, read actual files before trusting handoff summaries
+2. **Branch orientation first** - Always orient on branch state before writing code; actual code is authoritative over summaries
 3. **Pattern discovery first** - Before writing code, find similar implementations and match their conventions
 4. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
 5. **Follow existing patterns** - Match codebase style, don't invent new conventions
@@ -86,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}
 ```
@@ -124,4 +132,4 @@ Return structured completion status:
 - Switch branches during implementation
 - Push to branches other than your feature branch
 - Merge PRs (orchestrator handles this)
-- Trust handoff summaries without reading actual code (in sequential execution)
+- Trust handoff summaries without reading actual code

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}
 ```

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

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