devflow-kit 1.4.0 → 1.6.0

package/plugins/devflow-implement/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-implement/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-java/.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-python/.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-react/.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-resolve/.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",
@@ -21,8 +21,9 @@
     "simplifier"
   ],
   "skills": [
+    "agent-teams",
     "implementation-patterns",
-    "security-patterns",
-    "agent-teams"
+    "knowledge-persistence",
+    "security-patterns"
   ]
 }

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

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

package/plugins/devflow-resolve/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-resolve/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-rust/.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-self-review/.claude-plugin/plugin.json

@@ -4,7 +4,16 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.4.0",
+  "version": "1.6.0",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": [
+    "self-review",
+    "simplifier",
+    "scrutinizer",
+    "quality"
+  ],
   "agents": [
     "simplifier",
     "scrutinizer",

package/plugins/devflow-self-review/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-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)