Stats
Actions
Tags
From project-orchestration-skills
Bootstrap a new project at a chosen graduation tier (t0 minimum, t1 decision-tracked, t2 full pattern language) following AI-Assisted Project Orchestration best practices. Use when starting a new software project, promoting an existing project to a higher tier, or converting an existing project for AI-assisted development.
How this skill is triggered — by the user, by Claude, or both
Slash command
/project-orchestration-skills:bootstrap-projectThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Bootstrap a new project with foundational artifacts following AI-Assisted Project Orchestration best practices. Implements the **Tiered Bootstrap** pattern with three graduation tiers (t0/t1/t2) so that decision rationale is captured at decision-time and tier promotion is reformatting, not archaeology.
Bootstrap a new project with foundational artifacts following AI-Assisted Project Orchestration best practices. Implements the Tiered Bootstrap pattern with three graduation tiers (t0/t1/t2) so that decision rationale is captured at decision-time and tier promotion is reformatting, not archaeology.
Pattern Reference: See TIERED-BOOTSTRAP for the underlying pattern, including knowledge-preservation argument and the comparison with spec-driven development tools.
Before running this skill, gather from the user:
my-awesome-project)Why project category matters:
This skill implements the Tiered Bootstrap pattern. Each tier is a strict superset of the previous one. Pick the lowest tier that fits the project's current state — promotion is mechanical (reformat / reorganize), not archaeological.
| Project state | Recommended tier |
|---|---|
| Same-day exploration, weekend prototype | t0 |
| Multi-week solo project, expected to outlive prototype | t1 |
| Multi-contributor, professional, or upstream-OSS-bound | t2 (default) |
| Existing prototype with chat-only history | t0 immediately, then promote |
Promotion triggers:
Knowledge-preservation property: at every tier, decision rationale is captured at decision-time in durable, version-controlled artifacts (CLAUDE.md, conventional commits, ADRs). No tier requires recovering rationale from non-durable sources (chat logs, agent session memory).
| Phase | t0 | t1 | t2 |
|---|---|---|---|
| 1. Directory structure (Diátaxis) | — | — | yes |
| 2. Git initialization | yes (minimal) | yes | yes |
| 3. CLAUDE.md | yes | yes | yes |
| 4. CHANGELOG.md | — | yes | yes |
| 5. Roadmap | — | — | yes |
| 6. README.md | optional | yes | yes |
| 7. Audience-traced artifacts | — | — | yes (if registry) |
| 8. Invoke related skills | — | setup-adrs, setup-pre-commit | all |
At t0, only Phases 2 (minimal .gitignore) and 3 (CLAUDE.md) are required. README is optional. No docs/ tree, no ADR scaffolding, no changelog — those come with promotion to t1.
At t1, add Phase 4 (CHANGELOG) and invoke setup-adrs (creates ADR-0001/0002/0003) and setup-pre-commit. Still no Diátaxis tree or C4 model.
At t2, run all phases. This is the existing default behavior.
Create the Diátaxis documentation structure:
docs/
├── tutorials/ # Learning-oriented
│ └── .gitkeep
├── howto/ # Problem-oriented
│ └── .gitkeep
├── reference/ # Information-oriented
│ └── .gitkeep
├── explanation/ # Understanding-oriented
│ └── .gitkeep
├── adr/ # Architecture Decision Records
│ └── .gitkeep
├── architecture/ # Structurizr-specific docs (h2-first, for !docs directive)
│ └── .gitkeep
├── sprints/ # Sprint planning and tracking
│ └── .gitkeep
└── roadmap/ # Project roadmap and phase planning
└── .gitkeep
For BDD projects, also create:
features/ # or test/features/ depending on ecosystem
└── step_definitions/
git init# Secrets and credentials
.env
.env.*
!.env.example
.envrc
.envrc.local
*.pem
*.key
credentials.json
secrets.yaml
# Claude Code local files
CLAUDE.local.md
maindevelop branch from maindevelop as default working branchGenerate a project-specific CLAUDE.md with:
# [Project Name]
[Project description]
## Project Context
- **Category**: [Development/Infrastructure/Hybrid]
- **Type**: [library/application/service/infrastructure]
- **Stack**: [technology stack]
- **License**: [license]
- **Tier**: [t0 | t1 | t2]
## Project Tier
Current tier: **[t0 | t1 | t2]**
Tier-specific artifacts in this project:
- [list per current tier — e.g., "CLAUDE.md, conventional commits" at t0]
Promotion triggers being watched:
- [e.g., "t0 → t1 when first contributor joins" or "t1 → t2 when nearing v1.0"]
## Current Development Status
<!-- t2 only — at t0/t1, replace with a single "## Status" paragraph -->
- **Current Sprint**: Sprint 1 (see docs/sprints/sprint-0001-plan.md)
- **Sprint Goal**: [initial goal]
- **Status**: Not started
- **Next Milestone**: v0.1.0
## Foundational ADRs
Read these at the start of each AI session for complete context:
| ADR | Purpose | Summary |
|-----|---------|---------|
| [ADR-0001](docs/adr/0001-record-architecture-decisions.md) | HOW TO DECIDE | Decision methodology |
| [ADR-0002](docs/adr/0002-adopt-development-best-practices.md) | HOW TO DEVELOP | Development practices |
| [ADR-0003](docs/adr/0003-*.md) | WHAT TECH | Technology stack |
| [ADR-0004](docs/adr/0004-operations-best-practices.md) | HOW TO OPERATE | Operations practices (Infrastructure/Hybrid only) |
## Development Practices
This project follows [AI-Assisted Project Orchestration patterns](https://github.com/jrjsmrtn/ai-assisted-project-orchestration):
- **Testing**: [TDD/BDD approach based on project type]
- **Versioning**: Semantic versioning (0.x.x during development)
- **Git Workflow**: Gitflow (main, develop, feature/*, release/*, hotfix/*)
- **Documentation**: Diátaxis framework
- **Architecture**: C4 DSL models in architecture/
## Quick Commands
```bash
# Run tests
[ecosystem-specific test command]
# Run quality checks
[ecosystem-specific lint/format commands]
# Validate architecture model
make validate-architecture
Project-specific guidance:
AI delegation in this project:
What AI should know:
### Phase 4: Create CHANGELOG.md
```markdown
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Initial project structure
- Foundation ADRs (0001, 0002, 0003)
- Diátaxis documentation framework
- C4 DSL architecture skeleton
[Unreleased]: https://github.com/[username]/[project]/compare/v0.1.0...HEAD
Create docs/roadmap/roadmap.md with an initial project roadmap:
# [Project Name] Roadmap
## Vision
[1-2 sentence project vision — what the project achieves when complete]
## Phases
### Phase 1: Foundation
**Target**: v0.1.x
**Focus**: [Core infrastructure, initial capabilities]
- [ ] [Milestone 1]
- [ ] [Milestone 2]
### Phase 2: [Next Major Capability]
**Target**: v0.2.x
**Focus**: [What this phase delivers]
- [ ] [Milestone 1]
- [ ] [Milestone 2]
### Phase 3: [Production Readiness]
**Target**: v1.0.0
**Focus**: [Hardening, documentation, release]
- [ ] [Milestone 1]
- [ ] [Milestone 2]
## Sprint History
| Sprint | Phase | Version | Summary |
|--------|-------|---------|---------|
| 1 | Foundation | v0.1.0 | [Brief description] |
The roadmap is a living document — update it as phases complete and new ones emerge.
Generate a README.md with:
If SPARK analysis created docs/reference/audience-registry.md, seed initial artifacts:
1. BDD Feature Directories (if using BDD):
features/
├── user/ # Primary audience scenarios
│ └── .gitkeep
├── api/ # Integration audience scenarios
│ └── .gitkeep
└── ops/ # Operational audience scenarios
└── .gitkeep
2. C4 Model Skeleton with persons from Audience Registry:
# In architecture/workspace.dsl
model {
# From Audience Registry
user = person "User" "Primary audience" "Primary"
# Add persons for each Primary/Integration audience
}
3. Diátaxis Stubs per audience:
docs/
├── tutorials/
│ └── getting-started.md # A1: Primary audience
├── howto/
│ └── deployment.md # A3: Operational audience
├── reference/
│ └── api.md # A2: Integration audience
└── explanation/
└── architecture.md # A4: Contribution audience
4. Documentation Frontmatter Template:
---
audience: A1 # Reference to Audience Registry
title: Getting Started
---
Pattern Reference: See AUDIENCE-DRIVEN ARTIFACTS
After completing the bootstrap, suggest invoking based on tier:
Tier 0 — none required. Optionally suggest promotion path: "When you're ready to promote to t1, run this skill again with tier: t1."
Tier 1:
Tier 2 (all of t1 plus):
3. setup-architecture-as-code - Create architecture/ directory, workspace.dsl, and docs symlink
4. plan-sprint - Create Sprint 1 plan
When promoting an existing project from a lower tier to a higher one, this skill should reformat existing artifacts, not recreate them. The decision rationale is already captured at the lower tier; promotion makes it formal.
git log --oneline historysetup-adrs to scaffold ADR-0001, 0002, 0003 (+ 0004 if Infrastructure/Hybrid)setup-pre-commit for quality gates## Project Tier section to t1 and list new artifactsdocs/ structure (Phase 1)setup-architecture-as-code to create the C4 workspace; derive the model from the codebase as it standsplan-sprint for the next sprint cycle (do not retroactively create sprints for completed work; record it in the roadmap and changelog instead)## Project Tier section to t2This skill creates artifacts based on tier:
Tier 0:
.gitignore (technology-specific + security patterns)CLAUDE.md with ## Project Tier section set to t0main, first conventional commitTier 1 (adds to t0):
CHANGELOG.md (initialized, Keep a Changelog format)develop branch created from mainREADME.md (skeleton)t1setup-adrs) ADR-0001, 0002, 0003 [+ 0004 Infrastructure/Hybrid]setup-pre-commit) Two-stage pre-commit hooksTier 2 (adds to t1):
docs/ directory structure (Diátaxis): tutorials, howto, reference, explanation, adr, architecture, sprints, roadmapdocs/roadmap/roadmap.md (initial phases)t2, ## Current Development Status section populatedsetup-architecture-as-code) architecture/workspace.dsl and validation harnessplan-sprint) docs/sprints/sprint-0001-plan.mdfeatures/ subdirectories per audience categoryVerify successful bootstrap based on tier:
Tier 0:
git log shows at least one conventional commit## Project Tier: t0.gitignore covers security patterns (.env, credentials, CLAUDE.local.md)Tier 1 (adds to t0 checks):
4. CHANGELOG.md exists with [Unreleased] section
5. main and develop branches both exist
6. docs/adr/0001-*.md, 0002-*.md, 0003-*.md exist (and 0004-*.md for Infrastructure/Hybrid)
7. Pre-commit hooks installed and run successfully on initial commit
Tier 2 (adds to t1 checks):
8. docs/ directory tree exists (tutorials, howto, reference, explanation, adr, architecture, sprints, roadmap)
9. architecture/workspace.dsl exists and validates
10. docs/sprints/sprint-0001-plan.md exists
11. (If Audience Registry) Traced artifacts align with audience categories
analyze-project - Run SPARK analysis before bootstrapsetup-adrs - Next step: create foundational ADRssetup-pre-commit - Configure pre-commit hookssetup-architecture-as-code - Create architecture modelplan-sprint - Create initial sprint plannpx claudepluginhub jrjsmrtn/jrjsmrtn-skills --plugin project-orchestration-skillsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.