ai-development-framework 0.1.0 → 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