diff --git a/README.md b/README.md index b2dc360..ecd7de6 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,8 @@ Pick the smallest workflow that fits the risk: | Requirements are ready | `plan-work` | Produces executable tasks with files and commands | | Written plan exists | `execute-work` | Implements task-by-task with review gates | | Want everything handled end-to-end | `auto-dev-loop` | Runs the lifecycle until verified complete or blocked | +| Unfamiliar repo or risky subsystem | `codebase-map` | Maps nodes, edges, entry points, and impact before planning or refactoring | +| Need shared project knowledge | `project-knowledge` | Initializes or maintains repo-local architecture, flow, convention, and module knowledge | | Need isolated workspace | `worktree-work` | Creates or selects a safe branch/worktree context | | Need multiple agents | `orchestrate-agents` | Coordinates independent workstreams without file conflicts | | Bug, regression, or failing test | `debug-root-cause` | Proves root cause before any fix | @@ -120,6 +122,18 @@ Use `worktree-work` before implementation when the work needs an isolated filesy worktree-work create an isolated worktree for the selected-skills installer feature ``` +Use `codebase-map` before planning/refactoring when the repo or subsystem is unfamiliar. + +```text +codebase-map map the auth flow before we refactor session handling +``` + +Use `project-knowledge` when that map should become durable context other skills can reuse. + +```text +project-knowledge initialize repo-local knowledge and promote the auth map into docs/ai/knowledge +``` + Use `orchestrate-agents` when multiple independent streams can safely run without touching the same files. ```text @@ -150,15 +164,21 @@ If review comments arrive later, use `review-feedback` instead of blindly applyi review-feedback evaluate these PR comments and implement only the accepted items ``` -### 7. Capture Reusable Lessons Sparingly +### 7. Keep Project Knowledge Useful + +Use `project-knowledge` for the shared repo knowledge base: architecture, flows, module maps, conventions, decisions, and verified failure patterns under `docs/ai/knowledge/`. + +```text +project-knowledge update the module map for the installer after this refactor +``` -Use `capture-learning` only for knowledge future sessions will reuse: conventions, root causes, setup gotchas, or important module maps. +Use `capture-learning` for a specific verified reusable lesson that should be stored in local memory or promoted into project knowledge. ```text capture-learning store the verified installer path-handling convention ``` -Do not store transcripts, raw logs, secrets, or one-off progress. +Do not store transcripts, raw logs, secrets, speculation, or one-off progress. ### 8. Finish The Work Cleanly diff --git a/docs/project-knowledge.md b/docs/project-knowledge.md new file mode 100644 index 0000000..f932695 --- /dev/null +++ b/docs/project-knowledge.md @@ -0,0 +1,53 @@ +# Project Knowledge + +`project-knowledge` adds an offline, Markdown-first knowledge layer for projects that install dev-kit. + +The goal is to give future agent sessions shared context before they run `plan-work`, `execute-work`, `review-work`, `debug-root-cause`, or `orchestrate-agents`. + +## Why This Exists + +Large repos need more than task memory. Agents repeatedly rediscover: + +- entry points; +- module boundaries; +- important runtime/data flows; +- project conventions; +- verified failure patterns; +- decisions that explain why code looks the way it does. + +Inspired by codebase-understanding and knowledge-graph tools, dev-kit keeps the implementation simple and portable: Markdown files in the target repo, with evidence attached to every claim. + +## Default Layout In Target Projects + +```text +docs/ai/knowledge/ + index.md + architecture.md + flows.md + decisions.md + conventions.md + failure-patterns.md + modules/ + .md +``` + +## Recommended Flow + +```text +codebase-map map the billing subsystem before refactoring it +project-knowledge promote that map into docs/ai/knowledge/modules/billing.md +plan-work create the implementation plan using project knowledge as context +execute-work implement task 1 +review-work review the diff against the plan and project knowledge +verify-work prove the change is safe +project-knowledge update the affected module knowledge if the architecture changed +``` + +## Rules + +- Store verified reusable knowledge only. +- Cite evidence: source files, symbols, tests, command output, or explicit user instruction. +- Mark unknown/stale areas instead of guessing. +- Never store secrets, raw logs, transcripts, customer data, or one-off progress. +- Use `context-handoff` for paused task state. +- Use `capture-learning` for narrow reusable lessons; promote to `project-knowledge` when it should support future workflows broadly. diff --git a/scripts/install.sh b/scripts/install.sh index fba236c..0403c88 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -137,14 +137,16 @@ When the user's request matches one of these workflows, use the matching skill b - Bug, failing test, regression, production issue -> \`debug-root-cause\` - Any done/fixed/passing/ready claim -> \`verify-work\` - Refactor, simplify, reduce complexity -> \`simplify-work\` -- Understand, document, or remember code/project knowledge -> \`capture-learning\` +- Understand or map an unfamiliar repo/subsystem before changing it -> \`codebase-map\` +- Initialize, update, query, or maintain repo-local knowledge for future agents -> \`project-knowledge\` +- Document or remember a specific verified reusable lesson -> \`capture-learning\` - Received code review feedback -> \`review-feedback\` - Review README, install docs, guides, or skill docs -> \`docs-review\` - Code review, diff review, implementation check -> \`review-work\` - Branch ready for final review, commit, or PR -> \`finish-work\` - Create or revise skills -> \`writing-skills\` -Golden path: \`start-work -> shape-work when needed -> plan-work -> execute-work -> review-work -> verify-work -> capture-learning -> finish-work\`. +Golden path: \`start-work -> codebase-map/project-knowledge when context is missing -> shape-work when needed -> plan-work -> execute-work -> review-work -> verify-work -> capture-learning/project-knowledge -> finish-work\`. Fast path: for tiny low-risk tasks, make the change, run \`verify-work\`, and report evidence. Do not create lifecycle docs for typo-level work. diff --git a/skills/codebase-map/SKILL.md b/skills/codebase-map/SKILL.md new file mode 100644 index 0000000..7dad41c --- /dev/null +++ b/skills/codebase-map/SKILL.md @@ -0,0 +1,179 @@ +--- +name: codebase-map +description: Use when onboarding to an unfamiliar repo, preparing a significant refactor, doing impact analysis, or explaining how a codebase/module works before changing it. +--- + +# Codebase Map + +## Purpose + +Create a lightweight, evidence-backed map of a repo or subsystem before planning, refactoring, reviewing, or handing work to another agent. + +This is inspired by knowledge-graph workflows: identify nodes, edges, entry points, flows, and risk boundaries. Keep it offline and Markdown-first. Do not require a graph database, LLM service, package install, browser, or network call. + +## When To Use + +- Starting work in an unfamiliar repo or large module. +- User asks to understand architecture, flows, dependencies, or impact. +- A refactor touches multiple components. +- Planning agent handoff or parallel workstreams. +- Reviewing whether a change may break downstream behavior. +- Before `plan-work` when the implementation surface is unclear. +- Before `debug-root-cause` only if the system boundaries are unknown; then switch to debugging. + +## When Not To Use + +- Tiny obvious edits with one file and one verification command. +- Active bug investigation with a clear reproduction path: use `debug-root-cause`. +- Storing durable knowledge after the map is complete: use `capture-learning` for reusable docs. +- General docs review: use `docs-review`. +- Dependency-only changes: use `dependency-work`. + +## Hard Rules + +- Evidence first: every important node/edge must cite files, symbols, commands, docs, or tests. +- Do not infer architecture from filenames alone; verify entry points and call/reference paths. +- Keep maps scoped. Map the smallest repo area that answers the question. +- Prefer static inspection and repo-local commands. Do not require network access or package installs. +- Do not expose or store secrets. If configs contain secrets, report only the variable names/patterns. +- Do not edit implementation while mapping unless the user explicitly asked for docs-only output. +- If the map will guide code changes, include verification commands and risk boundaries. + +## Workflow + +1. Define map scope. + - Whole repo, package, feature, API route, CLI command, workflow, or module. + - State the user question the map must answer. + +2. Inventory top-level structure. + - README/docs. + - Package manifests and build/test config. + - Source roots. + - Entry points. + - Tests and fixtures. + - Deployment/config files. + +3. Build node list. + - Components, modules, services, CLIs, routes, jobs, skills, data stores, external integrations. + - For each node, capture purpose and evidence path. + +4. Build edge list. + - Imports/calls. + - API/client boundaries. + - Data flow. + - Config/env flow. + - File/artifact flow. + - Runtime/deployment flow. + +5. Trace key flows. + - Startup path. + - Main user action path. + - Error path. + - Persistence/artifact path when relevant. + - Auth/security path when relevant. + +6. Assess impact and risks. + - Direct and indirect callers. + - Shared state and side effects. + - Tests covering the area. + - Missing tests or unclear ownership. + - Security/privacy concerns. + - Operational assumptions. + +7. Produce a map artifact when useful. + - Prefer `docs/ai/implementation/map-.md` for durable project-local maps. + - For temporary analysis, answer inline and do not create files. + - Use Mermaid only when it clarifies the flow. + +8. Route next action. + - If implementing: continue with `plan-work`, `tdd-work`, or `execute-work`. + - If debugging: continue with `debug-root-cause`. + - If preserving reusable knowledge: continue with `capture-learning`. + - If coordinating agents: continue with `orchestrate-agents`. + +## Output Template + +```markdown +## Codebase Map + +Scope: ... +Question answered: ... + +### Nodes +- `` — purpose. Evidence: `` + +### Edges / Flows +- `` -> `` — why/how. Evidence: ... + +### Key Entry Points +- ... + +### Impact Notes +- Direct impact: ... +- Indirect impact: ... +- Tests/verification: ... +- Risks/gaps: ... + +### Recommended Next Step +- Use `` because ... +``` + +## Optional Durable Map Template + +```markdown +# Codebase Map + +Last verified: YYYY-MM-DD +Question: ... +Evidence commands: +- `...` + +## Component Graph + +```mermaid +graph TD + A[Entry point] --> B[Service] + B --> C[Store] +``` + +## Nodes + +| Node | Role | Evidence | +|---|---|---| +| ... | ... | ... | + +## Flows + +### Startup +... + +### Main User Flow +... + +### Persistence / Artifacts +... + +## Boundaries And Risks +... + +## Verification Commands +... +``` + +## Evaluation Notes + +- Trigger test: "Map this repo before refactoring auth" should invoke `codebase-map`. +- Negative trigger test: "This test fails, fix it" should invoke `debug-root-cause`, not mapping first unless boundaries are unknown. +- Workflow test: A fresh agent can identify nodes, edges, entry points, and verification commands from repo evidence. +- Failure-mode test: The skill rejects speculation and avoids reading secrets or doing package installs by default. +- Output test: The map includes scope, nodes, edges/flows, evidence, impact notes, and next skill. + +## Red Flags + +| Rationalization | Why It Is Wrong | Do Instead | +|---|---|---| +| "The folder names explain it" | Names lie or become stale | Verify with entry points, imports, and tests | +| "Map everything" | Huge maps become unusable | Scope to the current question | +| "No tests mentioned, so none exist" | Tests may be elsewhere | Search manifests, CI, and test directories | +| "Architecture doc says X" | Docs drift | Cross-check source evidence | +| "Let's refactor while mapping" | Mixing phases hides risk | Finish map, then choose the next skill | diff --git a/skills/project-knowledge/SKILL.md b/skills/project-knowledge/SKILL.md new file mode 100644 index 0000000..96d99fe --- /dev/null +++ b/skills/project-knowledge/SKILL.md @@ -0,0 +1,194 @@ +--- +name: project-knowledge +description: Use to initialize, update, query, or maintain a repo-local project knowledge base that supports other dev-kit skills with verified architecture, decisions, conventions, and module maps. +--- + +# Project Knowledge + +## Purpose + +Give the project a durable, local knowledge base that future agents can read before planning, debugging, reviewing, or refactoring. + +This borrows the useful idea from Understand-Anything — turn a codebase into navigable knowledge — but keeps dev-kit offline-first and Markdown-first. No graph database, embedding service, web app, or network access is required. + +## When To Use + +- User asks to initialize or manage project knowledge. +- Starting work in a repo where future agents should share architecture context. +- A `codebase-map` result should become reusable project knowledge. +- `debug-root-cause` found a verified failure pattern worth preserving. +- `plan-work`, `review-work`, or `orchestrate-agents` needs a quick project context pack. +- Before a large refactor when existing `docs/ai/knowledge/` is missing or stale. + +## When Not To Use + +- One-off task progress or transcript handoff: use `context-handoff`. +- Unverified guesses, brainstorms, or raw logs. +- Public docs polish: use `docs-review`. +- Tiny edits where knowledge storage would add noise. +- Secrets, credentials, customer data, private data, or production dumps. + +## Hard Rules + +- Store only verified, reusable knowledge. +- Cite evidence for every meaningful claim: file path, symbol, command, test, or user instruction. +- Keep the knowledge base repo-local under `docs/ai/knowledge/`. +- Do not require network calls, package managers, databases, or long-running services. +- Do not store raw secrets. For configs, document variable names and purpose only. +- Update indexes when adding or changing knowledge docs. +- Mark stale or unverified areas explicitly instead of pretending coverage is complete. + +## Knowledge Layout + +Use these files by default: + +```text +docs/ai/knowledge/ + index.md # map of all knowledge docs and freshness + architecture.md # high-level component graph and entry points + flows.md # important user/data/runtime flows + decisions.md # durable technical decisions + conventions.md # coding, testing, naming, repo conventions + failure-patterns.md # verified bugs/root causes/prevention notes + modules/ + .md # scoped module maps +``` + +If the project already has an equivalent folder, adapt to it and document the convention in `index.md`. + +## Workflow: Initialize Knowledge Base + +1. Create `docs/ai/knowledge/` and `docs/ai/knowledge/modules/`. +2. Inspect README, package manifests, CI, source roots, tests, and config examples. +3. Create or update `index.md` with: + - last verified date; + - repo purpose; + - knowledge coverage table; + - quick links; + - recommended read order for agents. +4. Create starter docs only when evidence exists. Leave unknown sections as `Unknown / not mapped yet`. +5. End with verification commands used and recommended next skill. + +## Workflow: Query Before Other Skills + +Before `plan-work`, `execute-work`, `review-work`, `debug-root-cause`, or `orchestrate-agents` on a non-trivial repo: + +1. Read `docs/ai/knowledge/index.md` if it exists. +2. Read the narrow docs linked for the current subsystem. +3. Check freshness and evidence dates. +4. If stale, verify against source before relying on it. +5. Continue with the target skill using the knowledge as context, not as authority. + +## Workflow: Promote A Map To Knowledge + +1. Start from a verified `codebase-map` or direct source analysis. +2. Choose the narrowest target doc: + - repo-wide structure -> `architecture.md`; + - runtime/data path -> `flows.md`; + - subsystem -> `modules/.md`; + - convention -> `conventions.md`; + - root cause -> `failure-patterns.md`. +3. Add evidence and last-verified date. +4. Update `index.md` coverage table and read order. +5. Run `verify-work` or the repo's docs/structure checks. + +## Document Templates + +### `index.md` + +```markdown +# Project Knowledge Index + +Last verified: YYYY-MM-DD +Repo: +Purpose: + +## Recommended Read Order + +1. `architecture.md` for system shape. +2. `flows.md` for runtime/data movement. +3. Relevant `modules/*.md` for the current work. +4. `decisions.md`, `conventions.md`, and `failure-patterns.md` before changing behavior. + +## Coverage + +| Area | Doc | Status | Evidence | +|---|---|---|---| +| Architecture | `architecture.md` | mapped / partial / stale | ... | + +## Open Questions + +- ... +``` + +### Module Doc + +```markdown +# Knowledge + +Last verified: YYYY-MM-DD +Scope: ... + +## Purpose + +... + +## Entry Points + +- `path/file.ext:symbol` — ... + +## Dependencies + +- Inbound callers: ... +- Outbound dependencies: ... +- Config/env: ... + +## Key Flows + +```mermaid +graph TD + A[Caller] --> B[Module] + B --> C[Dependency] +``` + +## Tests / Verification + +- `command` — result/evidence + +## Risks And Change Notes + +- ... +``` + +## Output Template + +```markdown +## Project Knowledge Update + +Action: Initialized | Updated | Queried | Promoted map +Location: `docs/ai/knowledge/...` +Evidence: ... +Freshness: ... +Supports next skills: ... +Remaining gaps: ... +Verification: ... +``` + +## Evaluation Notes + +- Trigger test: "Initialize project knowledge so other skills can use it" should invoke `project-knowledge`. +- Trigger test: "Use existing project knowledge before planning this refactor" should query `docs/ai/knowledge/index.md` first. +- Negative trigger test: "Save current task progress" should use `context-handoff`, not this skill. +- Workflow test: A fresh agent can create index/module docs with evidence and update the index. +- Failure-mode test: Secrets and unverified guesses are rejected. +- Output test: Result includes location, evidence, freshness, supported next skills, gaps, and verification. + +## Red Flags + +| Rationalization | Why It Is Wrong | Do Instead | +|---|---|---| +| "A knowledge graph needs a service" | Dev-kit must stay offline and portable | Use Markdown nodes/edges with evidence | +| "Store everything" | Noise makes retrieval worse | Store reusable, scoped knowledge only | +| "Docs already say it" | Docs drift | Verify against source before relying on it | +| "This might be useful someday" | Speculation rots | Store only likely reusable knowledge | +| "Copy secrets for completeness" | Unsafe and unnecessary | Document env variable names only | diff --git a/skills/registry.json b/skills/registry.json index 4162c2b..54a2aa1 100644 --- a/skills/registry.json +++ b/skills/registry.json @@ -58,6 +58,16 @@ "path": "skills/capture-learning", "description": "Use to document code entry points, store durable project knowledge, capture root causes, preserve conventions, or map unfamiliar modules." }, + { + "name": "codebase-map", + "path": "skills/codebase-map", + "description": "Use when onboarding to an unfamiliar repo, preparing a significant refactor, doing impact analysis, or explaining how a codebase/module works before changing it." + }, + { + "name": "project-knowledge", + "path": "skills/project-knowledge", + "description": "Use to initialize, update, query, or maintain a repo-local project knowledge base that supports other dev-kit skills with verified architecture, decisions, conventions, and module maps." + }, { "name": "context-handoff", "path": "skills/context-handoff", diff --git a/tests/test-install.sh b/tests/test-install.sh index 292e456..bbe0d43 100755 --- a/tests/test-install.sh +++ b/tests/test-install.sh @@ -38,6 +38,8 @@ assert_file "$PROJECT/AGENTS.md" assert_file "$PROJECT/.github/copilot-instructions.md" assert_file "$PROJECT/.claude/skills/start-work/SKILL.md" assert_file "$PROJECT/.claude/skills/tdd-work/SKILL.md" +assert_file "$PROJECT/.claude/skills/codebase-map/SKILL.md" +assert_file "$PROJECT/.claude/skills/project-knowledge/SKILL.md" assert_file "$PROJECT/.claude/registry.json" assert_file "$PROJECT/.opencode/skills/review-feedback/SKILL.md" assert_file "$PROJECT/.opencode/skills/review-work/SKILL.md" @@ -46,6 +48,7 @@ assert_file "$PROJECT/.opencode/registry.json" assert_file "$PROJECT/.github/prompts/start-work.prompt.md" assert_file "$PROJECT/.github/prompts/docs-review.prompt.md" assert_file "$PROJECT/.github/prompts/review-work.prompt.md" +assert_file "$PROJECT/.github/prompts/project-knowledge.prompt.md" assert_file "$PROJECT/.github/dev-kit-registry.json" assert_marker_once "$PROJECT/CLAUDE.md" assert_marker_once "$PROJECT/AGENTS.md" @@ -72,6 +75,7 @@ mkdir -p "$CUSTOM" "$ROOT/scripts/install.sh" "$CUSTOM" --claude --skills-dir .custom/skills assert_file "$CUSTOM/CLAUDE.md" assert_file "$CUSTOM/.custom/skills/start-work/SKILL.md" +assert_file "$CUSTOM/.custom/skills/project-knowledge/SKILL.md" assert_file "$CUSTOM/.custom/registry.json" assert_not_file "$CUSTOM/.claude/skills/start-work/SKILL.md" diff --git a/tests/test-skill-structure.sh b/tests/test-skill-structure.sh index e45b1e5..86abd03 100755 --- a/tests/test-skill-structure.sh +++ b/tests/test-skill-structure.sh @@ -27,7 +27,7 @@ for skill_dir in "$SKILLS_DIR"/*; do grep -q "\"path\": \"skills/$skill_name\"" "$REGISTRY" || fail "$skill_name path missing from registry" done -for required in start-work shape-work plan-work execute-work auto-dev-loop worktree-work orchestrate-agents debug-root-cause verify-work simplify-work capture-learning finish-work review-work writing-skills tdd-work review-feedback docs-review; do +for required in start-work shape-work plan-work execute-work auto-dev-loop worktree-work orchestrate-agents debug-root-cause verify-work simplify-work capture-learning codebase-map project-knowledge finish-work review-work writing-skills tdd-work review-feedback docs-review; do [ -f "$SKILLS_DIR/$required/SKILL.md" ] || fail "missing required skill: $required" done