Persistent Project Knowledge (Stateful Agents / Persistent Minds)

[dean0x]

Summary

Add persistent project knowledge files that accumulate across workflows — an append-only architectural decision log and structured pattern/pitfall registry that carry context between /code-review, /implement, and /specify invocations.

Motivation (from Forge Analysis)

Forge implements three "Persistent Minds" — agents whose knowledge survives across pipeline phases through owned files:

1. Architect Agent (Opus)

Owned files:

• .forge/docs/architecture.md — main architecture document with status markers
• .forge/docs/decisions.md — ADR-style, append-only decision log (never delete entries)
• .forge/docs/tech-stack.md, arch-constraints.md, codebase-state.md

Three modes: Architecture (bootstrap, write docs), Build (respond to state queries), Validate (read-only scan + findings)

Consultation pattern: Any agent can SendMessage with technical question → Architect replies → if new architectural decision needed, appends ADR to decisions.md

2. Sentinel Agent (Opus)

Owned files:

• .forge/docs/patterns.md — coding patterns with concrete code examples
• .forge/docs/pitfalls.md — known gotchas, anti-patterns, fragile areas

Pattern format:

### P-NNN: [Pattern Name]
- Category: naming | structure | testing | error-handling | async | data-flow
- Rule: One-line rule
- Example: Concrete code
- Counter-example: What NOT to do

Pitfall format:

### PF-NNN: [Pitfall Name]
- Area: file/module path
- Issue: What goes wrong
- Impact: What breaks
- Resolution: Fix steps
- Prevention: Avoidance

Iteration updates: After each build iteration, Sentinel scans new/modified files, cross-checks acceptance criteria have tests, extracts new patterns and pitfalls: "DOCS_UPDATED: {N} new patterns, {M} new pitfalls"

3. Knowledge Flow Across Pipeline Phases

Step 1 → Step 2: codebase-snapshot.md, decisions.md, pitfalls.md → brainstorm
Step 2 → Step 3: VISION.md, vision-notes.md → research
Step 3 → Step 4: research.md → architecture planning
Step 4 → Step 5: master-plan.md, architecture.md, patterns.md, pitfalls.md → build
Step 5 → Step 6: validation findings → next iteration scope

The key insight: project knowledge is distinct from session state. DevFlow's .memory/WORKING-MEMORY.md tracks what happened in a session. Project knowledge tracks what the project IS — its architecture, decisions, patterns, and pitfalls.

Current State in DevFlow

• .memory/WORKING-MEMORY.md — volatile, overwritten each session (session state)
• .memory/PROJECT-PATTERNS.md — accumulated patterns merged across sessions (partial overlap with Sentinel's patterns.md)
• .docs/reviews/ — review reports per branch (output artifacts, not persistent knowledge)
• .docs/design/ — implementation plans (output artifacts)
• No decisions log — architectural decisions are lost between sessions
• No cross-workflow knowledge flow — /code-review findings don't feed into /implement; /implement decisions don't persist for future reviews

Technical Approach

1. Project Knowledge Files

Add to .docs/knowledge/ (persistent, committed to repo unlike .memory/):

.docs/knowledge/
├── decisions.md          # ADR-style, append-only
├── patterns.md           # P-NNN format, concrete examples
└── pitfalls.md           # PF-NNN format, area-specific

2. Architectural Decision Records (decisions.md)

# Architectural Decision Records

## ADR-001: Use Result types instead of thrown errors
- **Date**: 2026-03-01
- **Status**: Accepted
- **Context**: Error handling inconsistency across codebase
- **Decision**: All business logic returns Result<T, E>, never throws
- **Consequences**: Uniform error handling, explicit error paths, no try/catch in business logic
- **Recorded by**: /implement (session abc123)

## ADR-002: ...

Rules: Append-only (never delete entries). Status can change (Accepted → Superseded by ADR-NNN). Each entry records which workflow/session created it.

3. Cross-Workflow Knowledge Flow

Source Workflow	Knowledge Produced	Consumer Workflow
/code-review	Patterns found, pitfalls identified, architectural observations	/implement, /resolve
/implement	ADRs for architectural decisions, new patterns from implementation	/code-review, future /implement
/specify	Constraints, non-goals, architectural requirements	/implement
/debug	Pitfalls (root causes, fragile areas)	/code-review, /implement

4. Agent Integration

• Synthesizer agent: After combining reviewer outputs, extract patterns/pitfalls and append to knowledge files
• Coder agent: Read decisions.md + patterns.md before implementation; append new ADRs when making architectural decisions
• Reviewer agents: Read pitfalls.md to check for known issues; flag new pitfalls found

5. Relationship to Existing .memory/PROJECT-PATTERNS.md

.memory/PROJECT-PATTERNS.md is auto-generated by the Stop hook with AI-merged patterns. The new .docs/knowledge/patterns.md would be the curated, P-NNN formatted version with code examples. Options:

• A: Merge — Stop hook feeds into knowledge/patterns.md
• B: Coexist — PROJECT-PATTERNS.md stays as raw auto-extracted; knowledge/patterns.md is curated
• C: Replace — knowledge/patterns.md replaces PROJECT-PATTERNS.md entirely

Acceptance Criteria

• .docs/knowledge/ directory structure created
• decisions.md with ADR format and append-only semantics
• patterns.md with P-NNN format including code examples
• pitfalls.md with PF-NNN format including area/impact/resolution
• /code-review Synthesizer extracts and appends patterns/pitfalls
• /implement Coder reads knowledge files before implementation
• /implement Coder appends ADRs for architectural decisions
• Cross-workflow flow verified (review → implement knowledge transfer)
• Relationship to .memory/PROJECT-PATTERNS.md resolved

References

• Forge (codename): Architect agent (.forge/docs/architecture.md, decisions.md), Sentinel agent (.forge/docs/patterns.md, pitfalls.md)
• DevFlow memory system: scripts/hooks/, .memory/ directory
• DevFlow review artifacts: .docs/reviews/
• ADR format: https://adr.github.io/
• Priority: High impact, Low-Medium effort — "Do second"

[dean0x]

Implemented. Persistent project knowledge ships as:

• .memory/knowledge/decisions.md — ADR-NNN format, append-only
• .memory/knowledge/pitfalls.md — PF-NNN format with area/impact/resolution
• knowledge-persistence skill — auto-activates during investigation, specification, and review
• Cross-workflow flow: review/debug findings persist as pitfalls, implementation decisions persist as ADRs

Location is .memory/knowledge/ rather than the originally proposed .docs/knowledge/, but the core feature (persistent project knowledge across workflows) is fully delivered.