ai-development-framework 0.1.1 → 0.1.2

package/.claude/commands/create-prd.md

@@ -31,6 +31,25 @@ Invoke the brainstorming skill to explore the idea before writing anything:
 4. User stories should be concrete and testable
 5. Implementation phases should be ordered by dependency and value
 
+### Phase 2.5: Seed Knowledge Base (if configured)
+
+Check CLAUDE.md for a `## Knowledge Base` section with a `Path:` value. If configured:
+
+1. Read `.claude/references/knowledge-base-templates.md` for templates
+2. Create `<kb-path>/overview.md` from the PRD:
+   - Vision from Executive Summary
+   - Goals from Goals & Success Criteria
+   - Target Users from Target Users section
+   - Tech Stack from Technical Architecture
+   - Feature Areas listing each epic/feature
+3. Create `<kb-path>/architecture/system-design.md` from the PRD's Technical Architecture and System Diagram sections
+4. For each epic or major feature in the PRD, create `<kb-path>/features/<feature-name>.md` using the feature note template:
+   - Summary from the epic description
+   - GitHub Issues section left empty (populated by `/plan-project`)
+   - Key Decisions from any decisions made during brainstorming
+
+If no knowledge base configured, skip this phase.
+
 ### Phase 3: Review and Save
 
 1. Present the PRD to the user section by section
@@ -48,8 +67,10 @@ After saving, tell the user:
 > - Run `/plan-project` to decompose this into GitHub milestones and issues
 > - Or run `/plan-feature` to start planning a specific feature from the PRD
 
-Commit the PRD:
+Commit the PRD and knowledge base files (if created):
 ```bash
 git add docs/plans/PRD.md
-git commit -m "docs: add product requirements document"
+# If knowledge base was seeded:
+git add <kb-path>/overview.md <kb-path>/architecture/ <kb-path>/features/
+git commit -m "docs: add PRD and seed project knowledge base"
 ```

package/.claude/commands/execute.md

@@ -27,6 +27,20 @@ Executes an implementation plan task by task with TDD discipline.
 
 Read every file listed in the plan's "Mandatory Reading" section. This ensures you have the codebase context needed for implementation.
 
+#### Knowledge Base Context (if configured)
+
+Check CLAUDE.md for a `## Knowledge Base` section with a `Path:` value. If configured:
+
+1. Detect the issue number from the plan file or current branch
+2. Grep `<kb-path>/features/*.md` for the issue number — read the matching feature note
+3. Scan other feature notes (first 5 lines each) for related features — read any with clear overlap
+4. Check `<kb-path>/decisions/` for decisions referencing the same feature area
+5. Read `<kb-path>/overview.md` for project context
+
+This supplements the plan's mandatory reading with project-level context the plan author may not have included.
+
+If no knowledge base configured, skip this step.
+
 ### Step 3: Execute Tasks
 
 For each task in the plan:

package/.claude/commands/plan-project.md

@@ -74,6 +74,24 @@ gh issue create --title "[type]: description" --body "..." --label "feat,priorit
 
 For issues with dependencies, add a "Blocked by #N" line in the issue body.
 
+#### Knowledge Base Integration (if configured)
+
+Check CLAUDE.md for a `## Knowledge Base` section with a `Path:` value. If configured, after creating each GitHub issue:
+
+1. Check if a feature note already exists in `<kb-path>/features/` for this feature area
+2. If yes: update the `## GitHub Issues` section with the new issue number and title
+3. If no: create a new feature note using `.claude/references/knowledge-base-templates.md` template, with:
+   - Summary from the issue description
+   - GitHub Issues section listing the new issue
+4. If architectural decisions were made during the planning process, create `<kb-path>/decisions/NNN-title.md` for each significant decision
+
+Stage knowledge base files for commit:
+```bash
+git add <kb-path>/features/ <kb-path>/decisions/
+```
+
+If no knowledge base configured, skip this step.
+
 ### Phase 6: Generate Roadmap
 
 Save a roadmap file to `docs/plans/roadmap.md`:

package/.claude/commands/prime.md

@@ -42,6 +42,17 @@ git branch --show-current
 - Read `.claude/agents/tester-agent/test-patterns.md` (page inventory)
 - Check `package.json` or equivalent for available scripts/commands
 
+### 6. Knowledge Base Context
+
+Check CLAUDE.md for a `## Knowledge Base` section with a `Path:` value (e.g., `.obsidian/`). If configured and the directory exists:
+
+1. **Always read:** `<kb-path>/overview.md`
+2. **Find linked feature note:** If working on a specific issue (detected from branch name or user input), grep `<kb-path>/features/*.md` for the issue number. Read the matching feature note.
+3. **Scan for related features:** List all files in `<kb-path>/features/`. Read the first 5 lines (`## Summary`) of each. If any feature has a clear dependency or overlap with the current issue (shared entities, referenced in acceptance criteria, same domain area), read the full note.
+4. **Check decisions:** List `<kb-path>/decisions/`. Read any whose title references the same feature area.
+
+If no knowledge base configured, skip this section entirely.
+
 ## Output Format
 
 Present a structured summary:
@@ -67,5 +78,8 @@ Available Commands:
 
 Knowledge Base: [N domains documented in architect-agent]
 
+Project Knowledge: [summary from overview.md if knowledge base exists, or "not configured"]
+Related Features: [list of feature notes loaded for this session]
+
 === Ready. Run /start to begin or specify a command. ===
 ```

package/.claude/commands/ship.md

@@ -10,6 +10,51 @@ Handles the full shipping workflow: staging, committing, pushing, and creating a
 2. Verify no uncommitted changes that shouldn't be included
 3. Check current branch is not main/master
 
+### Step 1.5: Update Knowledge Base (if configured)
+
+Check CLAUDE.md for a `## Knowledge Base` section with a `Path:` value. If configured:
+
+1. **Find the feature note:** Detect the current issue number from the branch name. Grep `<kb-path>/features/*.md` for that issue number. If no match, use keyword matching between branch name and feature note filenames.
+
+2. **Update the feature note:**
+   - `## Implementation Notes` — append what was built: key files created/modified, endpoints added, components built, patterns used
+   - `## GitHub Issues` — update the status of the current issue to reflect completion
+   - `## Key Decisions` — add any decisions made during implementation that weren't pre-planned
+
+3. **Create decision records** (only if warranted):
+   - A technology or approach was chosen over alternatives during implementation
+   - A pattern was established that future features should follow
+   - Something was intentionally excluded and the reason matters for future work
+
+4. **Update overview** (only if significant):
+   - New integration or service was added to the stack
+   - Project scope changed
+
+5. Stage knowledge base changes alongside code changes.
+
+If no knowledge base configured, skip to Step 2.
+
+### Step 1.6: Codex Adversarial Review (optional)
+
+This step requires an OpenAI subscription and the Codex plugin installed. If not available, skip to Step 2.
+
+Check if the Codex companion script exists:
+```bash
+test -f "$HOME/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs" && echo "codex available" || echo "codex not available"
+```
+
+If Codex is available:
+
+1. Ask the user: "Run Codex adversarial review before committing? (requires OpenAI subscription)"
+   - If yes: run `/codex:adversarial-review` against the working tree changes
+   - If no: skip to Step 2
+2. Present the review output to the user
+3. If the review surfaces significant concerns, ask: "Address these findings before committing, or proceed?"
+   - If address: stop `/ship`, let the user fix issues, then re-run `/ship`
+   - If proceed: continue to Step 2
+
+This does NOT replace the superpowers code review in `/validate`. It is an additional, adversarial perspective that questions design choices, tradeoffs, and assumptions — not just implementation defects.
+
 ### Step 2: Stage and Commit
 
 Use the `/commit` skill (from commit-commands plugin) for proper conventional commit formatting.

package/.claude/commands/start.md

@@ -10,6 +10,7 @@ Run these in parallel:
 3. Check current git branch and status
 4. Check for existing GitHub issues: `gh issue list --limit 5 2>/dev/null`
 5. Check for existing plan files: `find docs/plans docs/superpowers/plans -name "*.md" 2>/dev/null`
+6. Check if knowledge base is configured: look for `## Knowledge Base` section with `Path:` in CLAUDE.md. If found, check if the directory exists and has `overview.md`
 
 ## Step 2: Detect Scope Level
 
@@ -21,7 +22,15 @@ Based on context, determine the entry point:
 
 **L0 (New Project)** — No PRD, no issues, minimal/no code
 → "Looks like a fresh project. Let's plan it from scratch."
-→ Route to: `/create-prd` then `/plan-project`
+→ Route to:
+  1. Brainstorm functionalities (interactive discussion)
+  2. If knowledge base configured in CLAUDE.md:
+     a. Create knowledge base folder structure (`overview.md`, `features/`, `decisions/`, `config/`, `research/`, `architecture/`)
+     b. Create `overview.md` from brainstorming results using `.claude/references/knowledge-base-templates.md`
+     c. Create feature notes in `features/` for each agreed functionality
+  3. `/create-prd` (generates PRD from brainstorming, seeds knowledge base if configured)
+  4. `/plan-project` (creates GitHub issues, links them to feature notes)
+  5. STOP — present the issue list and ask: "Which issue do you want to work on first?"
 
 **L1 (New Feature)** — Project exists, user has a feature idea (no specific issue)
 → "Let's plan this feature."

package/.claude/references/knowledge-base-templates.md

@@ -0,0 +1,124 @@
+# Knowledge Base Templates
+
+Used by pipeline commands when creating knowledge base notes. The knowledge base path is configured in the project's CLAUDE.md under `## Knowledge Base`.
+
+**Security:** Knowledge base notes are committed to git. NEVER store actual secret values (API keys, tokens, passwords) in any note. Store only metadata: which env vars are needed, which services are used, who owns credentials. Actual secrets belong in `.env` files, secret managers, or CI/CD variables.
+
+---
+
+## Feature Note Template
+
+Create one per feature area in `<kb-path>/features/<feature-name>.md`.
+
+```markdown
+# Feature: [Name]
+
+## Summary
+
+[1-2 sentences: what this feature does and why]
+
+## GitHub Issues
+
+- #N — [title] (status: open/closed)
+
+## Key Decisions
+
+- [Decision and why]
+
+## Implementation Notes
+
+[Updated by /ship after work is completed — endpoints created, components built, patterns used]
+```
+
+---
+
+## Decision Record Template
+
+Create in `<kb-path>/decisions/NNN-title.md` when:
+- A technology or approach was chosen over alternatives
+- A pattern was established that future work should follow
+- Something was intentionally excluded (and why)
+
+NOT for every small implementation choice.
+
+```markdown
+# NNN: [Title]
+
+**Date:** YYYY-MM-DD
+**Status:** Accepted
+
+## Context
+
+[What situation led to this decision]
+
+## Decision
+
+[What we chose and why]
+
+## Consequences
+
+[What this means for future work — both positive and negative]
+```
+
+---
+
+## Overview Template
+
+Create once at `<kb-path>/overview.md` during project setup or PRD creation.
+
+```markdown
+# [Project Name]
+
+## Vision
+
+[1-2 sentences: what this project is and why it exists]
+
+## Goals
+
+- [Goal 1]
+- [Goal 2]
+
+## Target Users
+
+- [User type 1]: [their key need]
+- [User type 2]: [their key need]
+
+## Tech Stack
+
+| Layer | Technology | Rationale |
+|-------|-----------|-----------|
+| | | |
+
+## Feature Areas
+
+- [Feature 1] — see `features/feature-1.md`
+- [Feature 2] — see `features/feature-2.md`
+```
+
+---
+
+## Architecture Template
+
+Create at `<kb-path>/architecture/system-design.md` from PRD's technical architecture section.
+
+```markdown
+# System Design
+
+## Overview
+
+[High-level description of the system architecture]
+
+## Components
+
+| Component | Responsibility | Tech |
+|-----------|---------------|------|
+| | | |
+
+## Data Flow
+
+[How data moves through the system]
+
+## Integrations
+
+[External services and how they connect]
+```

package/CLAUDE.md

@@ -54,6 +54,44 @@ For non-trivial tasks, choose your discipline level:
 - **mobile-tester-agent** — Mobile app testing via mobile-mcp (VERIFY/FLOW)
 - **ui-ux-analyzer** — Design audit agent with screenshots and reports
 
+## Knowledge Base
+
+Optional Obsidian-compatible project knowledge base. Stores feature specs, architecture decisions, and project overview as markdown notes that the agent reads/writes during the pipeline.
+
+**Configuration:** Add `## Knowledge Base` with `Path: <path>` to your project's CLAUDE.md. Default: `.obsidian/`. Remove the section to disable.
+
+**Structure:**
+```
+<path>/
+├── overview.md          # Project vision, goals, tech stack
+├── architecture/        # System design, data model
+├── features/            # One note per feature area, linked to GitHub issues
+├── decisions/           # Architecture Decision Records (ADRs)
+├── config/              # Integration metadata, env var names (never actual secrets)
+└── research/            # Brainstorming notes, tech comparisons
+```
+
+**When commands read it:**
+- `/prime` — loads overview + related feature notes (smart/targeted)
+- `/execute` — reads feature context before implementing
+
+**When commands write it:**
+- `/start` (L0) — creates structure + feature notes during brainstorming
+- `/create-prd` — seeds overview + architecture from PRD
+- `/plan-project` — creates feature notes alongside GitHub issues
+- `/ship` — updates feature notes with implementation details
+
+## Code Review Layers
+
+The framework supports two complementary review layers:
+
+| Layer | Command | What it checks | Required |
+|-------|---------|---------------|----------|
+| **Superpowers Code Review** | `/validate` Phase 3 | Implementation defects, plan adherence, security, edge cases | Always available |
+| **Codex Adversarial Review** | `/ship` Step 1.6 | Design choices, tradeoffs, assumptions, alternative approaches | Optional (requires OpenAI subscription + Codex plugin) |
+
+These are additive — the adversarial review questions whether the *approach* is right, while the code review checks whether the *implementation* is correct.
+
 ## Rules & References
 
 - Domain-specific rules auto-load from `.claude/rules/` based on file paths being edited

package/cli/init.js

@@ -434,7 +434,7 @@ async function main() {
   console.log('  .claude/agents/      4 specialist agents + template');
   console.log('  .claude/skills/      2 framework skills');
   console.log('  .claude/rules/       6 domain rules + template');
-  console.log('  .claude/references/  5 templates');
+  console.log('  .claude/references/  6 templates');
   console.log('  .claude/hooks/       5 guardrails');
   console.log('  docs/                methodology + guides');
   console.log('');

package/docs/customization.md

@@ -26,6 +26,62 @@ Hooks are shell scripts in `.claude/hooks/`. Edit existing hooks or add new ones
 
 Each project gets its own `.claude/` folder. Customize CLAUDE.md, rules, and agent knowledge bases per project. The framework's commands stay the same.
 
+## Configuring the Knowledge Base
+
+The framework includes an optional project knowledge base (Obsidian-compatible) that gives the agent persistent project understanding across sessions.
+
+### Enable
+
+Add to your project's `CLAUDE.md`:
+
+```markdown
+## Knowledge Base
+
+Path: .obsidian/
+```
+
+### Custom Path
+
+Use any folder name:
+
+```markdown
+## Knowledge Base
+
+Path: knowledge/
+```
+
+**Note:** The framework's `.gitignore` only covers Obsidian config files under `.obsidian/`. If you use a custom path and open it as an Obsidian vault, add these entries to your `.gitignore` (replacing `knowledge/` with your path):
+
+```
+knowledge/app.json
+knowledge/appearance.json
+knowledge/core-plugins.json
+knowledge/core-plugins-migration.json
+knowledge/workspace.json
+knowledge/workspace-mobile.json
+knowledge/hotkeys.json
+knowledge/plugins/
+knowledge/themes/
+```
+
+### Disable
+
+Remove the `## Knowledge Base` section from CLAUDE.md. All knowledge operations are skipped — commands work exactly as before.
+
+### What It Does
+
+Pipeline commands automatically read from and write to the knowledge base:
+- `/start` creates the structure when starting a new project
+- `/prime` loads relevant notes for context before work
+- `/create-prd` seeds the knowledge base from the PRD
+- `/plan-project` creates feature notes alongside GitHub issues
+- `/execute` reads related feature notes before implementing
+- `/ship` updates feature notes after completing work
+
+### Obsidian
+
+If you have [Obsidian](https://obsidian.md/) installed, open your project folder as a vault. The `.obsidian/` directory makes it a valid vault. Notes are navigable, linkable, and searchable through Obsidian's UI. Obsidian is not required — the notes are plain markdown.
+
 ## Contributing
 
 1. Fork the repository

package/docs/plans/2026-04-04-knowledge-base-integration-design.md

@@ -0,0 +1,209 @@
+# Knowledge Base Integration Design
+
+**Date:** 2026-04-04
+**Status:** Approved
+
+## Problem
+
+The agent starts each session with no project-level context beyond what it can read from code and git history. It doesn't know what features are planned, why decisions were made, or how features relate to each other. This leads to:
+
+- Agent trying to implement entire projects in one shot instead of following the issue-based pipeline
+- No persistent project understanding across sessions
+- Brainstorming insights lost after the session ends
+- No automatic check for related features/decisions before starting work
+
+## Solution
+
+Add an optional, Obsidian-compatible knowledge base (`.obsidian/` by default) that pipeline commands read from and write to at natural checkpoints. The knowledge base complements the existing architect-agent (code-level knowledge) with project-level understanding.
+
+## Design
+
+### Knowledge Base Structure
+
+Default path: `.obsidian/` (configurable via `Knowledge Base: <path>` in project CLAUDE.md).
+
+```
+.obsidian/
+├── app.json                     # Obsidian config (gitignored)
+├── appearance.json              # Obsidian config (gitignored)
+├── core-plugins.json            # Obsidian config (gitignored)
+├── workspace.json               # Obsidian config (gitignored)
+├── overview.md                  # Project vision, goals, tech stack, target users
+├── architecture/
+│   └── system-design.md         # High-level architecture, component diagram
+├── features/
+│   ├── feature-name.md          # One per feature area, links to GitHub issues
+│   └── ...
+├── decisions/
+│   └── NNN-title.md             # ADR format: context, decision, consequences
+├── config/
+│   └── integrations.md          # Third-party services, env var names (never store actual secrets)
+└── research/
+    └── ...                      # Brainstorming notes, tech comparisons
+```
+
+### Gitignore Rules
+
+Obsidian config files are gitignored (machine-specific). Notes are committed.
+
+```
+.obsidian/app.json
+.obsidian/appearance.json
+.obsidian/core-plugins.json
+.obsidian/core-plugins-migration.json
+.obsidian/workspace.json
+.obsidian/hotkeys.json
+.obsidian/plugins/
+.obsidian/themes/
+```
+
+### Feature Note Template
+
+```markdown
+# Feature: [Name]
+
+## Summary
+[1-2 sentences: what this feature does and why]
+
+## GitHub Issues
+- #N — [title] (status)
+- #N — [title] (status)
+
+## Key Decisions
+- [Decision and why]
+
+## Implementation Notes
+[Updated after work is completed — endpoints created, components built, patterns used]
+```
+
+### Decision Record Template
+
+```markdown
+# NNN: [Title]
+
+**Date:** YYYY-MM-DD
+**Status:** Accepted
+
+## Context
+[What situation led to this decision]
+
+## Decision
+[What we chose and why]
+
+## Consequences
+[What this means for future work — both positive and negative]
+```
+
+## Command Integration
+
+### `/start` — New L0 Behavior
+
+Detects empty project → routes to new flow:
+1. Brainstorm functionalities (interactive)
+2. Create `.obsidian/` structure with `overview.md`
+3. Create feature notes in `.obsidian/features/`
+4. Create GitHub issues linked to feature notes
+5. STOP — ask user which issue to work on
+
+### `/prime` — Smart Knowledge Loading
+
+Add to existing context loading:
+1. Read `.obsidian/overview.md` (always)
+2. If working on a specific issue → read the linked feature note
+3. Scan other feature note filenames + summaries → pull in related ones
+4. Include knowledge context in session summary output
+
+### `/create-prd` — Knowledge Base Seeding
+
+Add after saving PRD:
+1. Create `.obsidian/overview.md` extracted from PRD (vision, goals, tech stack, users)
+2. Create `.obsidian/architecture/system-design.md` from PRD's architecture section
+
+### `/plan-project` — Feature Notes Alongside Issues
+
+Add after creating each GitHub issue:
+1. Create `.obsidian/features/<feature-name>.md` with the feature template
+2. Link the GitHub issue numbers in the note
+3. If architectural decisions were made during brainstorming, create `.obsidian/decisions/NNN-title.md`
+
+### `/ship` — Knowledge Update Checkpoint
+
+Add before committing:
+1. Read the feature note for the issue being completed
+2. Update `## Implementation Notes` with what was built
+3. Update `## GitHub Issues` status if issue is being closed
+4. If a significant decision was made, create a decision record
+5. Commit knowledge updates alongside code
+
+### `/execute` — Knowledge-Aware Context
+
+Add to mandatory file reading step:
+1. Check `.obsidian/` for the feature note linked to the current issue
+2. Read related feature notes (smart/targeted scan)
+3. Check `.obsidian/decisions/` for relevant past decisions
+
+## Read-Before-Work Flow (Smart/Targeted)
+
+When the agent starts work on an issue:
+
+1. **Always read:** `overview.md` + directly linked feature note
+2. **Scan for related:** list `.obsidian/features/`, read first 5 lines of each, pull in notes with clear dependency/overlap
+3. **Check decisions:** scan `.obsidian/decisions/` titles, read relevant ones
+4. **Check codebase:** existing `/prime` behavior (code structure, git history, architect-agent)
+
+### Issue-to-Feature Linking
+
+- Feature notes list issue numbers in `## GitHub Issues`
+- Agent greps `.obsidian/features/*.md` for the current issue number
+- Fallback: keyword matching between issue title and feature note filenames/summaries
+
+## Write-After-Work Flow (End of Issue)
+
+Triggered by `/ship`:
+
+### Updated:
+- **Feature note:** `## Implementation Notes`, `## GitHub Issues` status, `## Key Decisions`
+- **Decision records:** only when a technology/approach was chosen over alternatives, a pattern was established, or something was intentionally excluded
+
+### Updated only when significant:
+- **Overview:** only when new integration added or scope changed
+
+### Not updated:
+- Bug fixes (L3) unless they reveal a design decision
+- Unrelated feature notes
+- No full rewrites — only append/update relevant sections
+
+## Configuration & Optionality
+
+### CLAUDE.md Configuration
+
+```markdown
+## Knowledge Base
+
+Path: .obsidian/
+```
+
+When path is set → commands read/write from it.
+When absent → knowledge operations skipped entirely. Zero impact.
+
+### `/init-claude-md` Integration
+
+During setup, ask:
+1. Yes, use `.obsidian/` (default)
+2. Yes, custom path
+3. No — skip knowledge base
+
+### Guard Behavior
+
+Every command that touches the knowledge base:
+1. Read project CLAUDE.md → look for `Knowledge Base` path
+2. If not found → skip all knowledge operations
+3. If found → check folder exists
+4. If folder doesn't exist → create it with initial structure
+
+## Relationship to Existing Systems
+
+- **architect-agent:** Keeps code-level knowledge (modules, endpoints, patterns). Knowledge base holds project-level understanding. Agent reads both.
+- **docs/plans/:** Untouched. Superpowers skills write here. Knowledge base is additive.
+- **docs/superpowers/plans/:** Untouched. Same reason.
+- **Obsidian:** Optional. The `.obsidian/` folder works as plain markdown without Obsidian installed. Obsidian users get a navigable vault for free.

package/docs/superpowers/plans/2026-04-04-knowledge-base-integration.md

@@ -0,0 +1,526 @@
+# Knowledge Base Integration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add an optional, Obsidian-compatible knowledge base that pipeline commands read from and write to at natural checkpoints, giving the agent persistent project understanding across sessions.
+
+**Architecture:** Configurable path (default `.obsidian/`) with feature notes, decision records, and project overview. Existing commands (`/start`, `/prime`, `/create-prd`, `/plan-project`, `/ship`, `/execute`) gain knowledge read/write operations guarded by a `Knowledge Base` config in CLAUDE.md. No new commands or skills.
+
+**Tech Stack:** Markdown files, Claude Code commands, `.gitignore` configuration
+
+---
+
+### Task 1: Gitignore — Add Obsidian Config Exclusions
+
+**Files:**
+- Modify: `.gitignore`
+
+- [ ] **Step 1: Add Obsidian config ignores to `.gitignore`**
+
+Append to the end of `.gitignore`:
+
+```
+# Obsidian config (machine-specific, notes are tracked)
+.obsidian/app.json
+.obsidian/appearance.json
+.obsidian/core-plugins.json
+.obsidian/core-plugins-migration.json
+.obsidian/workspace.json
+.obsidian/workspace-mobile.json
+.obsidian/hotkeys.json
+.obsidian/plugins/
+.obsidian/themes/
+```
+
+- [ ] **Step 2: Verify gitignore works**
+
+Run: `git status`
+Expected: Obsidian config files no longer show as untracked (if they were). Knowledge note files (`.obsidian/*.md`, `.obsidian/features/`, etc.) remain trackable.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .gitignore
+git commit -m "chore: add Obsidian config to gitignore"
+```
+
+---
+
+### Task 2: Reference Templates — Feature Note + Decision Record
+
+**Files:**
+- Create: `.claude/references/knowledge-base-templates.md`
+
+- [ ] **Step 1: Create the templates reference file**
+
+```markdown
+# Knowledge Base Templates
+
+Used by pipeline commands when creating knowledge base notes.
+
+---
+
+## Feature Note Template
+
+Create one per feature area in `<knowledge-base-path>/features/<feature-name>.md`.
+
+```markdown
+# Feature: [Name]
+
+## Summary
+
+[1-2 sentences: what this feature does and why]
+
+## GitHub Issues
+
+- #N — [title] (status: open/closed)
+
+## Key Decisions
+
+- [Decision and why]
+
+## Implementation Notes
+
+[Updated by /ship after work is completed — endpoints created, components built, patterns used]
+```
+
+## Decision Record Template
+
+Create in `<knowledge-base-path>/decisions/NNN-title.md` when:
+- A technology or approach was chosen over alternatives
+- A pattern was established that future work should follow
+- Something was intentionally excluded (and why)
+
+NOT for every small implementation choice.
+
+```markdown
+# NNN: [Title]
+
+**Date:** YYYY-MM-DD
+**Status:** Accepted
+
+## Context
+
+[What situation led to this decision]
+
+## Decision
+
+[What we chose and why]
+
+## Consequences
+
+[What this means for future work — both positive and negative]
+```
+
+## Overview Template
+
+Create once at `<knowledge-base-path>/overview.md` during project setup or PRD creation.
+
+```markdown
+# [Project Name]
+
+## Vision
+
+[1-2 sentences: what this project is and why it exists]
+
+## Goals
+
+- [Goal 1]
+- [Goal 2]
+
+## Target Users
+
+- [User type 1]: [their key need]
+- [User type 2]: [their key need]
+
+## Tech Stack
+
+| Layer | Technology | Rationale |
+|-------|-----------|-----------|
+| | | |
+
+## Feature Areas
+
+- [Feature 1] — see `features/feature-1.md`
+- [Feature 2] — see `features/feature-2.md`
+```
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .claude/references/knowledge-base-templates.md
+git commit -m "docs: add knowledge base note templates"
+```
+
+---
+
+### Task 3: Update `/start` — L0 Knowledge Base Flow
+
+**Files:**
+- Modify: `.claude/commands/start.md`
+
+- [ ] **Step 1: Add knowledge base detection to Step 1 (Gather Context)**
+
+Add item 6 to the existing parallel checks:
+
+```
+6. Check if knowledge base exists: look for `Knowledge Base` path in CLAUDE.md, then check if that directory has `overview.md`
+```
+
+- [ ] **Step 2: Update L0 route to include knowledge base creation**
+
+Replace the L0 section:
+
+```markdown
+**L0 (New Project)** — No PRD, no issues, minimal/no code
+→ "Looks like a fresh project. Let's plan it from scratch."
+→ Route to:
+  1. Brainstorm functionalities (interactive discussion)
+  2. If knowledge base configured in CLAUDE.md:
+     a. Create knowledge base folder structure (overview.md, features/, decisions/, config/, research/, architecture/)
+     b. Create `overview.md` from brainstorming results
+     c. Create feature notes in `features/` for each agreed functionality
+  3. Create GitHub issues linked to feature notes
+  4. STOP — present the issue list and ask: "Which issue do you want to work on first?"
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .claude/commands/start.md
+git commit -m "feat: add knowledge base creation to /start L0 flow"
+```
+
+---
+
+### Task 4: Update `/prime` — Smart Knowledge Loading
+
+**Files:**
+- Modify: `.claude/commands/prime.md`
+
+- [ ] **Step 1: Add knowledge base loading section**
+
+Add a new section `### 6. Knowledge Base Context` after the existing `### 5. Configuration` section:
+
+```markdown
+### 6. Knowledge Base Context
+
+Check CLAUDE.md for a `Knowledge Base` path (e.g., `.obsidian/`). If configured and the directory exists:
+
+1. **Always read:** `<kb-path>/overview.md`
+2. **Find linked feature note:** If working on a specific issue (detected from branch name or user input), grep `<kb-path>/features/*.md` for the issue number. Read the matching feature note.
+3. **Scan for related features:** List all files in `<kb-path>/features/`. Read the first 5 lines (## Summary) of each. If any feature has a clear dependency or overlap with the current issue (shared entities, referenced in acceptance criteria, same domain area), read the full note.
+4. **Check decisions:** List `<kb-path>/decisions/`. Read any whose title references the same feature area.
+
+If no knowledge base configured, skip this section entirely.
+```
+
+- [ ] **Step 2: Update output format**
+
+Add to the session summary output template after `Knowledge Base: [N domains documented in architect-agent]`:
+
+```markdown
+Project Knowledge: [summary from overview.md if knowledge base exists, or "not configured"]
+Related Features: [list of feature notes loaded for this session]
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .claude/commands/prime.md
+git commit -m "feat: add smart knowledge loading to /prime"
+```
+
+---
+
+### Task 5: Update `/create-prd` — Knowledge Base Seeding
+
+**Files:**
+- Modify: `.claude/commands/create-prd.md`
+
+- [ ] **Step 1: Add Phase 2.5 for knowledge base seeding**
+
+Add between Phase 2 (Generate PRD) and Phase 3 (Review and Save):
+
+```markdown
+### Phase 2.5: Seed Knowledge Base (if configured)
+
+Check CLAUDE.md for a `Knowledge Base` path. If configured:
+
+1. Read `.claude/references/knowledge-base-templates.md` for templates
+2. Create `<kb-path>/overview.md` from the PRD:
+   - Vision from Executive Summary
+   - Goals from Goals & Success Criteria
+   - Target Users from Target Users section
+   - Tech Stack from Technical Architecture
+   - Feature Areas listing each epic/feature
+3. Create `<kb-path>/architecture/system-design.md` from the PRD's Technical Architecture and System Diagram sections
+4. For each epic or major feature in the PRD, create `<kb-path>/features/<feature-name>.md` using the feature note template:
+   - Summary from the epic description
+   - GitHub Issues section left empty (populated by /plan-project)
+   - Key Decisions from any decisions made during brainstorming
+
+If no knowledge base configured, skip this phase.
+```
+
+- [ ] **Step 2: Update Phase 4 commit to include knowledge files**
+
+Update the commit step in Phase 4:
+
+```markdown
+Commit the PRD and knowledge base files (if created):
+```bash
+git add docs/plans/PRD.md
+# If knowledge base was seeded:
+git add <kb-path>/overview.md <kb-path>/architecture/ <kb-path>/features/
+git commit -m "docs: add PRD and seed project knowledge base"
+```
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .claude/commands/create-prd.md
+git commit -m "feat: add knowledge base seeding to /create-prd"
+```
+
+---
+
+### Task 6: Update `/plan-project` — Feature Notes Alongside Issues
+
+**Files:**
+- Modify: `.claude/commands/plan-project.md`
+
+- [ ] **Step 1: Add knowledge base integration to Phase 5**
+
+Add to Phase 5 (Create in GitHub), after each issue is created:
+
+```markdown
+#### Knowledge Base Integration (if configured)
+
+After creating each GitHub issue:
+
+1. Check if a feature note already exists in `<kb-path>/features/` for this feature area
+2. If yes: update the `## GitHub Issues` section with the new issue number and title
+3. If no: create a new feature note using `.claude/references/knowledge-base-templates.md` template, with:
+   - Summary from the issue description
+   - GitHub Issues section listing the new issue
+4. If architectural decisions were made during the planning process, create `<kb-path>/decisions/NNN-title.md` for each significant decision
+```
+
+- [ ] **Step 2: Update Phase 6 commit to include knowledge files**
+
+Add to the commit step in Phase 6:
+
+```markdown
+# If knowledge base configured:
+git add <kb-path>/features/ <kb-path>/decisions/
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .claude/commands/plan-project.md
+git commit -m "feat: add feature note creation to /plan-project"
+```
+
+---
+
+### Task 7: Update `/ship` — Knowledge Update Checkpoint
+
+**Files:**
+- Modify: `.claude/commands/ship.md`
+
+- [ ] **Step 1: Add Step 1.5 for knowledge base update**
+
+Add between Step 1 (Pre-flight Check) and Step 2 (Stage and Commit):
+
+```markdown
+### Step 1.5: Update Knowledge Base (if configured)
+
+Check CLAUDE.md for a `Knowledge Base` path. If configured:
+
+1. **Find the feature note:** Detect the current issue number from the branch name. Grep `<kb-path>/features/*.md` for that issue number. If no match, use keyword matching between branch name and feature note filenames.
+
+2. **Update the feature note:**
+   - `## Implementation Notes` — append what was built: key files created/modified, endpoints added, components built, patterns used
+   - `## GitHub Issues` — update the status of the current issue to reflect completion
+   - `## Key Decisions` — add any decisions made during implementation that weren't pre-planned
+
+3. **Create decision records** (only if warranted):
+   - A technology or approach was chosen over alternatives during implementation
+   - A pattern was established that future features should follow
+   - Something was intentionally excluded and the reason matters for future work
+
+4. **Update overview** (only if significant):
+   - New integration or service was added to the stack
+   - Project scope changed
+
+5. Stage knowledge base changes alongside code changes.
+
+If no knowledge base configured, skip to Step 2.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .claude/commands/ship.md
+git commit -m "feat: add knowledge update checkpoint to /ship"
+```
+
+---
+
+### Task 8: Update `/execute` — Knowledge-Aware Context
+
+**Files:**
+- Modify: `.claude/commands/execute.md`
+
+- [ ] **Step 1: Add knowledge base reading to Step 2**
+
+Add to Step 2 (Read Mandatory Files), after reading plan-specified files:
+
+```markdown
+#### Knowledge Base Context (if configured)
+
+Check CLAUDE.md for a `Knowledge Base` path. If configured:
+
+1. Detect the issue number from the plan file or current branch
+2. Grep `<kb-path>/features/*.md` for the issue number — read the matching feature note
+3. Scan other feature notes (first 5 lines each) for related features — read any with clear overlap
+4. Check `<kb-path>/decisions/` for decisions referencing the same feature area
+5. Read `<kb-path>/overview.md` for project context
+
+This supplements the plan's mandatory reading with project-level context the plan author may not have included.
+
+If no knowledge base configured, skip this step.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .claude/commands/execute.md
+git commit -m "feat: add knowledge-aware context loading to /execute"
+```
+
+---
+
+### Task 9: Update CLAUDE.md Template + Project CLAUDE.md
+
+**Files:**
+- Modify: `.claude/references/claude-md-template.md`
+- Modify: `CLAUDE.md`
+
+- [ ] **Step 1: Add Knowledge Base section to the template**
+
+Add after the `## Agents` section in `.claude/references/claude-md-template.md`:
+
+```markdown
+## Knowledge Base
+
+Path: .obsidian/
+
+[Auto-configured during /init-claude-md setup. Set to the folder path for project knowledge notes. Remove this section to disable knowledge base features.]
+```
+
+- [ ] **Step 2: Add Knowledge Base documentation to project CLAUDE.md**
+
+Add after the `## Agents` section in `CLAUDE.md`:
+
+```markdown
+## Knowledge Base
+
+Optional Obsidian-compatible project knowledge base. Stores feature specs, architecture decisions, and project overview as markdown notes that the agent reads/writes during the pipeline.
+
+**Configuration:** Add `## Knowledge Base` with `Path: <path>` to your project's CLAUDE.md. Default: `.obsidian/`. Remove the section to disable.
+
+**Structure:**
+```
+<path>/
+├── overview.md          # Project vision, goals, tech stack
+├── architecture/        # System design, data model
+├── features/            # One note per feature area, linked to GitHub issues
+├── decisions/           # Architecture Decision Records (ADRs)
+├── config/              # Integration metadata, env var names (never actual secrets)
+└── research/            # Brainstorming notes, tech comparisons
+```
+
+**When commands read it:**
+- `/prime` — loads overview + related feature notes (smart/targeted)
+- `/execute` — reads feature context before implementing
+
+**When commands write it:**
+- `/start` (L0) — creates structure + feature notes during brainstorming
+- `/create-prd` — seeds overview + architecture from PRD
+- `/plan-project` — creates feature notes alongside GitHub issues
+- `/ship` — updates feature notes with implementation details
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .claude/references/claude-md-template.md CLAUDE.md
+git commit -m "docs: add knowledge base configuration to CLAUDE.md and template"
+```
+
+---
+
+### Task 10: Update Customization Docs
+
+**Files:**
+- Modify: `docs/customization.md`
+
+- [ ] **Step 1: Add knowledge base customization section**
+
+Add before the `## Contributing` section:
+
+```markdown
+## Configuring the Knowledge Base
+
+The framework includes an optional project knowledge base (Obsidian-compatible) that gives the agent persistent project understanding across sessions.
+
+### Enable
+
+Add to your project's `CLAUDE.md`:
+
+```markdown
+## Knowledge Base
+
+Path: .obsidian/
+```
+
+### Custom Path
+
+Use any folder name:
+
+```markdown
+## Knowledge Base
+
+Path: knowledge/
+```
+
+### Disable
+
+Remove the `## Knowledge Base` section from CLAUDE.md. All knowledge operations are skipped — commands work exactly as before.
+
+### What It Does
+
+Pipeline commands automatically read from and write to the knowledge base:
+- `/start` creates the structure when starting a new project
+- `/prime` loads relevant notes for context before work
+- `/create-prd` seeds the knowledge base from the PRD
+- `/plan-project` creates feature notes alongside GitHub issues
+- `/execute` reads related feature notes before implementing
+- `/ship` updates feature notes after completing work
+
+### Obsidian
+
+If you have [Obsidian](https://obsidian.md/) installed, open your project folder as a vault. The `.obsidian/` directory makes it a valid vault. Notes are navigable, linkable, and searchable through Obsidian's UI. Obsidian is not required — the notes are plain markdown.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/customization.md
+git commit -m "docs: add knowledge base customization guide"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-development-framework",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The system around the AI that makes the AI reliable. Structured AI-assisted development with the PIV+E loop.",
   "bin": {
     "ai-framework": "cli/index.js"