@rryando/arcs 3.0.0

package/opencode/arcs/skills/writing-plans/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: writing-plans
+description: Use when you have a spec or requirements for a multi-step task, before touching code
+---
+
+# Skill: writing-plans
+
+## When
+
+You have a spec or requirements for a multi-step task and need to create a detailed implementation plan before touching code.
+
+> CLI Primer: `arcs --commands --json` for discovery. Mutating commands run directly — no token.
+
+## Flow
+
+```mermaid
+flowchart TD
+    A[Detect Mode] --> B{Bash available?}
+    B -->|yes| C[Agent-Direct Mode]
+    B -->|no| D[Orchestrator Mode]
+    C --> E[Scope Check]
+    D --> E
+    E --> F{Multi-subsystem?}
+    F -->|yes| G[Split into separate plans]
+    F -->|no| H[Map File Structure]
+    H --> I[Define Tasks - bite-sized]
+    I --> J[Generate Diagram .mmd]
+    J --> K[Review Loop]
+    K --> L{Reviewer approves?}
+    L -->|issues| M[Fix chunk]
+    M --> K
+    L -->|approved| N{Last chunk?}
+    N -->|no| K
+    N -->|yes| O[Store Plan via CLI]
+    O --> P[Execution Handoff]
+```
+
+## Mode Detection
+
+- Bash available (`arcs --commands --json` works) → **agent-direct**: write plan + diagram + tasks via CLI
+- No bash → **orchestrator mode**: return structured artifact:
+
+```
+---plan-artifact---
+title: <plan title>
+summary: <one-line summary>
+keywords: ["implementation-plan", ...]
+sourceFiles: [{path: "...", anchor: "..."}]
+---body---
+<full plan markdown body>
+---diagram---
+<full .mmd file content>
+---tasks---
+- title: <task 1>
+  priority: high|medium|low
+  sourceFiles: [{path: "..."}]
+---end---
+```
+
+## File Structure
+
+Before defining tasks, map which files will be created/modified:
+
+- One clear responsibility per file. Files that change together live together.
+- Follow existing codebase patterns. Split only when a file has grown unwieldy.
+- This structure informs task decomposition — each task produces self-contained changes.
+
+## Bite-Sized Task Granularity
+
+Each step is one action (2-5 minutes):
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+````
+
+## Plan Document Header
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use arcs:subagent-driven-development (if subagents available) or arcs:executing-plans to implement this plan.
+
+**Goal:** [One sentence]
+
+**Architecture:** [2-3 sentences]
+
+**Tech Stack:** [Key technologies]
+
+---
+
+> Diagram: plans/<plan-id>.diagram.mmd
+```
+
+## Diagram Section
+
+Diagrams are **agentic execution maps** in separate `.mmd` files — never embedded in plan body. Load `to-diagram` skill for conventions.
+
+- File: `plans/<plan-id>.diagram.mmd`
+- Draft the plan in memory or `/tmp` first; persist only after user confirms
+- Node IDs: `T001`, `T002`, ... (stable, never change)
+- If design-phase `.mmd` exists (from brainstorming): EXTEND it, don't regenerate
+- If no prior diagram: generate fresh per `to-diagram` conventions
+
+**Required per-node metadata** (in `%%` comment block before `flowchart TD`):
+`node`, `title`, `status`, `skill`, `scope`, `files`, `acceptance`, `verify`, `blocked-by`, `delegate`
+
+All nodes start `:::backlog` but metadata must be fully populated at creation time for diagram-first execution.
+
+## Plan Review Loop
+
+```mermaid
+flowchart TD
+    A[Write chunk] --> B[Dispatch reviewer subagent]
+    B --> C{Issues found?}
+    C -->|yes| D[Fix chunk]
+    D --> B
+    C -->|no| E{Last chunk?}
+    E -->|no| A
+    E -->|yes| F[Proceed to storage]
+```
+
+- Chunk boundaries: `## Chunk N: <name>`, ≤1000 lines each
+- Same agent fixes (preserves context). Max 5 iterations, then surface to human.
+- Reviewer must announce confidence score per `confidence-gate`. Score <80% loops back to "Fix chunk" — never proceed past a sub-threshold review.
+
+## Storage
+
+```bash
+arcs plan create <slug> --title="YYYY-MM-DD <feature> Implementation Plan" --summary="..." --status=planned --keywords="implementation-plan" --body="<markdown>" --json
+```
+
+## Execution Handoff
+
+> "Plan complete and saved to arcs project plan `<planId>` in project `<slug>`. Ready to execute?"
+
+- **Subagents available** → REQUIRED: use `arcs:subagent-driven-development`
+- **No subagents** → use `arcs:executing-plans`
+
+## Constraints
+
+- Exact file paths always — never vague references
+- Complete code in plan (not "add validation")
+- Exact commands with expected output
+- DRY, YAGNI, TDD, frequent commits
+- Announce mode and skill at start
+- Scope check: multi-subsystem → split into separate plans
+- Implementation sub-agents NEVER edit `.mmd` files

package/opencode/arcs/skills/writing-plans/plan-document-reviewer-prompt.md

@@ -0,0 +1,52 @@
+# Plan Document Reviewer Prompt Template
+
+Use this template when dispatching a plan document reviewer subagent.
+
+**Purpose:** Verify the plan chunk is complete, matches the spec, and has proper task decomposition.
+
+**Dispatch after:** Each plan chunk is written
+
+```
+Task tool (general-purpose):
+  description: "Review plan chunk N"
+  prompt: |
+    You are a plan document reviewer. Verify this plan chunk is complete and ready for implementation.
+
+    **Plan chunk to review:** [PLAN_FILE_PATH] - Chunk N only
+    **Spec for reference:** [SPEC_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
+    | Spec Alignment | Chunk covers relevant spec requirements, no scope creep |
+    | Task Decomposition | Tasks atomic, clear boundaries, steps actionable |
+    | File Structure | Files have clear single responsibilities, split by responsibility not layer |
+    | File Size | Would any new or modified file likely grow large enough to be hard to reason about as a whole? |
+    | Task Syntax | Checkbox syntax (`- [ ]`) on steps for tracking |
+    | Chunk Size | Each chunk under 1000 lines |
+
+    ## CRITICAL
+
+    Look especially hard for:
+    - Any TODO markers or placeholder text
+    - Steps that say "similar to X" without actual content
+    - Incomplete task definitions
+    - Missing verification steps or expected outputs
+    - Files planned to hold multiple responsibilities or likely to grow unwieldy
+
+    ## Output Format
+
+    ## Plan Review - Chunk N
+
+    **Status:** Approved | Issues Found
+
+    **Issues (if any):**
+    - [Task X, Step Y]: [specific issue] - [why it matters]
+
+    **Recommendations (advisory):**
+    - [suggestions that don't block approval]
+```
+
+**Reviewer returns:** Status, Issues (if any), Recommendations

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@rryando/arcs",
+  "version": "3.0.0",
+  "description": "ARCS — DAG-based task orchestration for AI agents. Persistent workflow continuity via graph-structured context.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "arcs": "scripts/arcs-cli.mjs"
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "skills/",
+    "opencode/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rryando/arcs.git"
+  },
+  "keywords": [
+    "arcs",
+    "dag",
+    "ai-agents",
+    "task-orchestration",
+    "graph",
+    "workflow",
+    "cli"
+  ],
+  "author": "rryando",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "build:opencode-bundle": "npm run build && node scripts/build-opencode-bundle.mjs",
+    "prepack": "npm run build:opencode-bundle",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "postinstall": "npm run build && node scripts/arcs-init.mjs",
+    "init": "npm run build && node dist/index.js init",
+    "lint": "biome check src/ test/",
+    "lint:fix": "biome check --fix src/ test/",
+    "format": "biome format --write src/ test/",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "picocolors": "^1.1.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3",
+    "vite": "^6.4.1",
+    "vitest": "^3.2.4"
+  }
+}

package/scripts/arcs-cli.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+// Standalone CLI entry point for sub-agent consumption.
+// Requires `npm run build` first — imports from dist/.
+// Outputs JSON to stdout, errors to stderr.
+// Exit codes: 0 success, 1 user error, 2 internal error.
+
+import { handleCli } from "../dist/cli/index.js";
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  if (process.stdin.isTTY) {
+    // Human at terminal: show status dashboard
+    const { showStatusDashboard } = await import("../dist/cli/status-dashboard.js");
+    await showStatusDashboard();
+    process.exit(0);
+  }
+  process.stderr.write(
+    "Usage: arcs <command> [args]\n" +
+      "Commands: context, task, plan, knowledge, search, diagram, batch, validate\n" +
+      "Run `npm run build` before first use.\n"
+  );
+  process.exit(1);
+}
+
+if (args[0] === "--help" || args[0] === "-h") {
+  process.stderr.write(
+    "Usage: arcs <command> [args]\n" +
+      "Commands: context, task, plan, knowledge, search, diagram, batch, validate\n"
+  );
+  process.exit(0);
+}
+
+try {
+  const handled = await handleCli(args);
+  if (!handled) {
+    process.stderr.write(`Unknown command: ${args[0]}\n`);
+    process.exit(1);
+  }
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`Error: ${message}\n`);
+  process.exit(2);
+}

package/skills/explore-dag.md

@@ -0,0 +1,57 @@
+---
+name: explore-dag
+description: Navigate and understand the project DAG
+---
+
+> **Canonical source:** `src/cli/arcs-orchestrate.ts` under `### EXPLORE Workflow`.
+
+## When
+
+Need to understand project relationships, find context, inspect plan and knowledge indexes, or traverse dependencies.
+
+## Flow
+
+```mermaid
+flowchart TD
+    classDef sub fill:#8b5cf6,color:#fff
+
+    A[arcs project list → big picture] --> B{Question answered by DAG?}
+    B -->|yes| C[Report from DAG data]
+    B -->|no| D[Dispatch explore sub-agent]:::sub
+    D --> E{Durable discovery?}
+    E -->|yes| F[arcs knowledge create]
+    E -->|no| C
+    F --> C
+```
+
+## CLI Primer
+
+```bash
+arcs <command> --json
+```
+Discovery: `arcs --commands --json`
+
+## Key Commands
+
+| Operation | Command |
+|-----------|---------|
+| All projects | `arcs project list --json` |
+| Project meta | `arcs project get <slug> --json` |
+| Project doc | `arcs project get <slug> --doc=<doc> --json` |
+| Plan and knowledge indexes | `arcs plan list <slug> --json` / `arcs knowledge list <slug> --json` |
+| Full body | `arcs plan get <slug> <id> --body --json` / `arcs knowledge get <slug> <id> --body --json` |
+| Search | `arcs search <slug> "<query>" --json` |
+
+## Traversal Pattern
+
+1. `arcs project list --json` → get all projects + `dependsOn[]`
+2. Filter for dependencies of interest
+3. `arcs project get <slug> --json` per dependency for meta/docs
+4. Build dependency chain
+
+## Tips
+
+- Start with `arcs project list` for the big picture
+- Use `knowledge` docs to quickly understand unfamiliar codebases
+- Check `status` to know if a dependency is still actively maintained
+- Persist durable discoveries via `arcs knowledge create`

package/skills/init-project.md

@@ -0,0 +1,105 @@
+---
+name: init-project
+description: Initialize a new project in the DAG
+---
+
+> **Canonical source:** `src/cli/arcs-orchestrate.ts` under `### INIT Workflow`.
+
+## When
+
+User wants to track a new project, bootstrap documentation, or connect a repo to the DAG.
+
+## Flow
+
+```mermaid
+flowchart TD
+    classDef sub fill:#8b5cf6,color:#fff
+
+    A[Gather: name, description, repoUrl?, dependsOn?] --> B[arcs project list → conflict check]
+    B --> C[Present summary to user]
+    C -->|confirmed| D[arcs project init]
+    D --> E[arcs project update-doc × 4]
+    E --> F{graphify on PATH?}
+    F -->|yes| G[graphify update --force --no-cluster]
+    F -->|no| H[Skip graph step, log gap]
+    G --> G2[ingestGraph → ≤20 proposals]
+    G2 --> G3[graphify query / explain for enrichment]:::sub
+    H & G3 --> I[Fan out: system-architect + docs-researcher + tech-architect]:::sub
+    I --> J[Collect proposals → dedup → arcs knowledge create × N]
+    J --> K[Done]
+```
+
+## CLI Primer
+
+```bash
+arcs <command> --json
+```
+Discovery: `arcs --commands --json`
+
+## Constraints
+
+- Do NOT read repo to infer name/description — gather from user
+- Verify `dependsOn` targets exist via `arcs project list --json`
+- Init creates empty plans/ and knowledge/ indexes
+- Repo analysis is **fan-out across typed agents**, not a generic "analysis sub-agent" (see Agent Dispatch table below)
+
+## Graphify Sub-Flow (DEFAULT: ON when binary present)
+
+The orchestrator runs graphify directly during INIT to seed knowledge entries with structural evidence before any sub-agent reads code.
+
+1. **Detect:** `detectGraphify()` from `src/utils/graphify.ts`. If unavailable, skip cleanly — never block INIT on graphify.
+2. **Trust the gitignore guarantee:** `runExtraction()` already auto-appends `graphify-out/` to `.gitignore` (`ensureGitignoreEntry`). Don't redundantly check or modify `.gitignore` from agents — running extraction is sufficient.
+3. **Extract (AST-only, no LLM key required):**
+   ```bash
+   graphify update <workspacePath> --force --no-cluster
+   ```
+   Produces `graphify-out/graph.json`.
+4. **Ingest:** call internal `ingestGraph(graphJsonPath, slug)` → up to 20 `KnowledgeProposal` records:
+   - 8 god nodes (`kind=module`, top 5% degree, test files filtered)
+   - 8 architecture clusters (`kind=architecture`, by community or directory grouping)
+   - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs)
+5. **Enrich** with read-only graph queries (sub-agents may run these):
+   - `graphify query "entry points and main commands" --graph graphify-out/graph.json --budget 2000` → seeds for "key files" reference entries
+   - `graphify query "core data flow" --graph graphify-out/graph.json --budget 2000` → seeds for "core modules" entries
+   - `graphify explain "<godNodeLabel>" --graph graphify-out/graph.json` → plain-language summary for module entry bodies
+   - `graphify affected "<critical-symbol>" --graph graphify-out/graph.json --depth 2` → reverse-impact map for high-risk modules
+   - `graphify path "<A>" "<B>" --graph graphify-out/graph.json` → shortest dependency path for architecture entries
+6. **Hand to typed agents:** the proposals + query results go to the sub-agents listed in **Agent Dispatch** below; they merge graph evidence with code reading and return finalized knowledge entries.
+7. **Write** the entries directly via `arcs batch --file=ops.json` (one batch invocation for all knowledge entries) or `arcs knowledge create` per entry.
+
+If graphify is missing, log "graphify not on PATH; proceeding without graph signal" and skip steps 3–5. Sub-agents still run; they just lack the graph priors.
+
+## Content Guidelines
+
+| Doc | Format |
+|-----|--------|
+| overview.md | 2-3 sentence summary + goals |
+| tasks.md | `[ ]` backlog / `[/]` in-progress / `[x]` done |
+| dependencies.md | Upstream + downstream sections |
+| knowledge.md | High-level context + pointers to structured entries |
+
+## Agent Dispatch (named typed agents — DO NOT default to a generic analysis agent)
+
+| Sub-agent | Owns | Knowledge kinds it produces |
+|-----------|------|----------------------------|
+| `system-architect` | Module boundaries, clusters, dependency direction | `architecture`, `module` |
+| `docs-researcher` | Tech stack, third-party libraries, key files, features | `reference`, `feature` |
+| `tech-architect` | Cross-module couplings, structural gotchas, lessons | `gotcha`, `lesson` |
+| `qa-analyst` (optional) | Coding-style + convention scan from existing code | `pattern` |
+
+Dispatch in parallel (load `dispatching-parallel-agents`). Each agent receives the relevant `KnowledgeProposal` records from `ingestGraph` plus targeted graphify queries for evidence. Each agent returns finalized proposals (title, kind, summary, keywords, sourceFiles, body) for the orchestrator to write directly via `arcs knowledge create` (or `arcs batch`).
+
+## Knowledge Categories for Analysis Sub-Agents
+
+| Category | Kind | What to discover | Primary agent |
+|----------|------|------------------|---------------|
+| tech stack | `architecture` | Languages, frameworks, runtimes, build tools, versions | `docs-researcher` |
+| key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (graphify query "entry points") |
+| code patterns | `pattern` | Recurring design patterns, abstractions, error handling | `qa-analyst` or `system-architect` |
+| coding style | `pattern` | Formatting, linting, import ordering, file organization | `qa-analyst` |
+| core modules | `module` | Core modules/shared functions — what, where, interconnections | `system-architect` (god nodes from graphify) |
+| external services | `module` | APIs, databases, message queues the project interacts with | `docs-researcher` |
+| third-party libraries | `reference` | Key dependencies and why they are used | `docs-researcher` |
+| features | `feature` | Major user-facing or system-facing features | `docs-researcher` |
+| cross-module couplings | `gotcha` | Hot edges between modules surfaced by graphify | `tech-architect` (auto from `ingestGraph`) |
+| architecture clusters | `architecture` | Community/directory groupings from graphify | `system-architect` (auto from `ingestGraph`) |

package/skills/orchestrate.md

@@ -0,0 +1,94 @@
+---
+name: orchestrate
+description: Classify intent and route work across all ARCS workflows
+---
+
+> **Canonical source:** `src/cli/arcs-orchestrate.ts` (`ORCHESTRATE_PROMPT_TEXT`).
+> This is a condensed summary. TS prompt wins on disagreement.
+
+## When
+
+User request maps to multiple workflows, needs routing, or chains INIT → BRAINSTORM → EXECUTE.
+
+## Flow
+
+```mermaid
+flowchart TD
+    A[User Request] --> B[T0: arcs brief --lean --json]
+    B --> C[Classify Intent]
+    C -->|new project| INIT[INIT]
+    C -->|plan/decompose| BRAINSTORM[BRAINSTORM]
+    C -->|do work| EXECUTE[EXECUTE]
+    C -->|reconcile| SYNC[SYNC]
+    C -->|discover/report| EXPLORE[EXPLORE]
+    C -->|compound| MULTI[MULTI]
+    INIT & BRAINSTORM & EXECUTE & SYNC & EXPLORE & MULTI --> DONE[Completion: what done + state + next steps]
+```
+
+## Context Tiers
+
+| Tier | What | Who |
+|------|------|-----|
+| **T0** | `arcs brief --lean --json` — routing surface, focus, next action | Orchestrator |
+| **T1** | Single doc fetch | Sub-agent (default) |
+| **T2** | Index listings | Sub-agent (default) |
+| **T3** | Full body read | Sub-agent always |
+| **T4** | Multi-doc / audit | Sub-agent always |
+
+**Cardinal rule:** Orchestrator reads T0 + writes. Sub-agents read everything else.
+
+### T0 envelope shape
+
+`arcs brief --json` returns a tight ~1 KB envelope:
+
+```json
+{
+  "slug": "...", "name": "...", "summary": "...",
+  "operatingBrief": {
+    "currentFocus":       "<task or plan title to anchor on>",
+    "recommendedSurface": "QUEUE | PLAN | MEMORY",
+    "why":                "<one-line rationale>",
+    "nextAction":         "<concrete next step the orchestrator should take>"
+  },
+  "activePlansCount": N, "activePlanTitles": [...],
+  "openTasksCount":   N, "topOpenTasks": [{ id, title, status }],
+  "topKnowledge":     [{ id, title, kind }]
+}
+```
+
+Use `recommendedSurface` to pick the routing branch:
+- `QUEUE` → execute the active task (EXECUTE workflow)
+- `PLAN`  → decompose or plan work (BRAINSTORM workflow)
+- `MEMORY` → no active work; review knowledge or propose a new plan
+
+## CLI Primer
+
+All ops: `arcs <group> <action> [args] --json`. Mutating commands run directly — no token:
+```bash
+arcs <command> --json
+```
+Discovery: `arcs --commands --json`
+
+## Skill Selection (EXECUTE)
+
+| Task shape | Skill |
+|-----------|-------|
+| Fully bounded | `quick-dev` |
+| Mostly clear, 1-2 open questions | `code-agent` |
+| Non-trivial, test-first | `test-driven-development` |
+| Design open | reclassify → BRAINSTORM |
+
+## Loop Tools
+
+- `arcs loop start <slug> --prompt="..." --max-iterations=50 --json` — self-referential dev loop
+- `arcs loop cancel <slug> --json` — cancel active loop
+- `arcs loop status <slug> --json` — inspect loop state
+
+Pair with `loop` skill for iteration discipline.
+
+## Completion
+
+Every session ends with:
+1. What was done
+2. Current project state
+3. Suggested next steps

package/skills/update-docs.md

@@ -0,0 +1,72 @@
+---
+name: update-docs
+description: Update project documents with structured content
+---
+
+> **Canonical source:** `src/cli/arcs-orchestrate.ts` `## Content Guidelines`.
+
+## When
+
+Codebase analyzed and findings need recording, task statuses changed, dependencies updated, or knowledge needs capturing.
+
+## Flow
+
+```mermaid
+flowchart TD
+    A[Read current doc: arcs project get] --> B[Prepare updated content]
+    B --> C[Present summary to user]
+    C -->|confirmed| D[arcs project update-doc]
+    D --> E[Verify: arcs project get]
+```
+
+## CLI Primer
+
+```bash
+arcs <command> --json
+```
+Discovery: `arcs --commands --json`
+
+## Content Guidelines
+
+| Doc | Format |
+|-----|--------|
+| overview | 2-3 sentence summary + concrete goals |
+| tasks | `[ ]` backlog / `[/]` in-progress / `[x]` done — execution queue state only |
+| dependencies | Upstream + downstream with notes on *why* |
+| knowledge | Summary landing page → point to structured knowledge entries |
+
+## Structured Plans for Feature Work
+
+Use structured plans for feature work that spans multiple tasks. Create via:
+```bash
+arcs plan create <slug> "Title" --summary="..." --keywords="implementation-plan" --json
+arcs plan update-body <slug> <planId> --body="..." --json
+```
+
+List existing: `arcs plan list <slug> --json`
+
+## Structured Knowledge Entries
+
+For durable project memory (lessons, gotchas, patterns, architecture):
+```bash
+arcs knowledge create <slug> "Title" --kind=<kind> --summary="..." --body="..." --json
+```
+
+List existing: `arcs knowledge list <slug> --json`
+
+| Section | What to include |
+|---------|----------------|
+| Tech Stack | Languages, frameworks, runtimes, key libraries |
+| Architecture | Module boundaries, service topology, data flow |
+| Patterns | Naming conventions, file organization, coding patterns |
+| Gotchas | Non-obvious behaviors, common pitfalls, workarounds |
+| Key Files | Entry points, config files, main modules |
+
+> **Tip**: Summary table in knowledge.md. Deep dives in knowledge entries.
+
+## Plan Keyword Conventions
+
+| Keywords | Status | Origin |
+|----------|--------|--------|
+| `spec`, `design` | `proposed` | Design specs from brainstorming |
+| `implementation-plan` | `planned` | Step-by-step implementation plans |

package/templates/dependency.md.tmpl

@@ -0,0 +1,9 @@
+# Dependencies — {{name}}
+
+## Upstream
+
+{{upstreamBlock}}
+
+## Downstream
+
+- None yet