Skip to content
This repository was archived by the owner on Apr 5, 2026. It is now read-only.

Commit 250da30

Browse files
HerbHallHerbHall
committed
docs: update CLAUDE.md for three-kit architecture and implementation handoff
1 parent 5fcfb9d commit 250da30

1 file changed

Lines changed: 192 additions & 104 deletions

File tree

‎CLAUDE.md‎

Lines changed: 192 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,192 @@
1-
# devkit
2-
3-
Personal development methodology and Claude Code configuration, packaged as a portable toolkit.
4-
5-
## Quick Start
6-
7-
```bash
8-
# Check prerequisites
9-
bash setup/install-tools.sh
10-
11-
# Install everything to ~/.claude/
12-
bash setup/setup.sh
13-
14-
# Verify installation
15-
bash setup/verify.sh
16-
```
17-
18-
## Project Structure
19-
20-
```text
21-
devkit/
22-
├── claude/ - Claude Code config (rules, skills, agents, hooks)
23-
│ ├── CLAUDE.md - Global instructions (installed to ~/.claude/)
24-
│ ├── rules/ - Auto-loaded pattern files (5 files, 70+ patterns)
25-
│ ├── skills/ - Invokable skills (9 skills with workflow files)
26-
│ ├── agents/ - Agent templates (6 agents)
27-
│ └── hooks/ - SessionStart hook
28-
├── devspace/ - Workspace shared configs
29-
│ ├── CLAUDE.md - Workspace CLAUDE.md template
30-
│ ├── templates/ - Project starter templates (ADR, design, test plan)
31-
│ └── shared-vscode/ - VS Code setting fragments
32-
├── mcp/ - MCP server inventory and config templates
33-
├── setup/ - Install, setup, and verify scripts
34-
├── METHODOLOGY.md - 6-phase development process
35-
└── CHANGELOG.md - Version history
36-
```
37-
38-
## Code Style
39-
40-
- All documentation follows markdownlint rules (see `devspace/.markdownlint.json`)
41-
- Shell scripts use `#!/usr/bin/env bash` with `set -euo pipefail`
42-
- JSON templates must be valid JSON (verify with `python -c "import json; json.load(open('file'))"`)
43-
- Skill SKILL.md files follow Claude Code skill format (YAML frontmatter + routing table)
44-
- Placeholders use `UPPERCASE_WITH_UNDERSCORES` (not angle brackets, which trigger MD033)
45-
46-
## Project Gotchas
47-
48-
**IMPORTANT**:
49-
50-
- `claude/CLAUDE.md` is the *global* config installed to `~/.claude/CLAUDE.md` — it is NOT this project's config
51-
- `devspace/CLAUDE.md` is a *template* for workspace roots — not used directly by this project
52-
- Skill workflow files referenced in SKILL.md routing tables must exist on disk (CI validates this)
53-
- `settings.template.json` must be valid JSON — easy to break with missing commas
54-
- Rules files (`claude/rules/*.md`) are loaded into Claude Code's system prompt every session — keep them concise
55-
56-
## Key Dependencies
57-
58-
- `bash` - Setup and hook scripts
59-
- `git` - Version control
60-
- `node` / `npm` - Required for Claude Code itself
61-
- `gh` - GitHub CLI for issue/PR operations in skills
62-
- `markdownlint-cli2` - Markdown linting (CI and local)
63-
64-
## Testing
65-
66-
```bash
67-
# Validate JSON templates
68-
python -c "import json; json.load(open('claude/settings.template.json'))"
69-
70-
# Check for stale skill routing (all referenced workflows exist)
71-
# Automated in CI: .github/workflows/lint.yml
72-
73-
# Lint all markdown
74-
npx markdownlint-cli2 "**/*.md"
75-
76-
# Verify no hardcoded user-specific paths leaked in
77-
grep -r "HerbHall\|SubNetree\|D:\\\\DevSpace" claude/ devspace/ mcp/ setup/
78-
```
79-
80-
## Common Tasks
81-
82-
**Add a new skill:**
83-
84-
1. Create `claude/skills/{name}/SKILL.md` with YAML frontmatter
85-
2. Create `claude/skills/{name}/workflows/*.md` for each routing target
86-
3. Update `setup/verify.sh` to include the new skill name
87-
4. Update `README.md` skills table
88-
89-
**Add a new rule pattern:**
90-
91-
1. Edit the appropriate file in `claude/rules/` (patterns, gotchas, etc.)
92-
2. Keep entries numbered sequentially
93-
3. Include: category, context, fix, and example
94-
95-
**Sync from a workstation:**
96-
97-
```bash
98-
cp ~/.claude/rules/*.md claude/rules/
99-
cp -r ~/.claude/skills/new-skill claude/skills/
100-
```
101-
102-
---
103-
104-
**Note**: Add personal preferences to `CLAUDE.local.md` (gitignored) instead of this file.
1+
# devkit
2+
3+
Windows AI development platform — packages machine bootstrap, stack profiles, and new project scaffolding into a three-kit PowerShell automation suite.
4+
5+
**Current state:** Architecture designed, all GitHub issues created (#3–#24), implementation not yet started. The existing files in `setup/` and `claude/` are the v1.0 bash-based system — they still work but are being superseded by the PowerShell three-kit system described below.
6+
7+
## What This Project Does
8+
9+
Three kits, one entry point (`setup.ps1`):
10+
11+
- **Kit 1 — Bootstrap** (`setup/bootstrap.ps1`): Gets a bare Windows machine dev-ready. Installs tools via winget, configures git, creates devspace directory, stores credentials in Windows Credential Manager, deploys Claude skills.
12+
- **Kit 2 — Stack** (`setup/stack.ps1`): Adds tooling for a specific project type using profile files in `profiles/`. Profiles are Markdown+YAML — machine-parseable frontmatter, Claude-readable body.
13+
- **Kit 3 — New Project** (`setup/new-project.ps1`): Collects a concept brief, scaffolds a GitHub repo with directory structure, generates a project CLAUDE.md via Claude Code (falls back to template if not authenticated).
14+
15+
## Target Directory Structure (not yet built)
16+
17+
```text
18+
devkit/
19+
├── setup.ps1 # Entry point menu — reads VERSION file
20+
├── VERSION # Single line semver, e.g. 1.1.0
21+
├── setup/
22+
│ ├── bootstrap.ps1 # Kit 1
23+
│ ├── stack.ps1 # Kit 2
24+
│ ├── new-project.ps1 # Kit 3
25+
│ ├── backup.ps1 # Refresh machine/ snapshots
26+
│ ├── verify.ps1 # Standalone pass/fail table
27+
│ └── lib/
28+
│ ├── ui.ps1 # Console output: Write-OK/Warn/Fail, menus, tables
29+
│ ├── checks.ps1 # Tool/feature detection: Test-Tool, Test-HyperV, etc.
30+
│ ├── install.ps1 # Winget wrappers: Install-WingetPackage, etc.
31+
│ └── credentials.ps1 # Windows Credential Manager: Set/Get/Test-DevkitCredential
32+
├── profiles/ # Kit 2 stack profiles (Markdown+YAML)
33+
│ ├── go-cli.md
34+
│ ├── go-web.md
35+
│ └── iot-embedded.md
36+
├── machine/ # Kit 1 snapshots (committed, refreshed by backup.ps1)
37+
│ ├── winget.json
38+
│ ├── vscode-extensions.txt
39+
│ ├── git-config.template
40+
│ └── manual-requirements.md
41+
├── project-templates/ # Kit 3 scaffolding templates
42+
│ ├── concept-brief.md
43+
│ ├── claude-md-template.md
44+
│ └── github-labels.json
45+
├── docs/
46+
│ ├── BOOTSTRAP.md
47+
│ ├── PROFILES.md
48+
│ └── DECISIONS.md # Design rationale — READ THIS before implementing
49+
├── claude/ # Claude Code config (unchanged from v1.0)
50+
│ ├── CLAUDE.md # Global instructions → installed to ~/.claude/CLAUDE.md
51+
│ ├── skills/ # Invokable skills
52+
│ ├── rules/ # Auto-loaded pattern files
53+
│ └── agents/
54+
└── setup/legacy/ # Original bash scripts (deprecated, not deleted)
55+
├── setup.sh
56+
├── install-tools.sh
57+
└── verify.sh
58+
```
59+
60+
## Implementation Status
61+
62+
| Phase | Issues | Status |
63+
|-------|--------|--------|
64+
| 1 — Infrastructure | #3–#8 | Not started — implement first |
65+
| 2 — Bootstrap | #9–#13 | Not started — depends on Phase 1 |
66+
| 3 — Profiles + Kit 2 | #14–#17 | Not started — depends on Phase 1 |
67+
| 4 — Kit 3 New Project | #18–#20 | Not started — depends on Phases 1–3 |
68+
| 5 — Fixes + CI | #21–#24 | Not started — #21–#23 are standalone, do these first |
69+
70+
**Start here:** Issues #21–#23 are standalone fixes to existing files, no dependencies. Good first work. Then Phase 1 (#3 repo structure, then #4–#7 lib functions in parallel, then #8 menu).
71+
72+
## PowerShell Conventions
73+
74+
All new code is PowerShell. Bash scripts in `setup/legacy/` are deprecated — do not add new bash.
75+
76+
```powershell
77+
# File header — every .ps1 file
78+
#Requires -Version 5.1
79+
Set-StrictMode -Version Latest
80+
$ErrorActionPreference = 'Stop'
81+
82+
# Dot-source lib dependencies at top of each script
83+
. "$PSScriptRoot\lib\ui.ps1"
84+
. "$PSScriptRoot\lib\checks.ps1"
85+
```
86+
87+
- Target **PowerShell 5.1** minimum (ships with Windows 10/11). Use PS7 features only if wrapped in a version check.
88+
- Functions follow `Verb-Noun` naming: `Install-WingetPackage`, `Test-Tool`, `Write-OK`
89+
- Functions return `@{ Success=$bool; ... }` objects rather than throwing on failure
90+
- Never use `Write-Host` directly — always go through `ui.ps1` functions
91+
- No external module dependencies in lib files. YAML frontmatter parsing is done with a custom minimal parser (see issue #14)
92+
- Credential names prefixed `devkit/` to avoid collision with system credentials
93+
94+
## Profile Format (Kit 2)
95+
96+
Profiles are Markdown files with YAML frontmatter. The frontmatter is parsed by PowerShell; the body is passed to Claude as context.
97+
98+
```markdown
99+
---
100+
name: go-cli
101+
version: 1.0
102+
description: Go CLI tools — no HTTP, no web server
103+
requires: []
104+
winget:
105+
- id: GoLang.Go
106+
check: "go version"
107+
manual:
108+
- id: golangci-lint
109+
install: "go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest"
110+
check: "golangci-lint --version"
111+
vscode-extensions:
112+
- golang.go
113+
claude-skills:
114+
- go-development
115+
---
116+
117+
# Go CLI Profile
118+
119+
Body content here — used by Claude as project context.
120+
```
121+
122+
Parser lives in `setup/lib/` as part of the profile system (issue #14). No external YAML module.
123+
124+
## Template Tokens
125+
126+
Both `claude/CLAUDE.md` (global) and `project-templates/claude-md-template.md` use `{{TOKEN}}` placeholders substituted by `bootstrap.ps1` and `new-project.ps1`:
127+
128+
| Token | Source |
129+
|-------|--------|
130+
| `{{USERNAME}}` | `$env:USERNAME` |
131+
| `{{PLATFORM}}` | WMI OS caption |
132+
| `{{DEVSPACE}}` | `~/.devkit-config.json` |
133+
| `{{MACHINE}}` | `$env:COMPUTERNAME` |
134+
| `{{PROJECT_NAME}}` | Kit 3 Step 1 input |
135+
| `{{PROJECT_DESCRIPTION}}` | Concept brief first sentence |
136+
| `{{PROFILE}}` | Selected profile name |
137+
138+
## Critical Gotchas
139+
140+
- `claude/CLAUDE.md` is the **global** config installed to `~/.claude/CLAUDE.md` — it is NOT this project's CLAUDE.md. Do not confuse these.
141+
- `devspace/CLAUDE.md` is a **template** for workspace roots — not used directly by this project.
142+
- The `YOUR_PLATFORM` placeholder in `claude/CLAUDE.md` is a known bug — tracked in issue #21.
143+
- `METHODOLOGY.md` recommends BMAD which hangs on Windows — issue #21 adds a warning.
144+
- `claude/skills/go-development/SKILL.md` contains Subnetree-specific content that doesn't belong here — issue #21.
145+
- `known-gotchas.md` has non-contiguous numbering — issue #21.
146+
- `AGENT-WORKFLOW-GUIDE.md` has Python pseudo-code for agent definitions — issue #22 replaces with correct `.claude/agents/*.md` format.
147+
- Skill SKILL.md files referenced in routing tables must exist on disk (CI validates).
148+
- `settings.template.json` must be valid JSON — easy to break with missing commas.
149+
- Rules files (`claude/rules/*.md`) are loaded every Claude Code session — keep them concise.
150+
- Placeholders use `{{DOUBLE_BRACES}}` for bootstrap substitution, `UPPERCASE_WITH_UNDERSCORES` for human-filled template stubs.
151+
152+
## Key Decisions
153+
154+
Design rationale for non-obvious choices is in `docs/DECISIONS.md`. Read it before making architectural choices. Key points:
155+
156+
- Profile format is Markdown+YAML frontmatter (not JSON/TOML) — machine-parseable and Claude-readable in one file
157+
- No external PowerShell modules in lib — minimal parser for the small YAML subset used
158+
- Kit 3 CLAUDE.md generation: Claude Code → graceful template fallback (not a hard requirement)
159+
- Secrets go to Windows Credential Manager via `cmdkey` + WinRT PasswordVault — never `.env` files
160+
- `setup.ps1` is a menu that dispatches to scripts; each kit script is also independently invokable
161+
- All phases planned as GitHub issues before any implementation (done — issues #3–#24 exist)
162+
163+
## Testing
164+
165+
```powershell
166+
# Lint all markdown
167+
npx markdownlint-cli2 "**/*.md"
168+
169+
# Validate JSON templates
170+
python -c "import json; json.load(open('claude/settings.template.json'))"
171+
172+
# Check for user-specific path leakage
173+
Select-String -Path "claude/**","devspace/**","setup/**" -Pattern "HerbHall|Subnetree|D:\\DevSpace" -Recurse
174+
175+
# After implementing: test a lib function
176+
. .\setup\lib\checks.ps1
177+
Test-Tool -Name "git" -Command "git --version"
178+
```
179+
180+
## Existing Files (v1.0 — do not delete)
181+
182+
```text
183+
setup/install-tools.sh -- bash prereq checker
184+
setup/setup.sh -- bash installer
185+
setup/verify.sh -- bash verifier
186+
claude/ -- all Claude config (skills, rules, agents, hooks) — unchanged
187+
METHODOLOGY.md -- 6-phase dev process (needs BMAD warning per issue #21)
188+
```
189+
190+
---
191+
192+
**Note:** Add personal machine overrides to `CLAUDE.local.md` (gitignored).

0 commit comments

Comments
 (0)