Add project knowledge workflow skills

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
 

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/
+    <module-name>.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.

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.
 

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-<scope>.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
+- `<node>` — purpose. Evidence: `<path[:symbol]>`
+
+### Edges / Flows
+- `<source>` -> `<target>` — why/how. Evidence: ...
+
+### Key Entry Points
+- ...
+
+### Impact Notes
+- Direct impact: ...
+- Indirect impact: ...
+- Tests/verification: ...
+- Risks/gaps: ...
+
+### Recommended Next Step
+- Use `<skill>` because ...
+```
+
+## Optional Durable Map Template
+
+```markdown
+# <Scope> 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 |