clarity-bootstrap
Use when a new or not-yet-managed software project needs Clarity Framework set up — the smallest relevant document set, a stack-specific AGENTS starter, and optional workflow skills chosen from the pr
SKILL.mdskills/clarity-bootstrap/SKILL.md
GitHubClarity Bootstrap
Set up Clarity from the project's actual needs. Infer first, ask only for material gaps, and apply the minimum coherent setup without turning normal framework choices into approval gates. Do not generate application code.
Guardrails
- Work in the project root. Preserve all existing source code and project-authored documentation.
- If Clarity version markers already exist in the project's documents, stop and invoke
framework-updateinstead. - If this is a Git repository and the tree has unrelated uncommitted changes, report them and stop before writing.
- If the directory is not under version control, infer initialization as the default Delegated choice and initialize in step 5 unless evidence makes repository ownership an Escalation decision. Never initialize a directory that already sits inside another repository — that would nest one repository in another.
- Fetch only a stable tagged Clarity release. Never bootstrap from untagged
mainor a prerelease. - Treat templates as starting structures, not permission to invent product decisions.
- Install every selected Clarity skill identically in both
.agents/skills/<name>/and.claude/skills/<name>/. A same-named non-Clarity skill is an ownership conflict: treat it as Escalation rather than overwriting it.
Step 1 — Inspect, infer, then ask only for material gaps
Inspect the README, build manifests, directory layout, and existing docs without changing them. Infer what is already evident. Establish the Git state first, because it decides whether the documents this skill writes can be versioned at all:
if TOPLEVEL=$(git rev-parse --show-toplevel 2>/dev/null); then
if [ "$TOPLEVEL" -ef "$PWD" ]; then GIT_STATE=repo-root; else GIT_STATE=inside-repo; fi
else
GIT_STATE=none
fi
printf 'git: %s %s\n' "$GIT_STATE" "${TOPLEVEL:-}"
repo-root is the normal case. inside-repo means a parent directory owns the history: use it, and
never initialize a second repository inside it. none means the choice below is live.
Infer product, users, stack, UI/data/API/deployment/operations needs, team shape, AI clients, and workflow needs from the user's project description, repository, manifests, and existing docs. Do not ask for a value merely because the template has a field.
Classify unresolved choices as Delegated, Escalation, or Reserved. Ordinary implementation uncertainty is Delegated: choose the least-consequential reversible option, record the assumption, and continue. During an active project-driver mission, Escalation is orchestrator work rather than a human approval category: resolve it from documented intent and evidence or return it to project-driver. Only a Reserved consequence may become a user-facing gate. In a standalone bootstrap with no active mission, ask one compact question only when the unresolved choice is genuinely material.
When GIT_STATE=none, initialize Git by default because documentation-as-code requires history.
Ask only when there is evidence that repository initialization itself could conflict with the user's
intent or an enclosing ownership model.
Do not ask the user to choose template numbers, runtime plumbing, starter files, or skills. Translate product needs into framework artifacts automatically.
Step 2 — Fetch the release
Use an isolated temporary clone and normalize the tag:
BOOTSTRAP_TMP=$(mktemp -d)
git clone --quiet --filter=blob:none \
https://github.com/HansJoakimPersson/clarity-framework "$BOOTSTRAP_TMP/cf"
CLARITY_TAG=$(git -C "$BOOTSTRAP_TMP/cf" tag -l --sort=-v:refname 'v*' \
| grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
[ -n "$CLARITY_TAG" ] || { printf '%s\n' 'No stable Clarity release found' >&2; exit 2; }
CLARITY_VERSION=${CLARITY_TAG#v}
git -C "$BOOTSTRAP_TMP/cf" cat-file -e \
"${CLARITY_TAG}:skills/clarity-bootstrap/SKILL.md" || {
printf '%s\n' "Latest stable release $CLARITY_TAG does not contain Clarity Bootstrap" >&2
exit 2
}
${CLARITY_TAG} is braced because zsh reads $CLARITY_TAG:skills as a modifier on the variable.
Read the release's README.md ownership and scaling sections before selecting files. Remove the
temporary clone when the run completes or aborts. The self-check deliberately stops an unreleased
bootstrap from combining its newer rules with an older release layout; release Clarity first.
Step 3 — Select the minimum coherent setup
Apply these conditions:
| Artifact | Select when |
|---|---|
README.md |
Always; preserve and extend an existing README, or create a concise project entry point from approved facts |
docs/01-vision-scope.md |
Always |
docs/00-ai-context.md |
Claude Code or Codex will be used after bootstrap |
docs/02-requirements.md |
The project has a launch, users, acceptance criteria, or a team |
docs/02-user-stories.md |
Only when the backlog already exceeds roughly 20 active stories or more than one person maintains it; otherwise keep stories in 02-requirements.md §2.6 |
docs/03-sad.md |
The system has meaningful components, integrations, persistence, or deployment decisions |
docs/04-data-model-api.md |
Persistent data or an API exists |
docs/05-deployment-view.md |
The project is deployed outside a developer machine |
docs/06-test-documentation.md |
The project is launch-bound, production-facing, or team-maintained |
docs/07-runbook.md |
Someone must operate, back up, restore, or troubleshoot it |
docs/08-change-management.md |
Releases or changes need traceability across people or environments |
docs/09-visual-profile.md |
Any visual UI will be implemented |
Choose exactly one matching starter from agents/. Use generic.md when no specialized starter
matches. Never combine starters silently.
Select skills separately:
clarity-bootstrap: keep it installed so the setup remains reproducible.framework-update: select by default for managed projects.plan-driven-build: select when the project will use governed multi-agent implementation.project-driver: select withplan-driven-buildwhen the user wants the orchestrator to drive the project from product intent through successive increments rather than manually request each one.
Step 4 — Resolve the setup
Record the inferred setup in the run report: product/stack assumptions, Git state, release version, selected documents, starter, skills, merge targets, and any assumptions. Continue directly to apply it when every unresolved item is Delegated.
Under an active project-driver mission, do not create a human checkpoint for Escalation; return the smallest material choice to the outer orchestrator. Stop for the human only when project-driver's authority firewall classifies the concrete action as Reserved and issues a human gate. In a standalone bootstrap, present at most one unresolved material decision and never turn the inferred setup into an approval checklist.
Step 5 — Apply without losing existing work
When the resolved setup has no outstanding Escalation/Reserved decision:
- When initialization is selected under the authority rules above, run
git initbefore writing anything, so every file this skill creates is captured by the bootstrap commit rather than arriving as pre-existing untracked clutter. Initialize only whenGIT_STATE=none; never run it forrepo-rootorinside-repo. - Create or update
README.mdfrom the resolved setup, preserving all existing content, then createdocs/and copy only the selected templates from the stable tag. - Fill established facts from the user's description and project evidence. For unknown Delegated details, choose the least-consequential reversible assumption and mark it as an assumption. Leave a visible unresolved item only for an Escalation or Reserved decision.
- Never overwrite an existing project document. Merge the selected template structure around its content. Resolve straightforward mappings from headings and semantics; escalate only when alternative mappings would materially change meaning or ownership.
- If
AGENTS.mdorCLAUDE.mdalready contains project-specific instructions, move them into thedocs/document that clearly governs each one. Escalate only ambiguous ownership or conflicting rules. Then copy the selected starter verbatim toAGENTS.md. - Write
CLAUDE.mdcontaining exactly@AGENTS.mdand nothing else. Never reduce an existingCLAUDE.mdto the import until its content has been migrated under step 5; losing a project's own rules is worse than leaving the file inconsistent for one more round. - For each selected skill, replace only its exact Clarity-managed target directory under both
runtime roots with the release copy. Verify every pair using
diff -qr. - Ensure
.gitignoredoes not exclude the selected.agents/skills/or.claude/skills/files. Narrow broad runtime-directory ignores while preserving ignores for local settings and caches. - Add
docs/plans/.runs/,.agents/build-env.local.sh, and.m2/to.gitignorewhenplan-driven-buildis selected. Preserve all existing ignore rules. - When
plan-driven-buildis selected and the stack has a build tool, write.agents/preflight.shfrom the example in the skill'ssetup.md("Implementation and the build environment"), with the one command that proves the tool runs (mvn -q -version,npm --version,go version). Write.agents/build-env.shonly when the tool needs an environment an interactive shell provides and a dispatch does not. A preflight that runs the tool turns a broken environment into a one-second failure instead of a build that spends its budget discovering it. - When documents are written in another language and named accordingly, keep the names the project chose and record each one against its canonical template name in the AI Context table "Where is more context?". Agent starters and skills refer to documents by canonical name and resolve them through that table.
Do not edit the copied AGENTS.md or skill files, and never add rules to CLAUDE.md.
Project-specific deviations belong in docs/, in the document that governs them.
Step 6 — Stamp and verify
Write the marker into docs/00-ai-context.md — the Clarity-managed setup block under its AI
workflow section. That document is where framework-update looks for both the framework version and
the list of Clarity-managed skill names, so a marker written anywhere else leaves the next update
unable to tell a Clarity skill from a third-party one. There is no separate version file.
agents-starter: <starter name without .md, or none>
skills: <comma-separated Clarity-managed names>
skill-paths: .agents/skills, .claude/skills
Set the framework version and date in the document's header table (Framework version and Last updated), not in the block. One fact, one place.
When 00-ai-context.md was not selected in step 3 — no agent will work on the project — skip the
marker and say so in the report. Nothing reads it in that case, and framework-update falls back to
the version footers in the other documents.
Verify:
CLAUDE.mdcontains@AGENTS.mdand nothing else;- every selected document exists exactly once at its standard
docs/NN-*.mdpath, or at the project's own name with the canonical name recorded in the AI Context table; .agents/preflight.sh, when written, exits 0 on this machine;- both runtime copies of each managed skill are identical;
git check-ignoreconfirms that neither managed skill copy is excluded;- existing Framework version markers match the fetched tag;
- no source file or documentation outside the resolved setup changed.
Report remaining placeholders and material decisions first, then created/merged artifacts and
verification results. When plan-driven-build was selected, also name the values its runtime
contract still needs (model pools, gate command, rollout budget) in one list, and point at the
client permission rules in the skill's settings.example.json: they are a convenience the user adds
to the client's own settings, separate from the clarity-authority block, and bootstrap does not
write them. A bootstrap commit is Delegated unless the project explicitly reserves commits
or the commit would include unrelated pre-existing work; create it and report the SHA.
The Git-dependent checks and the commit proposal are unconditional, because step 5 has already guaranteed a repository in every path except one: the user declined initialization. Only then, skip those checks and close with what the project is missing and the one command that fixes it —
Not under version control, so .gitignore handling, git check-ignore verification, and the bootstrap
commit were skipped. The Clarity documents exist but are unversioned. Run `git init`, then ask for a
bootstrap commit.
Do not present that as a routine closing note. The user declined a recommendation and the setup is incomplete as a result; say so plainly, once, without repeating the argument for versioning.