--- name: bootstrap-project description: 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. metadata: author: "Georges Martin <jrjsmrtn@gmail.com>" version: "0.1.34" license: MIT ---

# Project Bootstrap

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.

## When to Use

- Starting a new software project (pick a tier appropriate to scope) - Promoting an existing project from a lower tier to a higher one - Converting an existing project to follow best practices - Setting up a project for AI-assisted development

> **Pattern Reference**: See [TIERED-BOOTSTRAP](https://github.com/jrjsmrtn/ai-assisted-project-orchestration/blob/develop/docs/patterns/inception/tiered-bootstrap.md) for the underlying pattern, including knowledge-preservation argument and the comparison with spec-driven development tools.

## Required Inputs

Before running this skill, gather from the user:

1. **Project name** (kebab-case, e.g., `my-awesome-project`) 2. **Project description** (1-2 sentences) 3. **Tier** (graduation level — see [Tier Selection](#tier-selection) below): - **t0** — minimum viable foundation (CLAUDE.md + git + conventional-commits) - **t1** — decision-tracked project (+ foundation ADRs + pre-commit + changelog) - **t2** — full pattern language (+ Diátaxis + C4 + sprint cadence + roadmap) — **default** 4. **Project category**: - **Development**: Software (applications, libraries, services) - **Infrastructure**: Operations (homelab, deployment, monitoring) - **Hybrid**: Both development and operations components 5. **Project type** (library, web application, CLI tool, API service, infrastructure automation) 6. **Technology stack** (e.g., "Elixir/Phoenix/Ash", "Python/FastAPI", "Ansible") 7. **License** (MIT, Apache-2.0, proprietary) — required at t1+, optional at t0 8. **Git remotes** (private origin only, or multi-remote with public GitHub/GitLab) 9. **Distribution profile** (exposure — orthogonal to the tier): **Private** (default — internal/homelab/WIP) or **Public** (open-sourced on a public forge *and* properly licensed). Set the **`ships-artifacts`** marker if the maintainer will publish built packages/images to a registry (Hex/PyPI/GHCR/containers) or signed release binaries. The profile governs which compliance controls apply — see [Distribution Profile](#distribution-profile) below.

**Why project category matters:** - **Development**: ADR-0004 (Operations) is skipped - **Infrastructure**: ADR-0004 is created (backup, monitoring, change management) - **Hybrid**: ADR-0004 is created, covering both application and infrastructure operations

## Tier Selection

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**: - **t0 → t1**: more than one contributor, project survives two weeks, first decision deserves a numbered record - **t1 → t2**: docs need structure beyond CLAUDE.md, architecture needs visual artifacts, work needs sprint-scale planning, project nears 1.0

**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).

## Distribution Profile

**Orthogonal to the tier.** The tier measures process *maturity*; the distribution profile measures *exposure* — how far the software travels — which is what actually gates compliance controls. A mature internal tool has no external obligations; an early public library incurs them the moment it ships. Set the profile at inception (default **Private**), and graduate it like the tier.

| Profile / marker | Trigger | Controls it adds | |---|---|---| | **Private** (default) | internal / homelab / WIP | baseline hygiene (secret scanning — already universal) | | **Public** | open-sourced on a public forge **and** licensed | LICENSE/REUSE, `SECURITY.md` + coordinated disclosure (Phase 9), OpenSSF Scorecard aspirational | | **`ships-artifacts`** (marker) | publishes built packages/images to a registry, or signed release binaries | + SLSA provenance, SBOM, signing, trusted publishing (via `harden-github-actions`, `wrapup-sprint`) |

Going Public *is* making the source redistributable (licensing is part of the gate), so there is no separate "distributed" level. **`ships-artifacts` is a boolean, not a rung** — set it when going public, later, or never. Controls attach to the profile, not the tier, so a project pays only for its actual exposure. Record the profile in CLAUDE.md `## Project Context`; promotion to Public is the `public-release` graduation gate (`project-maintenance-skills`).

This axis maps to recognized frameworks: **Public** → EU CRA "open-source steward" duties + OpenSSF Best Practices; **`ships-artifacts`** → SLSA / EEF Ægis trusted publishing. Treat these as guidance, not legal advice. The `commercial` case (placing on the EU market for pay), which triggers full CRA manufacturer obligations, is out of scope here.

## Phases by Tier

| 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-git-hooks` | 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-git-hooks`. Still no Diátaxis tree or C4 model.

At **t2**, run all phases. This is the existing default behavior.

**Public profile (any tier)**: additionally run **Phase 9** (`SECURITY.md` + coordinated disclosure). This is gated on the distribution profile, not the tier — a t0 project that is Public still needs it, and a t2 Private project does not.

## Workflow

### Phase 1: Directory Structure

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/ ```

### Phase 2: Git Initialization

1. Initialize git if not already: `git init` 2. Create appropriate .gitignore using gitignore.io for the technology stack 3. Add common security patterns to .gitignore: ``` # Secrets and credentials .env .env.* !.env.example .envrc .envrc.local *.pem *.key credentials.json secrets.yaml

# Claude Code local files CLAUDE.local.md ``` 4. Set up gitflow branches: - Create initial commit on `main` - Create `develop` branch from `main` - Set `develop` as default working branch

> **Interacts with OpenSSF Scorecard** (if you add `harden-github-actions`' Scorecard workflow). > Scorecard's content analysis runs against the **default branch**, so making `develop` the default > means the published score describes the **integration** branch, not the `main` releases are cut > from. (The `Branch-Protection` check is the exception — it also inspects release branches — but > `Pinned-Dependencies`, `Dangerous-Workflow`, `Token-Permissions`, etc. read the default branch.) > Two honest resolutions: keep `develop` default and protect/harden it as the graded branch, or make > `main` the default and treat `develop` as a long-lived branch. Decide deliberately — see > `harden-github-actions` Step 6.

#### Commit message content

[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specifies the **grammar** — `type(scope)!: description`, uppercase `BREAKING CHANGE`, a blank line before the body, footers as git trailers. Its Rule 7 makes the body *"free-form"*, and that is a vacuum rather than an endorsement. These rules fill it.

**Scale them by tier.** Loading a solo t0 project with a five-rule commit policy is how conventions get ignored wholesale.

| Tier | Applies | |---|---| | **t0** | Rule 1 — subject discipline | | **t1** | + Rules 2 and 3 | | **t2** | + Rule 2 wired as a hook (`setup-git-hooks`), + trailer grammar stated |

**1. The subject says what changed. The body says why — or there is no body.** The diff already shows what. A body restating the subject in longer words is worse than none, because it looks like rationale and is not. *Test: delete the body. If nothing is lost, it should not have been there.*

**2. A commit message MUST NOT claim more than the commit contains.** The sharpest rule, because a wrong message is worse than a thin one: a thin message is merely unhelpful, a wrong one is a false record that outlives everyone who could correct it, and `git log` is where people go precisely when the code no longer explains itself.

This failure is easy to commit and hard to notice. An edit silently does nothing — a pattern that did not match, a file already in the target state — while the message, written beforehand, describes it confidently. **The risk is highest when the message is generated**, since fluent prose about an intended change reads identically whether or not the change landed.

> Before committing, re-read the message against `git diff --cached` and not against your intent.

`setup-git-hooks` can enforce the mechanical half — see *Commit message honesty* there.

**3. Record what would otherwise be lost.** Why this approach rather than the one you rejected; what you tried that failed; what constraint forced the shape. Not the diff in prose — the reasoning that cannot be recovered from the tree. This is the highest-value content in any commit and the first thing omitted under time pressure.

**Two supporting rules**

- **Corrections belong in the message of the commit that fixes them**, naming *what the old state would have misled someone into believing*. A CHANGELOG entry reaches readers; a commit message reaches whoever runs `git blame` in two years, which is a different and usually more desperate person. - **Trailers are structured metadata, not decoration.** Git standardises the *shape* of a trailer block and nothing about which tokens mean what, so any project using `Assisted-by:`, `Co-authored-by:` or similar must state its own gr