Skip to content

Commit 0b1a802

Browse files
nolrmnolrm
committed
feat(commands): add doc-arch, doc-feature, doc-component slash commands (0.13.4)
 Three new stack-aware doc commands distributed via ck install — /doc-arch generates docs/architecture.md (Level 1), /doc-feature generates docs/features/<name>.md (Level 2), /doc-component generates a colocated <name>.md (Level 3). Wired into ClaudeIntegration, install.js, and update.js. Docs updated in README and contextkit-docs site.
1 parent e6ba17e commit 0b1a802

11 files changed

Lines changed: 456 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,9 @@ ContextKit installs reusable slash commands for supported platforms:
142142
| `/refactor` | Refactor code with safety checks |
143143
| `/test` | Generate comprehensive tests |
144144
| `/doc` | Add documentation |
145+
| `/doc-arch` | Generate architecture docs (`docs/architecture.md`) — stack-aware (Level 1) |
146+
| `/doc-feature` | Generate feature-level docs (`docs/features/<name>.md`) — stack-aware (Level 2) |
147+
| `/doc-component` | Generate component-level docs colocated with the target file — stack-aware (Level 3) |
145148
| `/spec` | Write a component spec (MD-first) before any code is created |
146149
| `/squad` | Kick off a squad task — one task or many (auto-detects batch mode). Pushes back with clarifying questions if the task is vague. |
147150
| `/squad-architect` | Design the technical plan from the PO spec |

‎__tests__/integrations/claude-integration.test.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ describe('ClaudeIntegration', () => {
7373
'analyze', 'review', 'fix', 'refactor', 'test', 'doc', 'spec',
7474
'squad', 'squad-architect', 'squad-dev', 'squad-test', 'squad-review',
7575
'squad-auto', 'squad-auto-parallel', 'squad-reset', 'squad-doc', 'ck',
76+
'doc-arch', 'doc-feature', 'doc-component',
7677
];
7778
for (const cmd of commands) {
7879
const filePath = `.claude/commands/${cmd}.md`;

‎commands/doc-arch.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Doc — Architecture (Level 1)
2+
3+
Generate or update the architecture-level documentation for this project (`docs/architecture.md`).
4+
5+
## What I'll Do
6+
7+
1. Detect the project stack by inspecting project files
8+
2. Scope to a PR diff (if a PR number is provided) or the current branch changes
9+
3. Identify architectural signals: new modules, service boundaries, data flows, key decisions
10+
4. Generate or update `docs/architecture.md` following the Level 1 documentation standard
11+
5. Tailor artifacts to the detected stack profile
12+
13+
## How to Use
14+
15+
```
16+
/doc-arch # from current branch diff
17+
/doc-arch 142 # from PR #142
18+
/doc-arch # after adding a new service or module
19+
```
20+
21+
## Stack Detection
22+
23+
Inspect the project root to determine the stack profile:
24+
25+
| Profile | Detected by |
26+
|---------|------------|
27+
| **frontend** | `package.json` with react / vue / angular / svelte / nextjs / nuxt dependency |
28+
| **backend-node** | `package.json` without a frontend framework |
29+
| **backend-typed** | `go.mod` (Go), `Cargo.toml` (Rust), `pom.xml` or `build.gradle` (Java) |
30+
| **scripting** | `requirements.txt` or `pyproject.toml` (Python), `Gemfile` (Ruby), `composer.json` (PHP) |
31+
| **generic** | None of the above |
32+
33+
## Output: `docs/architecture.md`
34+
35+
Create the directory if missing. If the file already exists, update in place — add or replace sections relevant to the current changes, preserve unrelated content.
36+
37+
### Structure to generate:
38+
39+
```markdown
40+
# Architecture
41+
42+
## Overview
43+
[1–3 sentence system description]
44+
45+
## Stack
46+
[detected stack and key dependencies]
47+
48+
## Directory Structure
49+
[annotated tree of key directories]
50+
51+
## Key Flows
52+
[prose + Mermaid diagrams]
53+
54+
## Architecture Decisions
55+
[notable decisions with rationale]
56+
57+
## External Dependencies
58+
[third-party services, APIs, databases]
59+
```
60+
61+
### Artifacts by stack profile:
62+
63+
**frontend**
64+
- Routes/pages overview (Next.js: `app/` or `pages/`; Vue/Nuxt: `pages/` or `router/`)
65+
- Component hierarchy diagram (Mermaid)
66+
- State management approach
67+
- API integration pattern
68+
69+
**backend-node**
70+
- Middleware chain diagram (Mermaid sequence)
71+
- API endpoint surface (routes, controllers)
72+
- Service/module boundaries
73+
- Data layer (DB, ORM, caching)
74+
75+
**backend-typed** (Go / Rust / Java)
76+
- Package/crate/module structure
77+
- Interface and struct boundaries
78+
- Service-to-service flows (gRPC, REST, message queues) — Mermaid sequence diagram
79+
- Concurrency model (if relevant)
80+
81+
**scripting** (Python / Ruby / PHP)
82+
- Module/package structure
83+
- Class and function surface
84+
- External integrations
85+
86+
**generic**
87+
- Directory structure only
88+
- High-level flow prose
89+
90+
## Standards Applied
91+
92+
- `.contextkit/standards/architecture.md` — 3-level documentation hierarchy

‎commands/doc-component.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Doc — Component (Level 3)
2+
3+
Generate or update component-level documentation colocated with the target file or directory.
4+
5+
## What I'll Do
6+
7+
1. Detect the project stack by inspecting project files
8+
2. Identify the target from the argument, or infer from current file context / recent changes
9+
3. Read the target file(s) to understand the public API, behavior, and edge cases
10+
4. Create or update a `<name>.md` file colocated next to the target
11+
5. Tailor content to the detected stack profile
12+
13+
## How to Use
14+
15+
```
16+
/doc-component # infer from current file
17+
/doc-component src/components/Button.tsx # target a specific file
18+
/doc-component lib/utils/parser.js # target a utility
19+
/doc-component internal/auth/ # target a directory (documents all files in it)
20+
```
21+
22+
## Stack Detection
23+
24+
Inspect the project root to determine the stack profile:
25+
26+
| Profile | Detected by |
27+
|---------|------------|
28+
| **frontend** | `package.json` with react / vue / angular / svelte / nextjs / nuxt dependency |
29+
| **backend-node** | `package.json` without a frontend framework |
30+
| **backend-typed** | `go.mod` (Go), `Cargo.toml` (Rust), `pom.xml` or `build.gradle` (Java) |
31+
| **scripting** | `requirements.txt` or `pyproject.toml` (Python), `Gemfile` (Ruby), `composer.json` (PHP) |
32+
| **generic** | None of the above |
33+
34+
## Output: `<target-name>.md` colocated with the target
35+
36+
If the target is `src/components/Button.tsx`, create `src/components/Button.md`.
37+
If the target is `internal/auth/`, create `internal/auth/README.md`.
38+
If the doc file already exists, update in place.
39+
40+
### Structure to generate:
41+
42+
```markdown
43+
# <ComponentName / ModuleName>
44+
45+
## Purpose
46+
[One sentence: what this does]
47+
48+
## API / Props
49+
[table or list of inputs, parameters, or exported symbols]
50+
51+
## Usage
52+
[code example(s)]
53+
54+
## Behavior & Edge Cases
55+
[non-obvious logic, error states, boundary conditions]
56+
57+
## Where It's Used
58+
[list of known consumers — files that import this]
59+
```
60+
61+
### Artifacts by stack profile:
62+
63+
**frontend** (React / Vue / Angular / Svelte)
64+
- Props table: name, type, required, default, description
65+
- Emits / events (Vue)
66+
- Slots (Vue/Svelte) or children patterns (React)
67+
- Usage code example with JSX/template
68+
- CSS/Tailwind class notes if relevant
69+
70+
**backend-node**
71+
- Exported function signatures
72+
- Parameters and return values
73+
- Middleware signature if applicable
74+
- Usage example
75+
76+
**backend-typed** (Go / Rust / Java)
77+
- Exported types, structs, interfaces, traits
78+
- Function/method signatures with types
79+
- Usage example in the target language
80+
81+
**scripting** (Python / Ruby / PHP)
82+
- Class/function signatures
83+
- Parameters with types (type hints if available)
84+
- Usage example
85+
86+
**generic**
87+
- Exported symbols and descriptions
88+
- Usage example if discernible
89+
90+
## Standards Applied
91+
92+
- `.contextkit/standards/architecture.md` — 3-level documentation hierarchy (Component Level)

‎commands/doc-feature.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Doc — Feature (Level 2)
2+
3+
Generate or update feature-level documentation for a specific feature, route, or domain area.
4+
5+
## What I'll Do
6+
7+
1. Detect the project stack by inspecting project files
8+
2. Identify the target feature from the argument, current branch name, or PR diff
9+
3. Determine the feature's boundaries — which files, routes, or modules it covers
10+
4. Generate or update `docs/features/<feature-name>.md` following the Level 2 documentation standard
11+
5. Tailor content to the detected stack profile
12+
13+
## How to Use
14+
15+
```
16+
/doc-feature # infer feature from current branch or recent changes
17+
/doc-feature 98 # infer feature from PR #98
18+
/doc-feature apps/billing # target a specific directory
19+
/doc-feature auth # target a named feature
20+
```
21+
22+
## Stack Detection
23+
24+
Inspect the project root to determine the stack profile:
25+
26+
| Profile | Detected by |
27+
|---------|------------|
28+
| **frontend** | `package.json` with react / vue / angular / svelte / nextjs / nuxt dependency |
29+
| **backend-node** | `package.json` without a frontend framework |
30+
| **backend-typed** | `go.mod` (Go), `Cargo.toml` (Rust), `pom.xml` or `build.gradle` (Java) |
31+
| **scripting** | `requirements.txt` or `pyproject.toml` (Python), `Gemfile` (Ruby), `composer.json` (PHP) |
32+
| **generic** | None of the above |
33+
34+
## Output: `docs/features/<feature-name>.md`
35+
36+
Create `docs/features/` if missing. If the file already exists, update in place — replace sections relevant to the current changes, preserve unrelated content.
37+
38+
### Structure to generate:
39+
40+
```markdown
41+
# Feature: <Name>
42+
43+
## Purpose
44+
[1–2 sentence description of what this feature does and why it exists]
45+
46+
## Scope
47+
[files, routes, or modules this feature covers]
48+
49+
## Key Components / Modules
50+
[list with one-line descriptions]
51+
52+
## Data & State
53+
[data models, API contracts, state management]
54+
55+
## User Flows
56+
[key paths through the feature — prose or Mermaid sequence]
57+
58+
## Dependencies
59+
[internal: other features/modules; external: APIs, services]
60+
61+
## Edge Cases & Gotchas
62+
[known non-obvious behaviors]
63+
```
64+
65+
### Artifacts by stack profile:
66+
67+
**frontend**
68+
- Route(s) this feature owns
69+
- Components used (with roles)
70+
- Hooks / context / stores
71+
- API calls and response shapes
72+
- Optional: layout sketch or Mermaid component tree
73+
74+
**backend-node**
75+
- HTTP routes / controllers
76+
- Service methods and their responsibilities
77+
- Middleware applied
78+
- DB queries / data access layer
79+
80+
**backend-typed** (Go / Rust / Java)
81+
- Package(s) / crate(s) / modules
82+
- Exported interfaces and types
83+
- Request/response contracts
84+
- Mermaid sequence diagram for the main flow
85+
86+
**scripting** (Python / Ruby / PHP)
87+
- Module/class structure
88+
- Public API surface
89+
- External calls
90+
91+
**generic**
92+
- File list with descriptions
93+
- Main flow prose
94+
95+
## Standards Applied
96+
97+
- `.contextkit/standards/architecture.md` — 3-level documentation hierarchy

0 commit comments

Comments
 (0)