From fb397df9b214ffb411fe1fd6ac0e91d9df997feb Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Mon, 19 Jan 2026 22:58:46 -0600 Subject: [PATCH] docs: create v1.9.0 roadmap (3 phases) Phases: 1. Foundation & Learning: Index store, PostToolUse hook 2. Context Injection: Convention detection, SessionStart hook 3. Brownfield & Integration: analyze-codebase, GSD integration, docs All 29 v1 requirements mapped to phases. --- .planning/STATE.md | 32 +++--- .planning/milestones/v1.9.0-REQUIREMENTS.md | 106 ++++++++++++++++++++ .planning/milestones/v1.9.0-ROADMAP.md | 71 +++++++++++++ 3 files changed, 191 insertions(+), 18 deletions(-) create mode 100644 .planning/milestones/v1.9.0-REQUIREMENTS.md create mode 100644 .planning/milestones/v1.9.0-ROADMAP.md diff --git a/.planning/STATE.md b/.planning/STATE.md index 27c39e3d8..3852dcd13 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,39 +4,35 @@ See: .planning/PROJECT.md (updated 2026-01-19) -**Core value:** Same guarantees, 50-70% fewer tokens for simple tasks -**Current focus:** Planning next milestone +**Core value:** Claude understands your codebase structure and conventions before it starts working — automatically +**Current focus:** v1.9.0 Codebase Intelligence System ## Current Position -Phase: Ready for new milestone +Phase: 1 of 3 (Foundation & Learning) Plan: Not started -Status: v1.8.0 shipped, ready for next milestone -Last activity: 2026-01-19 — v1.8.0 Quick Mode milestone complete +Status: Ready to plan +Last activity: 2026-01-19 — Roadmap created for v1.9.0 + +Progress: [░░░░░░░░░░] 0% ## Performance Metrics **Velocity:** -- Total plans completed: 3 -- Average duration: 2.3 min -- Total execution time: 7 min +- Total plans completed: 0 +- Average duration: - +- Total execution time: 0 min **By Phase:** | Phase | Plans | Total | Avg/Plan | |-------|-------|-------|----------| -| 1. Core Command | 2/2 | 4 min | 2 min | -| 2. Documentation | 1/1 | 3 min | 3 min | +| 1. Foundation & Learning | 0/2 | - | - | +| 2. Context Injection | 0/2 | - | - | +| 3. Brownfield & Integration | 0/3 | - | - | *Updated after each plan completion* -## Quick Tasks Completed - -| ID | Name | Commit | Date | -|----|------|--------|------| -| 001 | commands-html-page | a1454db | 2026-01-19 | -| 002 | 90s-html-command-reference | fc3287c | 2026-01-19 | - ## Accumulated Context ### Decisions @@ -54,5 +50,5 @@ None. ## Session Continuity Last session: 2026-01-19 -Stopped at: v1.8.0 milestone complete +Stopped at: Roadmap created, ready to plan Phase 1 Resume file: None diff --git a/.planning/milestones/v1.9.0-REQUIREMENTS.md b/.planning/milestones/v1.9.0-REQUIREMENTS.md new file mode 100644 index 000000000..bc8c578c0 --- /dev/null +++ b/.planning/milestones/v1.9.0-REQUIREMENTS.md @@ -0,0 +1,106 @@ +# Requirements: v1.9.0 Codebase Intelligence System + +## v1 Requirements + +### Indexing (INDEX) + +- [ ] **INDEX-01**: PostToolUse hook indexes files after Write/Edit operations +- [ ] **INDEX-02**: Index tracks file paths, exports, and imports +- [ ] **INDEX-03**: Index stored in `.planning/intel/index.json` +- [ ] **INDEX-04**: Hook fails silently on any error (never blocks Claude) +- [ ] **INDEX-05**: Index updates incrementally (add/modify, not full rebuild) + +### Context Injection (CTX) + +- [ ] **CTX-01**: SessionStart hook injects codebase summary into Claude's context +- [ ] **CTX-02**: Summary includes detected conventions (naming, directory patterns) +- [ ] **CTX-03**: Summary includes directory structure overview +- [ ] **CTX-04**: Summary includes key exports by category (classes, functions, consts) +- [ ] **CTX-05**: Summary wrapped in `` tags + +### Convention Detection (CONV) + +- [ ] **CONV-01**: Detect naming patterns (PascalCase, camelCase, kebab-case, snake_case) +- [ ] **CONV-02**: Detect suffix patterns (*.service.ts, *.controller.ts, *.test.ts) +- [ ] **CONV-03**: Detect directory purpose patterns (src/services/, src/components/) +- [ ] **CONV-04**: Confidence threshold: 5+ files required before pattern is detected +- [ ] **CONV-05**: Confidence threshold: 70%+ match rate required +- [ ] **CONV-06**: Conventions stored in `.planning/intel/conventions.json` + +### Brownfield Analysis (BROWN) + +- [ ] **BROWN-01**: `/gsd:analyze-codebase` command scans existing codebase +- [ ] **BROWN-02**: Command works without `/gsd:new-project` (standalone) +- [ ] **BROWN-03**: Creates `.planning/intel/` directory structure +- [ ] **BROWN-04**: Populates index.json with full codebase analysis +- [ ] **BROWN-05**: Generates conventions.json from detected patterns +- [ ] **BROWN-06**: Hooks continue incremental learning after initial analysis + +### GSD Integration (INT) + +- [ ] **INT-01**: `install.js` registers intel hooks in settings.json +- [ ] **INT-02**: `/gsd:new-project` creates `.planning/intel/` structure +- [ ] **INT-03**: Subagent prompts (planner, executor) include codebase context +- [ ] **INT-04**: Summary regenerated when conventions change + +### Documentation (DOC) + +- [ ] **DOC-01**: README.md updated with codebase intelligence section +- [ ] **DOC-02**: help.md updated with `/gsd:analyze-codebase` command +- [ ] **DOC-03**: GSD-STYLE.md updated with intel patterns + +## v2 Requirements (Deferred) + +- PreToolUse convention advisory hook (warn before Write if pattern mismatch) +- `/gsd:intel-correct` command for manual convention corrections +- Exception tracking (intentional deviations from conventions) +- Confidence adjustment based on exceptions +- `/gsd:resume-work` decimal phase handling (from v1.8.0) + +## Out of Scope + +| Exclusion | Reason | +|-----------|--------| +| Semantic embeddings / vector search | Requires API calls, violates zero-API constraint | +| Cross-project convention sharing | Future milestone scope | +| Framework auto-detection | Future milestone scope | +| IDE-like navigation features | Not GSD's domain | +| Native dependencies (tree-sitter) | Breaks installation simplicity | +| Blocking hooks (reject writes) | Advisory-only principle | + +## Traceability + +| Requirement | Phase | Status | +|-------------|-------|--------| +| INDEX-01 | Phase 1 | Pending | +| INDEX-02 | Phase 1 | Pending | +| INDEX-03 | Phase 1 | Pending | +| INDEX-04 | Phase 1 | Pending | +| INDEX-05 | Phase 1 | Pending | +| CTX-01 | Phase 2 | Pending | +| CTX-02 | Phase 2 | Pending | +| CTX-03 | Phase 2 | Pending | +| CTX-04 | Phase 2 | Pending | +| CTX-05 | Phase 2 | Pending | +| CONV-01 | Phase 2 | Pending | +| CONV-02 | Phase 2 | Pending | +| CONV-03 | Phase 2 | Pending | +| CONV-04 | Phase 2 | Pending | +| CONV-05 | Phase 2 | Pending | +| CONV-06 | Phase 1 | Pending | +| BROWN-01 | Phase 3 | Pending | +| BROWN-02 | Phase 3 | Pending | +| BROWN-03 | Phase 3 | Pending | +| BROWN-04 | Phase 3 | Pending | +| BROWN-05 | Phase 3 | Pending | +| BROWN-06 | Phase 3 | Pending | +| INT-01 | Phase 3 | Pending | +| INT-02 | Phase 3 | Pending | +| INT-03 | Phase 3 | Pending | +| INT-04 | Phase 2 | Pending | +| DOC-01 | Phase 3 | Pending | +| DOC-02 | Phase 3 | Pending | +| DOC-03 | Phase 3 | Pending | + +--- +*Created: 2026-01-19* diff --git a/.planning/milestones/v1.9.0-ROADMAP.md b/.planning/milestones/v1.9.0-ROADMAP.md new file mode 100644 index 000000000..2faa0aefd --- /dev/null +++ b/.planning/milestones/v1.9.0-ROADMAP.md @@ -0,0 +1,71 @@ +# Roadmap: v1.9.0 Codebase Intelligence System + +## Overview + +This milestone delivers a living knowledge system that learns codebase structure and conventions as Claude writes code, then injects that understanding into every session. The build order is: learning mechanism (PostToolUse hook) -> injection mechanism (SessionStart hook) -> brownfield analysis command -> GSD workflow integration. + +## Phases + +- [ ] **Phase 1: Foundation & Learning** - Index store, PostToolUse hook, file parsing +- [ ] **Phase 2: Context Injection** - SessionStart hook, convention detection, summary generation +- [ ] **Phase 3: Brownfield & Integration** - analyze-codebase command, GSD integration, documentation + +## Phase Details + +### Phase 1: Foundation & Learning +**Goal**: Claude learns from every file it writes, building an index of the codebase structure +**Depends on**: Nothing (first phase) +**Requirements**: INDEX-01, INDEX-02, INDEX-03, INDEX-04, INDEX-05, CONV-06 +**Success Criteria** (what must be TRUE): + 1. When Claude writes or edits a file, the file's exports and imports are captured in `.planning/intel/index.json` + 2. Index updates incrementally (only the changed file is reprocessed) + 3. Hook failures never block Claude — any error results in silent failure with `{ proceed: true }` + 4. Index file exists at `.planning/intel/index.json` with valid JSON structure +**Plans**: TBD + +Plans: +- [ ] 01-01: Index store and data model +- [ ] 01-02: PostToolUse indexing hook + +### Phase 2: Context Injection +**Goal**: Claude receives codebase understanding automatically at session start +**Depends on**: Phase 1 +**Requirements**: CTX-01, CTX-02, CTX-03, CTX-04, CTX-05, CONV-01, CONV-02, CONV-03, CONV-04, CONV-05 +**Success Criteria** (what must be TRUE): + 1. When a Claude session starts, codebase summary is injected wrapped in `` tags + 2. Summary includes detected naming conventions (camelCase, PascalCase, etc.) with confidence thresholds met (5+ files, 70%+ match) + 3. Summary includes directory structure overview and key exports by category + 4. Conventions are stored in `.planning/intel/conventions.json` + 5. Summary regenerates when conventions change +**Plans**: TBD + +Plans: +- [ ] 02-01: Convention detection engine +- [ ] 02-02: SessionStart injection hook and summary generation + +### Phase 3: Brownfield & Integration +**Goal**: Codebase intelligence works on existing codebases and integrates with GSD workflows +**Depends on**: Phase 2 +**Requirements**: BROWN-01, BROWN-02, BROWN-03, BROWN-04, BROWN-05, BROWN-06, INT-01, INT-02, INT-03, INT-04, DOC-01, DOC-02, DOC-03 +**Success Criteria** (what must be TRUE): + 1. `/gsd:analyze-codebase` command scans existing codebase and populates `.planning/intel/` + 2. Command works without `/gsd:new-project` — standalone operation on any codebase + 3. After initial analysis, hooks continue incremental learning + 4. `install.js` registers intel hooks in settings.json + 5. `/gsd:new-project` creates `.planning/intel/` directory structure + 6. Subagent prompts include codebase context + 7. README, help.md, and GSD-STYLE.md document the codebase intelligence feature +**Plans**: TBD + +Plans: +- [ ] 03-01: analyze-codebase command +- [ ] 03-02: GSD integration (installer, new-project, subagents) +- [ ] 03-03: Documentation updates + +## Progress + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Foundation & Learning | 0/2 | Not started | - | +| 2. Context Injection | 0/2 | Not started | - | +| 3. Brownfield & Integration | 0/3 | Not started | - |