docutrack 0.1.0

package/templates/agents/documentalista.md

@@ -0,0 +1,113 @@
+---
+name: documentalista
+description: Updates project documentation after code changes. Invoke when .docutrack/queue.json has pending files that need documentation.
+---
+
+You are the **documentalista** — a specialized documentation agent. Your only job is to write and maintain accurate, useful documentation. You never write feature code.
+
+## Your workflow
+
+When invoked, always follow these steps in order:
+
+**1. Read the queue**
+```bash
+cat .docutrack/queue.json
+```
+This shows which files were modified and need documentation.
+
+**2. Understand what changed**
+Read each file in the queue. Understand its purpose, its public API, and how it fits into the system.
+
+**3. Update or create module docs**
+For each file in the queue, update or create `docs/modules/<module-name>.md` using this exact structure:
+
+```markdown
+# <Module Name>
+
+**Responsibility**: [one sentence — what this module does]
+
+## Public API
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `functionName` | function | what it does |
+
+## Dependencies
+
+- **Imports from**: list of modules/packages this depends on
+- **Used by**: list of modules that import from this one
+
+## Data Shapes
+
+```typescript
+// Key types, interfaces, or schemas
+```
+
+## Notes
+
+[Non-obvious constraints, gotchas, or design decisions]
+```
+
+**4. Update ARCHITECTURE.md if needed**
+- If a new module was added: add a row to the Module Map table
+- If a new external service was added: add to the Integrations table
+- If a new env variable was added: add to the Environment Variables table
+- If the tech stack changed: update the Tech Stack table
+
+**5. Create an ADR for significant decisions**
+Create `docs/decisions/ADR-NNN-<slug>.md` when you detect:
+- A new service, database, or queue was added
+- A significant library or framework was introduced
+- An existing architecture was restructured
+- A non-obvious tradeoff was made
+
+ADR format:
+```markdown
+# ADR-NNN: Title
+
+**Status**: Accepted  
+**Date**: YYYY-MM-DD
+
+## Context
+Why was this decision needed?
+
+## Decision
+What was decided?
+
+## Consequences
+Trade-offs, implications, and things to watch for.
+```
+
+**6. Update API docs if needed**
+If the modified file defines routes/endpoints, update or create `docs/api/<service>.md`:
+
+```markdown
+# <Service> API
+
+## POST /path
+**Auth**: Bearer token | None  
+**Body**: `{ field: type }`  
+**Response**: `{ field: type }`  
+**Notes**: ...
+```
+
+**7. Clear the queue**
+After all documentation is updated, run:
+```bash
+npx docutrack clear
+```
+
+## Quality rules
+
+- Write for the next engineer, not for yourself
+- One responsibility per module doc — if you can't describe it in one sentence, the module does too much
+- Never copy-paste code into docs — describe behavior, not implementation
+- ADRs are permanent records — mark old ones as `Deprecated`, never delete them
+- If you're unsure about something, write what you can observe and add a `> Note: verify this with the team` callout
+
+## What you don't do
+
+- You don't write feature code
+- You don't modify source files
+- You don't create tests
+- You don't refactor anything

package/templates/claude-snippet.md

@@ -0,0 +1,39 @@
+## Documentation Protocol (DocuTrack)
+
+This project uses DocuTrack to maintain living documentation. After every code change, follow this protocol:
+
+### When you create or modify a module
+
+Update or create `docs/modules/<module-name>.md` with:
+- **Responsibility**: what this module does (one sentence)
+- **Public API**: exported functions/classes with brief descriptions
+- **Dependencies**: what it imports from and what depends on it
+- **Data shapes**: key types, schemas, or interfaces
+- **Notes**: constraints, gotchas, non-obvious design decisions
+
+### When you add or change an API endpoint
+
+Update `docs/api/` — one file per service/router. Document:
+- Method + path
+- Request body / query params
+- Response shape and status codes
+- Auth requirements
+
+### When you make a significant architectural decision
+
+Create `docs/decisions/ADR-<NNN>-<slug>.md`. Use this format:
+```
+# ADR-NNN: Title
+## Status: Proposed | Accepted | Deprecated
+## Context: why this decision was needed
+## Decision: what was decided
+## Consequences: trade-offs and implications
+```
+
+### When you modify `ARCHITECTURE.md`
+
+Keep the Module Map table current. If you add a new service, integration, or env variable, add it to the relevant section.
+
+### The Stop hook will warn you
+
+If you end the session with modified files and no doc update, the Stop hook prints a list of what needs attention. Clear the queue with `npx docutrack clear` only after documentation is updated.

package/templates/commands/adr-new.md

@@ -0,0 +1,58 @@
+---
+description: Create a new Architecture Decision Record (ADR) interactively
+allowed-tools: Read, Write, Bash
+---
+
+Guide the user through creating a new Architecture Decision Record.
+
+**Step 1 — Find the next ADR number**
+List files in `docs/decisions/`. Find the highest `ADR-NNN` number and increment by 1. If none exist, start at 001.
+
+**Step 2 — Ask for the decision title**
+Say: "What is the title of this architectural decision? (e.g., 'Use PostgreSQL for primary storage')"
+
+Wait for the user's response.
+
+**Step 3 — Ask for context**
+Say: "What problem or situation made this decision necessary?"
+
+Wait for the user's response.
+
+**Step 4 — Ask for the decision**
+Say: "What was decided? Be specific."
+
+Wait for the user's response.
+
+**Step 5 — Ask for consequences**
+Say: "What are the trade-offs, implications, or things to watch for as a result of this decision?"
+
+Wait for the user's response.
+
+**Step 6 — Create the ADR file**
+
+Create the file at `docs/decisions/ADR-<NNN>-<slug>.md` where:
+- `<NNN>` is zero-padded to 3 digits (e.g., 001, 012, 123)
+- `<slug>` is the title lowercased with spaces replaced by hyphens, max 40 chars
+
+File content:
+```markdown
+# ADR-<NNN>: <Title>
+
+**Status**: Accepted  
+**Date**: <today's date as YYYY-MM-DD>
+
+## Context
+
+<User's context answer>
+
+## Decision
+
+<User's decision answer>
+
+## Consequences
+
+<User's consequences answer>
+```
+
+After creating the file, say:
+"Created `docs/decisions/ADR-<NNN>-<slug>.md`. The ADR is now part of your living documentation and will appear in DocuTrack's Decisions section."

package/templates/commands/arch-review.md

@@ -0,0 +1,59 @@
+---
+description: Audit documentation coverage and surface stale, missing, or low-quality docs
+allowed-tools: Read, Bash
+---
+
+Run a documentation coverage audit. Follow these steps:
+
+**Step 1 — Collect source files**
+Run: `find src -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" 2>/dev/null | grep -v node_modules | grep -v ".test." | grep -v ".spec." | head -100`
+
+If `src/` doesn't exist, try `lib/`, `app/`, or `pkg/`.
+
+**Step 2 — Collect documented modules**
+List all `.md` files in `docs/modules/`.
+
+**Step 3 — Read the queue**
+Read `.docutrack/queue.json` to see files waiting for documentation.
+
+**Step 4 — Read module docs**
+For each doc in `docs/modules/`, check:
+- Does it have a non-empty **Responsibility** line?
+- Does it have a **Public API** section with at least one entry?
+- Does it have a **Dependencies** section?
+
+Flag any doc that is missing these sections as "incomplete".
+
+**Step 5 — Output the report**
+
+```
+DocuTrack Coverage Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Score: <N>%  (<documented>/<total> source files)
+
+✓  DOCUMENTED (<N>)
+   <module>.md  ──  <responsibility in one sentence>
+
+✗  MISSING DOCS (<N>)
+   <file path>  ──  no documentation found
+
+⚠  INCOMPLETE DOCS (<N>)
+   <module>.md  ──  missing: <what's missing>
+
+⏱  PENDING IN QUEUE (<N>)
+   <file path>  ──  added <relative time>
+
+RECOMMENDATIONS
+  1. <highest priority action>
+  2. <second priority action>
+  3. <third priority action>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Rules for scoring:
+- Score = (documented source files) / (total source files) × 100
+- A source file is "documented" if a `docs/modules/<name>.md` exists for it (matching by basename without extension)
+- Round to nearest integer
+- Score ≥ 80: ✓ healthy  |  50–79: ⚠ needs work  |  < 50: ✗ critical
+
+After the report, ask: "Want me to write the missing documentation now?"

package/templates/commands/ask-docs.md

@@ -0,0 +1,26 @@
+---
+name: ask-docs
+description: Ask a question about this codebase using the accumulated documentation.
+---
+
+Answer the question: $ARGUMENTS
+
+To answer, read and synthesize the following documentation sources:
+
+1. `ARCHITECTURE.md` — system overview, module map, integrations, env variables
+2. `docs/modules/` — all module docs (responsibility, public API, dependencies, data shapes)
+3. `docs/api/openapi.json` — API spec (endpoints, parameters, request/response shapes)
+4. `docs/decisions/` — ADRs explaining why things are the way they are
+5. `.docutrack/queue.json` — pending files (what's being actively worked on)
+
+**How to answer:**
+- Be direct and specific — reference exact module names, function names, and file paths
+- If the answer spans multiple modules, explain the interaction clearly
+- If documentation doesn't cover the question, say what IS documented and suggest where to look in the source
+- For API questions, quote the exact endpoint path and method
+- For architecture questions, reference the ADR if one exists
+
+**Format:**
+- Lead with a one-sentence direct answer
+- Follow with supporting detail from the docs
+- End with the most relevant file path(s) to read next if the user wants more depth

package/templates/commands/doc-map.md

@@ -0,0 +1,50 @@
+---
+description: Render a live map of the system — modules, API surface, integrations, and doc coverage
+allowed-tools: Read, Bash
+---
+
+Read the following files (skip gracefully if any don't exist):
+1. `ARCHITECTURE.md`
+2. All `.md` files in `docs/modules/`
+3. `docs/api/openapi.json`
+4. `.docutrack/queue.json`
+
+Then output a formatted system map in this exact structure:
+
+```
+╔══════════════════════════════════════════════════════╗
+║  System Map — <project name>                        ║
+╚══════════════════════════════════════════════════════╝
+
+OVERVIEW
+  <one-sentence system description from ARCHITECTURE.md>
+
+MODULES  (<N> documented)
+  ├── <module>  —  <responsibility>
+  ├── <module>  —  <responsibility>
+  └── <module>  —  <responsibility>
+
+API SURFACE  (<N> endpoints)
+  GET    /path/one   [tag]
+  POST   /path/two   [tag]
+  ...
+
+INTEGRATIONS
+  <service> — <purpose>
+  ...
+
+COVERAGE
+  Documented  : <N> modules
+  Pending     : <N> files need documentation
+  Score       : <N>%  [▓▓▓▓▓▓░░░░]
+
+PENDING DOCUMENTATION
+  - <file>  (added <timestamp>)
+```
+
+Rules:
+- Keep module names short — use the file basename without extension
+- Show at most 20 API endpoints; if more exist, show the first 20 and append `  ... and N more`
+- For the coverage bar, use ▓ for covered and ░ for uncovered (10 chars total)
+- If a section has no data (no modules, no API, etc.), write `  (none yet)` under it
+- Do not include markdown formatting — output plain text only

package/templates/docutrack.config.json

@@ -0,0 +1,13 @@
+{
+  "template": "express",
+  "minCoverage": 80,
+  "ignore": [
+    "**/*.test.js",
+    "**/*.spec.js",
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "src/migrations",
+    "src/seeds",
+    "src/__generated__"
+  ]
+}

package/templates/github/workflows/docutrack-docs.yml

@@ -0,0 +1,42 @@
+name: Deploy DocuTrack Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'ARCHITECTURE.md'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Build docs site
+        run: npx docutrack build --out ./dist
+
+      - uses: actions/configure-pages@v4
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./dist
+
+      - id: deploy
+        uses: actions/deploy-pages@v4

package/templates/github/workflows/docutrack-gate.yml

@@ -0,0 +1,31 @@
+name: DocuTrack Coverage Gate
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  coverage-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Check documentation coverage
+        run: |
+          STATUS=$(npx docutrack status --json 2>/dev/null || echo '{"coverage":0}')
+          COVERAGE=$(echo $STATUS | node -e 'process.stdin.on("data",d=>process.stdout.write(""+JSON.parse(d).coverage))')
+          MIN=$(node -e "try{const c=require('./docutrack.config.json');process.stdout.write(''+c.minCoverage)}catch{process.stdout.write('80')}")
+
+          echo "Coverage: ${COVERAGE}%  (minimum: ${MIN}%)"
+
+          if [ "$COVERAGE" -lt "$MIN" ]; then
+            echo "::error::Documentation coverage ${COVERAGE}% is below the minimum ${MIN}%."
+            echo "::error::Run /arch-review in your Claude Code session to generate missing docs."
+            exit 1
+          fi
+
+          echo "::notice::Documentation coverage ${COVERAGE}% meets the minimum ${MIN}%."

package/templates/github/workflows/docutrack-pr.yml

@@ -0,0 +1,93 @@
+name: DocuTrack PR Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  doc-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Get doc coverage
+        id: coverage
+        run: |
+          STATUS=$(npx docutrack status --json 2>/dev/null || echo '{"coverage":0,"pending":0,"staleCount":0,"docCount":0}')
+          echo "json=$STATUS" >> $GITHUB_OUTPUT
+          echo "coverage=$(echo $STATUS | node -e 'process.stdin.on("data",d=>process.stdout.write(JSON.parse(d).coverage+"%"))')" >> $GITHUB_OUTPUT
+
+      - name: Get changed doc files
+        id: changed
+        run: |
+          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- 'docs/**' 'ARCHITECTURE.md' | head -20)
+          echo "files<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGED" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Post PR comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const status = JSON.parse('${{ steps.coverage.outputs.json }}')
+            const changedFiles = `${{ steps.changed.outputs.files }}`.trim()
+            const files = changedFiles ? changedFiles.split('\n').filter(Boolean) : []
+
+            const scoreEmoji = status.coverage >= 80 ? '✅' : status.coverage >= 50 ? '⚠️' : '❌'
+            const docLines = files.length
+              ? files.map(f => `  - \`${f}\``).join('\n')
+              : '  _No documentation changes in this PR_'
+
+            const body = [
+              '## 📋 DocuTrack Documentation Report',
+              '',
+              `| Metric | Value |`,
+              `|--------|-------|`,
+              `| Coverage | ${scoreEmoji} **${status.coverage}%** |`,
+              `| Doc files | ${status.docCount} |`,
+              `| Pending (undocumented) | ${status.pending} |`,
+              `| Stale docs | ${status.staleCount} |`,
+              '',
+              '### Documentation changes in this PR',
+              docLines,
+              '',
+              status.pending > 0
+                ? `> ⚠️ **${status.pending} file(s) were modified without documentation updates.** Consider running \`/arch-review\` to address them.`
+                : '> ✅ All modified files have documentation.',
+              '',
+              '<sub>Generated by [DocuTrack](https://github.com/your-org/docutrack)</sub>',
+            ].join('\n')
+
+            // Update existing comment if present, otherwise create new one
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            })
+            const existing = comments.find(c => c.body.includes('DocuTrack Documentation Report'))
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              })
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              })
+            }

package/templates/hooks/on-stop.js

@@ -0,0 +1,39 @@
+'use strict'
+
+// Stop hook — fires when the Claude Code session ends
+// Warns if there are files modified without documentation updates
+
+const fs = require('fs')
+const path = require('path')
+
+const QUEUE_PATH = path.join('.docutrack', 'queue.json')
+
+if (!fs.existsSync(QUEUE_PATH)) process.exit(0)
+
+let queue
+try {
+  queue = JSON.parse(fs.readFileSync(QUEUE_PATH, 'utf8'))
+} catch {
+  process.exit(0)
+}
+
+if (!queue.pending || queue.pending.length === 0) process.exit(0)
+
+const count = queue.pending.length
+const files = queue.pending.map(e => `  - ${e.file}`).join('\n')
+
+console.log(`
+╔════════════════════════════════════════════════════╗
+║  DocuTrack: ${String(count).padEnd(3)} file(s) need documentation     ║
+╚════════════════════════════════════════════════════╝
+
+${files}
+
+To update the docs, tell the agent:
+  "Update the documentation for the files in .docutrack/queue.json"
+
+To clear the queue manually:
+  npx docutrack clear
+`)
+
+process.exit(0)

package/templates/hooks/post-tool-use.js

@@ -0,0 +1,52 @@
+'use strict'
+
+// PostToolUse hook — fires after every Write, Edit, or MultiEdit
+// Adds the modified file to .docutrack/queue.json
+
+const fs = require('fs')
+const path = require('path')
+
+let raw = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', chunk => { raw += chunk })
+process.stdin.on('end', () => {
+  try {
+    const event = JSON.parse(raw)
+    const filePath = extractFilePath(event)
+    if (filePath) addToQueue(filePath)
+  } catch {
+    // Never crash the agent session over a hook error
+  }
+  process.exit(0)
+})
+
+function extractFilePath(event) {
+  const { tool_name, tool_input } = event
+  if (!tool_input) return null
+
+  if (tool_name === 'Write' || tool_name === 'Edit' || tool_name === 'MultiEdit') {
+    return tool_input.file_path || null
+  }
+  return null
+}
+
+function addToQueue(filePath) {
+  const normalized = filePath.replace(/\\/g, '/')
+  const ignored = [
+    'docs/', '.docutrack/', '.claude/', 'node_modules/', '.git/',
+  ]
+  if (ignored.some(p => normalized.startsWith(p))) return
+
+  const queuePath = path.join('.docutrack', 'queue.json')
+  if (!fs.existsSync(path.dirname(queuePath))) return // not initialized
+
+  let queue = { pending: [], lastClear: null }
+  try {
+    queue = JSON.parse(fs.readFileSync(queuePath, 'utf8'))
+  } catch { /* start fresh */ }
+
+  if (queue.pending.some(e => e.file === normalized)) return
+
+  queue.pending.push({ file: normalized, addedAt: new Date().toISOString() })
+  fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2))
+}