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

Commit ea7214a

Browse files
HerbHallclaude
HerbHall
and
claude
committed
feat: add project template files for Kit 3 scaffolding (issue #18)
- concept-brief.md: project vision capture template with substitution tokens - claude-md-template.md: fallback CLAUDE.md for new projects - github-labels.json: standard 13-label set for new repos Closes #18 Co-Authored-By: Claude <noreply@anthropic.com>
1 parent a48e0f0 commit ea7214a

4 files changed

Lines changed: 282 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@
3232
- `setup/bootstrap.ps1` phases 5-6: AI layer deploy (Claude Code npm install, skills/rules/agents/hooks with hash-based overwrite, CLAUDE.md placeholder substitution) and full verification table with next steps
3333
- `docs/BOOTSTRAP.md`: step-by-step new machine setup guide with troubleshooting section
3434
- `setup/lib/profiles.ps1`: profile format parser with YAML frontmatter, dependency resolution, and cycle detection
35+
- `project-templates/concept-brief.md`: project vision capture template for Kit 3 scaffolding
36+
- `project-templates/claude-md-template.md`: fallback CLAUDE.md template for new projects
37+
- `project-templates/github-labels.json`: standard label set (13 labels) for new GitHub repos
3538

3639
### Changed
3740

‎project-templates/claude-md-template.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# {{PROJECT_NAME}} - Development Guide
2+
3+
**Project scope:** {{PROJECT_DESCRIPTION}}
4+
5+
**Created:** 2026-02-21 · **Profile:** {{PROFILE}} · **Workspace:** {{DEVSPACE}}
6+
7+
**This file is your project's development handbook.** It contains build commands, test strategies, architecture notes, and workflow conventions specific to {{PROJECT_NAME}}.
8+
9+
## Quick Start
10+
11+
```bash
12+
# Install dependencies
13+
make install
14+
15+
# Build and test
16+
make build
17+
make test
18+
19+
# Run the project
20+
make run
21+
```
22+
23+
See `Makefile` or `justfile` in the project root for all available commands.
24+
25+
## Project Structure
26+
27+
```text
28+
{{PROJECT_NAME}}/
29+
├── README.md # Public-facing project overview
30+
├── CLAUDE.md # This file — development guide for AI agents
31+
├── Makefile # Build and development tasks
32+
│
33+
├── src/ # Source code
34+
│ └── main.{{PROFILE_EXT}}
35+
│
36+
├── tests/ # Test suite
37+
│ └── *_test.{{PROFILE_EXT}}
38+
│
39+
├── docs/ # Architecture and design docs
40+
│ ├── ARCHITECTURE.md # System design and components
41+
│ ├── decisions.md # Architecture decision records (ADRs)
42+
│ └── decisions/ # Individual ADRs
43+
│
44+
└── .github/workflows/ # CI/CD pipelines
45+
└── test.yml # Automated tests on push
46+
```
47+
48+
Replace {{PROFILE_EXT}} with appropriate extension (go, ts, rs, etc. based on profile).
49+
50+
## Tech Stack
51+
52+
**Language:** {{PROFILE}} profile
53+
**Build tool:** Makefile
54+
**Testing:** [match to profile]
55+
**CI/CD:** GitHub Actions
56+
57+
See `.github/workflows/` for automated checks that run on each push.
58+
59+
## Development Workflow
60+
61+
### Branch Strategy
62+
63+
- **Never commit directly to main**
64+
- Create feature branch: `git checkout -b feature/issue-NNN-description`
65+
- Commit using conventional format: `feat: ...`, `fix: ...`, `docs: ...`
66+
- Include co-author tag in all commits:
67+
68+
```bash
69+
git commit -m "feat: add X
70+
71+
Co-Authored-By: Claude <noreply@anthropic.com>"
72+
```
73+
74+
- Push branch and create PR via `gh pr create`
75+
- Merge only after CI passes
76+
77+
### Testing Before Push
78+
79+
```bash
80+
# Build and test locally
81+
make build
82+
make test
83+
84+
# For Go projects: race detection
85+
go test -race ./...
86+
87+
# For all projects: lint
88+
make lint
89+
```
90+
91+
Fix all failures before pushing. CI should only confirm what you've already verified locally.
92+
93+
### Code Review
94+
95+
1. Push to feature branch
96+
2. Create PR with `gh pr create`
97+
3. Wait for CI to pass (GitHub Actions)
98+
4. Merge via GitHub UI (`gh pr merge <number> --merge`)
99+
100+
## Conventions
101+
102+
### Commit Message Format
103+
104+
```text
105+
feat: add user authentication
106+
^--- type: one of feat, fix, refactor, docs, test, chore
107+
108+
Brief description (50 chars or less)
109+
110+
Longer explanation of the change and why it was made.
111+
112+
Co-Authored-By: Claude <noreply@anthropic.com>
113+
```
114+
115+
**Types:**
116+
117+
- `feat:` new feature or enhancement
118+
- `fix:` bug fix
119+
- `refactor:` code restructuring (no behavior change)
120+
- `docs:` documentation only
121+
- `test:` test addition or modification
122+
- `chore:` tooling, CI, dependencies, etc.
123+
124+
### Code Style
125+
126+
- Follow the language's idioms (Go conventions for Go, Python PEP 8, etc.)
127+
- Comments only where logic isn't self-evident
128+
- Watch for security issues: input validation, SQL injection, XSS, command injection
129+
- Validate only at system boundaries (user input, external APIs)
130+
131+
### File Naming
132+
133+
- Use snake_case for files and directories
134+
- Use PascalCase for type/class names
135+
- Use camelCase for functions and variables
136+
137+
## Known Constraints
138+
139+
<!-- Fill these in as you discover them -->
140+
141+
- [Constraint 1]
142+
- [Constraint 2]
143+
144+
## Debugging Tips
145+
146+
### When Tests Fail
147+
148+
1. Run the failing test in isolation: `make test TEST=TestName`
149+
2. Add logging or breakpoints
150+
3. Check git diff to understand what changed
151+
4. Search for related issues on GitHub
152+
153+
### When CI Fails
154+
155+
1. Check the GitHub Actions logs (link in PR)
156+
2. Run the failing job locally if possible
157+
3. Common issues: missing dependencies, platform-specific bugs, lint errors
158+
4. Push fix and re-run CI with `gh run rerun <run-id>`
159+
160+
## References
161+
162+
- **Architecture:** See `docs/ARCHITECTURE.md` for system design
163+
- **Decisions:** See `docs/decisions.md` for ADRs and design rationale
164+
- **Global conventions:** See `~/.claude/CLAUDE.md` for workspace-wide standards
165+
166+
---
167+
168+
**Note:** This template was generated from `devkit/project-templates/claude-md-template.md`. Update it as the project evolves.

‎project-templates/concept-brief.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Project Concept Brief
2+
3+
**Available tokens for substitution in Kit 3 scaffolding:**
4+
5+
- `{{PROJECT_NAME}}` -- the project's canonical name
6+
- `{{PROJECT_DESCRIPTION}}` -- one-sentence problem statement
7+
- `{{AUTHOR}}` -- creator's name
8+
- `{{DEVSPACE}}` -- path to development workspace
9+
- `{{MACHINE}}` -- development machine identifier
10+
- `{{PROFILE}}` -- selected tech stack profile (e.g., "go-rest-api", "react-spa")
11+
12+
Fill this out BEFORE running Kit 3 scaffolding. Your answers drive template population and architecture decisions.
13+
14+
## What is this project?
15+
16+
<!-- One sentence description. Examples: "CLI tool for ...", "REST API that ...", "React dashboard for ..." -->
17+
18+
## What problem does it solve?
19+
20+
<!-- Who has this problem? What pain does it cause them? What happens without this solution? -->
21+
22+
## What does it do? (core behavior)
23+
24+
<!-- List the 2-3 most important things it must do. Be specific. Examples: "Accept SSH connections and tunnel traffic", "Provide live search across N million documents", "Sync configuration from git to Kubernetes cluster" -->
25+
26+
1.
27+
2.
28+
3.
29+
30+
## What does it NOT do? (explicit scope boundary)
31+
32+
<!-- What should be left out? What is explicitly out of scope? Examples: "Not a multi-tenant platform", "No persistence layer (stateless)", "Supports Linux only, not Windows" -->
33+
34+
## Tech stack hints
35+
36+
<!-- Optional but helpful: suggest the target environment. Examples: "Go CLI that runs on macOS/Linux", "Node.js backend + React frontend", "Kubernetes-native operator" -->
37+
38+
## Success looks like
39+
40+
<!-- How will you know it's working? What's the end state? What does the user get? Examples: "Bandwidth savings of 50% compared to manual config", "Deploy new services in under 5 minutes", "0 data loss on power failure" -->
41+
42+
---
43+
44+
**Next step:** Share this brief with your AI agent before running scaffolding. The answers become part of the project's `CLAUDE.md` and architecture decisions.

‎project-templates/github-labels.json‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
[
2+
{
3+
"name": "feat",
4+
"color": "0075ca",
5+
"description": "New feature or enhancement"
6+
},
7+
{
8+
"name": "fix",
9+
"color": "d73a4a",
10+
"description": "Bug fix"
11+
},
12+
{
13+
"name": "chore",
14+
"color": "e4e669",
15+
"description": "Maintenance, refactor, tooling, dependencies"
16+
},
17+
{
18+
"name": "docs",
19+
"color": "0075ca",
20+
"description": "Documentation"
21+
},
22+
{
23+
"name": "test",
24+
"color": "bfd4f2",
25+
"description": "Tests and test infrastructure"
26+
},
27+
{
28+
"name": "phase-1",
29+
"color": "a2eeef",
30+
"description": "Phase 1 work"
31+
},
32+
{
33+
"name": "phase-2",
34+
"color": "a2eeef",
35+
"description": "Phase 2 work"
36+
},
37+
{
38+
"name": "phase-3",
39+
"color": "a2eeef",
40+
"description": "Phase 3 work"
41+
},
42+
{
43+
"name": "phase-4",
44+
"color": "a2eeef",
45+
"description": "Phase 4 work"
46+
},
47+
{
48+
"name": "blocked",
49+
"color": "b60205",
50+
"description": "Waiting on something external or internal"
51+
},
52+
{
53+
"name": "question",
54+
"color": "d876e3",
55+
"description": "Needs clarification, decision, or design review"
56+
},
57+
{
58+
"name": "good-first-issue",
59+
"color": "7057ff",
60+
"description": "Good for newcomers to the project"
61+
},
62+
{
63+
"name": "help-wanted",
64+
"color": "33aa3f",
65+
"description": "Actively seeking contributions"
66+
}
67+
]

0 commit comments

Comments
 (0)