Skip to content

Commit c0b869a

Browse files
hi-leiclaude
hi-lei
and
claude
committed
feat: add auto-maintained per-subcommand knowledge docs
Add README.md (human-readable) and CLAUDE.md (AI-context) to each subcommand directory under cmd/*, auto-updated by a pre-commit hook that runs the new update-command-knowledge skill via headless Claude. - New skill: .ai/skills/update-command-knowledge.md - Pre-commit hook integration in githooks/pre-commit - Initial docs for all 8 command domains (auth, vm, volume, sshkey, startupscript, settings, version, update) - SKIP_DOC_UPDATE=1 escape hatch for bypassing Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent d10e094 commit c0b869a

21 files changed

Lines changed: 1353 additions & 2 deletions

File tree

‎.ai/skills/update-command-knowledge.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
name: update-command-knowledge
3+
description: Auto-detect changed subcommand dirs from staged git changes and regenerate their README.md + CLAUDE.md knowledge docs
4+
---
5+
6+
# Update Command Knowledge
7+
8+
This skill generates and updates per-subcommand knowledge docs (README.md + CLAUDE.md) in each `internal/verda-cli/cmd/*/` directory. It can be invoked headlessly via `claude -p "/update-command-knowledge"` or interactively via `/update-command-knowledge`.
9+
10+
## Step 1: Determine which command directories to process
11+
12+
If the argument contains `--all`, process ALL command directories:
13+
- auth, vm, sshkey, startupscript, volume, settings, version, update
14+
15+
Otherwise, detect changed dirs from staged files:
16+
17+
1. Run `git diff --cached --name-only` using the Bash tool
18+
2. From the output, extract unique directory names matching the pattern `internal/verda-cli/cmd/<dir>/` where `<dir>` is not `util`
19+
3. Exclude any matches that are just files in `internal/verda-cli/cmd/` itself (like `cmd.go`, `helper.go`) — only include actual subdirectories
20+
21+
If no directories are found, print exactly:
22+
> No command directories with staged changes. Nothing to update.
23+
24+
Then stop. Do not generate any files.
25+
26+
## Step 2: For each affected directory, read and analyze the source
27+
28+
For each directory `internal/verda-cli/cmd/<domain>/`:
29+
30+
1. Use the Glob tool to find all `*.go` files in the directory
31+
2. Use the Read tool to read every `.go` file found
32+
3. Analyze the code to extract:
33+
- **Parent command**: The `Use`, `Aliases`, and `Short` fields from the parent cobra command (usually in `<domain>.go`)
34+
- **Subcommands**: Each subcommand's `Use`, `Short`, `Long`, `Example`, and flags (from `cmd.Flags()` calls)
35+
- **API calls**: SDK client methods used (e.g., `client.VirtualMachines.List`, `client.SSHKeys.Create`)
36+
- **Business logic**: Pricing calculations, status mappings, validation rules, formatting
37+
- **Wizard flows**: If a `wizard.go` exists, document the steps, `clientFunc`, `apiCache` usage
38+
- **Interactive vs non-interactive**: Which flags allow non-interactive mode, what gets prompted when missing
39+
40+
Do NOT guess or infer — extract all information directly from the source code.
41+
42+
## Step 3: Generate README.md
43+
44+
For each directory, generate `internal/verda-cli/cmd/<domain>/README.md` using the Write tool.
45+
46+
If a README.md already exists in the directory, read it first with the Read tool before generating — you will need to preserve manually-added sections.
47+
48+
Follow this template:
49+
50+
```markdown
51+
# verda <domain> — <Short description from parent command>
52+
53+
## Commands
54+
55+
| Command | Description | Key Flags |
56+
|---------|-------------|-----------|
57+
| `verda <domain> <sub>` | Short desc | `--flag1`, `--flag2` |
58+
59+
## Usage Examples
60+
61+
### <Subcommand 1>
62+
\`\`\`bash
63+
# Interactive
64+
verda <domain> <sub>
65+
66+
# Non-interactive
67+
verda <domain> <sub> --flag value
68+
\`\`\`
69+
70+
(Repeat for each subcommand. Use the `Example` field from cobra commands when available.)
71+
72+
## Interactive vs Non-Interactive
73+
74+
Describe which flags enable non-interactive mode, what happens when flags are missing (prompts).
75+
76+
## Architecture Notes
77+
78+
- List key files and what each does
79+
- API endpoints/SDK methods used
80+
- Business logic (pricing, status mappings, etc.)
81+
- Wizard flows if applicable
82+
```
83+
84+
If the old README.md had manually-added sections titled "Gotchas" or "Notes", append them at the end of the newly generated content.
85+
86+
## Step 4: Generate CLAUDE.md
87+
88+
For each directory, generate `internal/verda-cli/cmd/<domain>/CLAUDE.md` using the Write tool.
89+
90+
If a CLAUDE.md already exists in the directory, read it first with the Read tool before generating — you will need to preserve manually-added gotchas.
91+
92+
Follow this template:
93+
94+
```markdown
95+
# <Domain> Command Knowledge
96+
97+
## Quick Reference
98+
- Parent: `verda <domain>` (aliases: <aliases or "none">)
99+
- Subcommands: <comma-separated list>
100+
- Files: list each .go file and a brief description of its role
101+
102+
## Domain-Specific Logic
103+
- Pricing calculations, status mappings, validation rules
104+
- Any non-obvious business rules extracted from the code
105+
106+
## Gotchas & Edge Cases
107+
- Things that aren't obvious from reading the code
108+
- Common mistakes when modifying this command
109+
110+
## Relationships
111+
- Dependencies on other packages (util, SDK types, wizard engine)
112+
- Shared state (apiCache, clientFunc patterns)
113+
```
114+
115+
If the old CLAUDE.md had manually-added items in the "Gotchas & Edge Cases" section, append them below any auto-detected gotchas (avoid exact duplicates).
116+
117+
## Step 5: Stage the updated docs
118+
119+
After all files are written, run a single `git add` command using the Bash tool to stage all the README.md and CLAUDE.md files that were created or updated. For example:
120+
121+
```bash
122+
git add internal/verda-cli/cmd/vm/README.md internal/verda-cli/cmd/vm/CLAUDE.md internal/verda-cli/cmd/sshkey/README.md internal/verda-cli/cmd/sshkey/CLAUDE.md
123+
```
124+
125+
## Important rules
126+
127+
- Use the Write tool to create/update doc files — do NOT use Bash (echo/cat) for file creation
128+
- Use Bash only for `git diff --cached --name-only` and `git add`
129+
- Read ALL .go files in a directory before generating docs — accuracy matters
130+
- If a directory has no .go files or no parent command definition, skip it and note why
131+
- Do not modify any .go source files — this skill only creates/updates README.md and CLAUDE.md
132+
- Do not create docs for `internal/verda-cli/cmd/util/` — always skip this directory

‎AGENTS.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,9 @@ This document provides instructions for AI coding agents (Claude Code, Codex, et
55
## Before You Start
66

77
1. Read `CLAUDE.md` for project overview, build commands, and architecture
8-
2. Read `.ai/skills/new-command.md` when creating or modifying CLI commands
9-
3. Run `go build ./...` and `go test ./...` to verify your changes compile and pass
8+
2. Read the `CLAUDE.md` in the specific subcommand directory you're working on (e.g., `cmd/vm/CLAUDE.md`)
9+
3. Read `.ai/skills/new-command.md` when creating or modifying CLI commands
10+
4. Run `go build ./...` and `go test ./...` to verify your changes compile and pass
1011

1112
## Skills
1213

@@ -15,6 +16,7 @@ Skills are structured guides in `.ai/skills/` that document patterns and checkli
1516
| Skill | When to Use |
1617
|-------|-------------|
1718
| [new-command.md](.ai/skills/new-command.md) | Adding a new subcommand or modifying an existing one |
19+
| [update-command-knowledge.md](.ai/skills/update-command-knowledge.md) | Auto-updating per-command README.md and CLAUDE.md docs |
1820

1921
## Key Rules
2022

‎CLAUDE.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,17 @@ go mod tidy # Sync dependencies
4343
- Instance `price_per_hour` from API is the TOTAL price (not per-GPU). Derive per-unit by dividing.
4444
- Volume pricing is `price_per_month_per_gb`. Hourly = `ceil(monthly_per_gb * size / 30 / 24 * 10000) / 10000`
4545

46+
## Per-Command Knowledge
47+
48+
Each subcommand directory has its own docs:
49+
- `README.md` — Human-readable: usage, examples, flags, architecture
50+
- `CLAUDE.md` — AI context: gotchas, domain logic, relationships
51+
52+
These are auto-maintained by a pre-commit hook. See `.ai/skills/update-command-knowledge.md`.
53+
54+
When modifying a command, the hook will auto-update its docs on commit.
55+
For manual update: `claude -p "/update-command-knowledge --all" --model sonnet --dangerously-skip-permissions`
56+
4657
## Credentials
4758

4859
- AWS-style INI file at `~/.verda/credentials` with `verda_` prefixed keys

0 commit comments

Comments
 (0)