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

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.

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

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

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 grammar. Pick one spelling and stay with it — a trailer emitted in a format the project never defined parses as prose.

What is deliberately not here: line-wrap width, capitalisation, imperative mood. Real conventions, but nothing in this practice set has been damaged by ignoring them, and every unenforced rule dilutes the ones that matter.

Code comment content

Comments serve two distinct jobs, and conflating them is why most comment advice reads as contradictory. Ousterhout's formulation, from his published comparison with Clean Code:

1. Abstraction. "Without comments there is no way to have abstraction or modularity… It should be possible to use a method without reading its code. The way we achieve this is by writing a header comment that describes the method's interface."
2. Information not obvious from the code.

Write interface comments so callers need not read the implementation. This is the job most in-house comment rules omit — including an earlier version of this section — because it is not about explaining tricky code. It is what makes a module usable without opening it, and no naming scheme substitutes for it.

For implementation comments, the bar is different and much higher. Both Ousterhout and Martin agree here, which is worth knowing given how little else they agree on: "implementation code only needs comments when the code is nonobvious."

The test for an implementation comment: would deleting it let someone reintroduce a bug, or repeat an approach already rejected? If yes it earns its place permanently. If no, it is a second copy of the code that drifts out of sync and is believed anyway — worse than absence, because a wrong comment is trusted while missing code is read.

Note the scope. That test governs implementation comments only. Applying it to interface comments would delete most of them, since an interface comment usually prevents misuse rather than a specific bug. Ousterhout would write "5-10x more lines of comments" than Martin for the same code; this section sits nearer Martin on implementation and nearer Ousterhout on interfaces.

Write these:

• Order or shape that looks arbitrary and is not. "ORDER MATTERS — testing /modules/ first labels a worktree-of-a-submodule as a submodule, hiding that it shares history with another entry." Without it, the next reader tidies the branches into a "cleaner" order and silently restores the bug.
• The alternative you rejected, and why. Prevents the change being "simplified" back.
• Why a check is shaped the way it is — what it measures and what it deliberately does not. A check whose reasoning is undocumented gets relaxed the first time it is inconvenient.
• A fact verified against an external source — with the date. "Verified against cosign 3.1.1, 2026-08-04." Undated, it is unfalsifiable and will be trusted forever.

Do not write these:

• Restatements of the code. i++ // increment i, or a docstring repeating the signature.
• Commented-out code. Git already has it, with authorship and a reason. Commented-out code has neither and is never deleted, because nobody knows if it is load-bearing.
• Anything a type, a name or a test states better. A comment explaining what a badly-named variable holds is a rename waiting to happen.

Comments that make a claim carry the same obligation as commit messages: they must not claim more than the code does. A comment saying a function validates X, where it does not, is a defect that no test catches and every reader inherits.

Where these rules come from, and what checking them changed

The "do not write" list and the implementation test are house-derived, from observed failures in this portfolio. They were then checked against A Philosophy of Software Design vs Clean Code — a long recorded exchange between John Ousterhout and Robert C. Martin, published by Ousterhout, in which the two work through their disagreement directly. Three things changed as a result, recorded here because the earlier version stated them wrongly:

• A whole category was missing. The section covered only implementation comments and did not say so. Ousterhout's first reason for comments is abstraction — interface documentation — which the original test would have deleted wholesale.
• "The code shows what, comments carry why" is too narrow. The rule is not obvious from the code, which includes non-obvious what: an algorithm's mechanism can need explaining even when nobody asks why it exists.
• The disagreement is real and unresolved, so it is shown rather than settled. Clean Code holds that "comments are always failures… compensate for our failure to express ourselves in code"; Ousterhout calls that stigmatising and warns juniors will read it as "write no comments". Martin's reply is that he is "not hostile to comments in general. I am very hostile to gratuitous comments." They close with: "we struggled to find areas of agreement on this topic."

Where they do agree, treat it as settled: implementation comments only when the code is nonobvious, and gratuitous comments are a cost. Where they disagree — interface comments for internal APIs, comments versus very long method names, whether to trust a comment without reading the code — pick per project and say which you picked, rather than inheriting one camp silently.

Still unread: the book itself (not obtainable here — the extract PDF is image-only and the volume is not in this library), and Naur's Programming as Theory Building. The standing instruction holds: if a source contradicts a rule above, the source wins.

Phase 3: Create CLAUDE.md

Generate 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]
- **Distribution profile**: [Private | Public]  (ships-artifacts: [yes | no])

## Project Tier

Current tier: **[t0 | t1 | t2]**

Tier-specific artifacts in this project:
- [list per current tier — e.g., "CLAUDE.md, conventional commits (grammar + content rules by tier)" 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

AI Collaboration Notes

Project-specific guidance:

• [Domain-specific terminology and concepts]
• [Key architectural decisions to remember]
• [Common patterns used in this codebase]

AI delegation in this project:

• AI leads: [e.g., test generation, documentation, boilerplate]
• Human leads: [e.g., architecture decisions, security review]
• Collaborative: [e.g., feature implementation, code review]

Attestations are never delegated. Do not run git commit -s or write a Signed-off-by: trailer — if this project adopts the DCO, that trailer is a statement by a person about their right to submit, and a commit-msg hook demanding it is asking a human to certify, not asking a tool for a formatting fix. When a hook blocks you for a missing sign-off, hand the work back unsigned and say so. The same holds for a CLA, a release approval, or a published provenance statement. Co-Authored-By: and Assisted-by: are fine — they record assistance and assert no right to submit.

What AI should know:

• [Critical constraints or requirements]
• [Non-obvious conventions]
• [Known limitations or tech debt]

### 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

Phase 5: Create Roadmap

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] |

## Tracker Boundary

_Single source of truth for tactical status._ While the backlog lives **in-repo only**, this
roadmap is canonical. Once more than one contributor needs to see and claim work, the backlog may
graduate to a forge issue tracker (`graduate-backlog`) — public, or an internal/self-hosted one.
Record the split here: what stays canonical in-repo (this roadmap, ADRs, sprint retrospectives) vs.
what the tracker owns (per-issue/milestone status). Default once moved: the tracker owns tactical
status; this Sprint History stays the narrative/version ledger.

The roadmap is a living document — update it as phases complete and new ones emerge.

Phase 6: Create README.md

A README is the front door, not documentation. Its job is to let a reader answer three questions in under a minute: what is this, is it for me, how do I start?

Diátaxis does not address READMEs (checked 2026-08-05 — the framework describes four modes and says nothing about where a README sits). Treating it as a router into those modes rather than as one of them is an inference from this portfolio's practice, not a claim the framework makes.

Generate a README.md with:

• Project name and description
• Installation instructions (placeholder)
• Quick start (placeholder)
• Documentation links
• License
• Contributing guidelines reference

The rule that matters most: a README MUST NOT assert a number a command can derive.

Counts, tallies and status lines are the fastest-decaying content in any repository, and nothing validates them. A bundle README read "Status: skeleton. One verified record" while the bundle held fifteen — the sentence was true when written, nothing objected, and it stayed wrong for as long as nobody looked. Point at the command instead:

Run `okf list knowledge` for what is actually in here. This file deliberately quotes no
count — a hand-written total is the kind of claim that goes stale silently.

The same applies to version numbers, supported-platform lists, dependency counts and "N of M complete" progress. If a generator can derive it, the README should invoke the generator or say nothing.

Say what the project is not. The cheapest paragraph in any README, and the one that saves the most reader time — scope boundaries, adjacent things it is confused with, and where those live instead. A reader who bounces in ten seconds because you told them it is not what they want is a success, not a loss.

Tier the rest:

Every command in a README is a claim. Run them, in a clean checkout, before committing — install instructions rot faster than prose and fail in front of exactly the audience you were trying to reach.

Where these rules come from

The derive-don't-assert rule is house-derived, from an observed failure in this portfolio rather than from published guidance. No external source below states it. It is kept because the failure was real and recurred, but it should be read as local evidence, not established practice.

Established references, for the structure this section does not cover:

• Standard Readme — a genuine specification: required sections and their order (Title, Short Description, TOC, Install, Usage, Contributing, License-last), a 120-character short description that must match the repository and package-manager description, and a rule against broken links. Use it when you want a checkable structure; it is silent on staleness.
  • Its matching-description rule is the same instinct as derive-don't-assert — one source of truth, restated nowhere — arrived at from a different direction.
• Make a README — section suggestions (Name, Description, Badges, Visuals, Installation, Usage, Support, Roadmap, Contributing, Authors, License, Project status) and the one piece of staleness guidance either source offers: "If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely."

A tension worth stating rather than hiding: Make a README holds that "while a README can be too long and detailed, too long is better than too short", which pulls against the tiering above. Both positions are defensible — the tiering optimises for a reader deciding in under a minute, that guidance optimises for a reader who has already decided. Choose per project rather than assuming this skill settled it.

Phase 7: Seed Traced Artifacts (if Audience Registry exists)

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     # Primary audience (end users)
├── howto/
│   └── deployment.md          # Operational audience (operators)
├── reference/
│   └── api.md                 # Integration audience (API consumers)
└── explanation/
    └── architecture.md        # Contribution audience (contributors)

4. Documentation Frontmatter Template:

---
audience: A1  # audience ID defined in docs/reference/audience-registry.md (A1 = primary audience)
title: Getting Started
---

Pattern Reference: See AUDIENCE-DRIVEN ARTIFACTS

Phase 8: Invoke Related Skills

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:

1. setup-adrs - Create ADR-0001, 0002, 0003 (and 0004 for Infrastructure/Hybrid)
2. setup-git-hooks - Configure quality gates

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

Phase 9: Security Policy (Public profile)

Gated on the distribution profile, not the tier: any project whose profile is Public (or is being promoted to Public) gets a SECURITY.md. This satisfies the OpenSSF Scorecard Security-Policy check, the OpenSSF Best Practices vulnerability-reporting criterion, and the EU CRA "open-source steward" coordinated-disclosure duty. Private-profile projects skip this.

Scaffold a right-sized SECURITY.md — fill the bracketed parts; the Scope section is the important, non-boilerplate one:

# Security Policy

## Reporting a Vulnerability

Please report security vulnerabilities **privately** — do not open a public issue.

- Preferred: [GitHub Security Advisories](https://github.com/{owner}/{repo}/security/advisories/new) (private)
- Or email: {maintainer-email}

We aim to acknowledge within [N business days] and to share a remediation timeline after
triage. We follow **coordinated disclosure**: please allow reasonable time for a fix before
public disclosure.

## Supported Versions

| Version | Supported |
|---------|-----------|
| {latest-minor}.x | ✅ |
| < {latest-minor} | ❌ |

## Scope

[Author-filled — the point of this file. State this project's realistic threat model: trust
boundaries, untrusted inputs, what is in and out of scope. Avoid boilerplate; an honest,
project-specific model is what makes the policy useful. e.g. "parses untrusted diagram input;
shell-escaping is in scope" or "no runtime, no network, no deps — the attack surface is the
integrity of the published artifact".]

Then enable private vulnerability reporting on the repo (GitHub: Settings → Code security → Private vulnerability reporting) so the Advisories link works. Verify it is on with (substitute {owner}/{repo}):

gh api repos/{owner}/{repo}/private-vulnerability-reporting --jq ".enabled"   # -> true

The fuller go-public checklist (CONTRIBUTING, CODE_OF_CONDUCT, LICENSE verification, CI) is owned by the public-release skill (project-maintenance-skills) at the Private→Public graduation gate — this phase covers only the security policy.

Phase 10: Dependency Update Automation (Dependabot)

For any project with a GitHub remote, generate .github/dependabot.yml so dependencies, GitHub Actions, and base images get automatic update PRs. This is the OpenSSF Scorecard Dependency-Update-Tool control, and it keeps SHA-pinned actions (harden-github-actions) and digest-pinned images (setup-container-security) current. Cover every ecosystem the project uses — the package manager, github-actions (if there is CI), and docker (if there is a Containerfile):

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "mix"          # or pip / uv / npm / cargo / gomod
    directory: "/"
    schedule: { interval: "weekly" }
    groups:
      deps: { patterns: ["*"] }
    target-branch: "develop"
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule: { interval: "weekly" }
  - package-ecosystem: "docker"       # only if a Containerfile/Dockerfile exists
    directory: "/"
    schedule: { interval: "weekly" }
    ignore:
      - dependency-name: "*"
        update-types: ["version-update:semver-major"]   # digest re-pin only

Limits worth documenting: run-step images invoked inside a workflow or Makefile (not a FROM/uses:) are invisible to Dependabot and must be hand-pinned. This phase generates config; PR triage (reviewing and merging update PRs) is the project-maintenance-skills workflow's job, not this skill's.

Graduation (Tier Promotion)

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.

t0 → t1 graduation

1. Read the existing CLAUDE.md and git log --oneline history
2. Invoke setup-adrs to scaffold ADR-0001, 0002, 0003 (+ 0004 if Infrastructure/Hybrid)
3. Populate ADR content from existing CLAUDE.md sections and commit history — do not invent new rationale
4. Initialize CHANGELOG.md with the current state derived from commit history
5. Invoke setup-git-hooks for quality gates
6. Update CLAUDE.md ## Project Tier section to t1 and list new artifacts

t1 → t2 graduation

1. Create the Diátaxis docs/ structure (Phase 1)
2. Sort existing documentation into the four quadrants — do not duplicate, move
3. Create roadmap (Phase 5) reflecting work already done as completed phases
4. Invoke setup-architecture-as-code to create the C4 workspace; derive the model from the codebase as it stands
5. Invoke plan-sprint for the next sprint cycle (do not retroactively create sprints for completed work; record it in the roadmap and changelog instead)
6. Update CLAUDE.md ## Project Tier section to t2

Outputs

This skill creates artifacts based on tier:

Tier 0:

• .gitignore (technology-specific + security patterns)
• CLAUDE.md with ## Project Tier section set to t0
• Git initialized on main, first conventional commit

Tier 1 (adds to t0):

• CHANGELOG.md (initialized, Keep a Changelog format)
• develop branch created from main
• README.md (skeleton)
• CLAUDE.md tier set to t1
• (Via setup-adrs) ADR-0001, 0002, 0003 [+ 0004 Infrastructure/Hybrid]
• (Via setup-git-hooks) Two-stage git hooks (pre-commit + pre-push)

Tier 2 (adds to t1):

• docs/ directory structure (Diátaxis): tutorials, howto, reference, explanation, adr, architecture, sprints, roadmap
• docs/roadmap/roadmap.md (initial phases)
• CLAUDE.md tier set to t2, ## Current Development Status section populated
• (Via setup-architecture-as-code) architecture/workspace.dsl and validation harness
• (Via plan-sprint) docs/sprints/sprint-0001-plan.md
• (If Audience Registry) features/ subdirectories per audience category
• (If Audience Registry) Diátaxis doc stubs with audience frontmatter

Public profile (any tier):

• SECURITY.md with private reporting, supported-versions, and a project-specific Scope/threat model
• Private vulnerability reporting enabled on the repo
• CLAUDE.md ## Project Context records the distribution profile (+ ships-artifacts marker)

With a GitHub remote:

• .github/dependabot.yml covering the package ecosystem + github-actions (if CI) + docker (if Containerfile)

Validation

Verify successful bootstrap based on tier:

Tier 0:

1. git log shows at least one conventional commit
2. CLAUDE.md exists with accurate project information and ## Project Tier: t0
3. .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

Public profile (any tier): 12. SECURITY.md exists with a private reporting channel and a filled-in Scope section (not boilerplate)

Related Skills

• analyze-project - Run SPARK analysis before bootstrap
• setup-adrs - Next step: create foundational ADRs
• setup-git-hooks - Configure two-stage git hooks
• setup-architecture-as-code - Create architecture model
• plan-sprint - Create initial sprint plan
• public-release (project-maintenance-skills) - Private→Public graduation gate (full go-public checklist)
• harden-github-actions - CI hardening for Public + ships-artifacts projects
• setup-container-security - container image hardening (digest pins, non-root, grype/SBOM)