Project Bootstrap

---
name: project-bootstrap
description: |-
  Initialize a new project context inside the task repository before any task exists. Creates projects/<client>__<project>/, PROJECT_CHARTER.md, REFERENCES.md skeleton, and active/ plus archive/ subfolders so subsequent task-init runs have grounded project-level memory to consume. Use when starting a brand-new project, product, initiative, or client engagement, projects/<client>__<project>/ does not yet exist, or you need to capture project-level context (objective, stack, planned repositories, constraints, references) before opening the first task. Do not use when the project folder already exists (use task-init to start a new task on top of it), you only need a new task on an existing project, you only need to capture external references for an existing project (use capture-references), or the work is task-scoped and short enough that bootstrap ceremony adds no value.
metadata:
  category: "project-initialization"
  primary-cursor-mode: "Ask"
  multi-repo-aware: "false"
  context-layers-consumed: ""
  context-layers-produced: "memory, retrieved"
  tools: "Read, Write, Edit, Bash, Glob, Grep"
  x-wos-profiles: "core, full"
  provenance: "first-party"
  suggested-model: "claude-sonnet-5-5"
---

Act as a senior/staff engineering project initializer.

Goal:
Initialize a new project context inside the task repository before any task exists. Create the project folder, the project charter, and the references skeleton, so that subsequent `task-init` runs have grounded project-level memory to consume.

This command is the canonical zero-state entry point for a brand-new project (product, initiative, or client engagement) that does not yet have a folder under `projects/`.

Mandatory context bootstrap (before any output):
- **Resolving the spec and `wos/<topic>.md`:** canonical repository FIRST. Otherwise use active-adapter docs: `~/.claude/workflow-docs` (`CLAUDE_WORKFLOW_DOCS_DIR`), `~/.cursor/workflow-docs` (`WORKFLOW_DOCS_DIR`; project `.cursor/workflow-docs` on project installs), `~/.codex/workflow-docs` (`CODEX_WORKFLOW_DOCS_DIR`), or `<kimi-home>/workflow-docs` (`KIMI_WORKFLOW_DOCS_DIR`). Nonempty overrides win. Kimi home: `KIMI_CODE_HOME`, else existing `~/.kimi-code`, else existing `~/.kimi`, default `~/.kimi-code`. Use one root for both paths; try other adapters if absent or unknown. Report resolved root, fallback to other adapters, or missing mandatory context in `### Command transcript`. Installed snapshots refresh and prune retired topics only on sync.
- Read these sections in `WORKFLOW_OPERATING_SYSTEM.md` first:
  - `## LLM execution contract`
  - `## Editor mode policy`
  - `## Global output contract` (including **Adaptive handoff** and **Mode selection rule**)
  - `## Cross-cutting workflow guardrails`
  - `## Project-level memory`
- Read additional sections only when needed:
  - naming/path setup: `## Naming conventions`, `## Repository structure`
  - multi-repo schema: `## Multi-repo support (v1)`
  - phase/entry ambiguity: `## Command roles` index (or `wos/command-roles.md` for full per-command detail), `## Entry points`
- Read canonical command inventory when a clone is available; otherwise use installed Fhorja commands and skills.
- Align all routing recommendations and next-command suggestions with the current command set.
- **Official next-command names only:** every recommended next command MUST use a registered canonical command name or available installed Fhorja command or skill. Never invent names. The default next command after `project-bootstrap` is `task-init`; alternative next steps are `capture-references` (when the user wants to research external context before opening the first task) or `what-next` (when the user is uncertain). When the bootstrapped stack is defined and the product has a notable feature set, mention that `feature-library-scout` (run inside the first task, after `task-init`) surfaces community-vetted per-feature libraries (ADR-0045); it needs an active task folder, so it is never the direct next step from `project-bootstrap`. One exception: `Run now: none` with `Mode: N/A` declares that the chain has ended and no following command would be honest, defined under `### Official command names (routing integrity)` (ADR-0126); use it only when nothing honest remains, never to end a chain that has a real next step.

Required inputs:
- initial product description / objective from the user
- client and project identifier (or enough context to derive `<client>__<project>`)
- intended editor mode (Ask for drafting only, or Agent for actual file creation in the task repository)
- optional but encouraged: stack (or explicit `[not decided yet]`), planned repositories, known references (URLs, docs, tickets), constraints, non-goals, stakeholders

Adaptive question flow (loop control):
- This command MUST ask only the minimum questions needed to fill the required fields below; everything else stays as `[to be confirmed]` or `[not decided yet]` in the artifacts.
- Reuse the question discipline of `targeted-questions` (one question at a time, narrow, no compound questions).
- The question loop ENDS as soon as all of these are answered (each may be answered with `[not decided yet]` by the user):
  1. client + project identifier
  2. product objective (one paragraph)
  3. stack (or explicit `[not decided yet]`)
  4. planned repositories (0, 1, or N; if N is at least 2, capture the multi-repo schema upfront)
  5. known references (URLs/docs/tickets) or explicit "none yet"
  6. constraints and non-goals known so far, or explicit "none yet"
- Do NOT ask speculative or design questions (architecture choices, naming standards, backlog items, etc.). The command is for context capture, not for solving.
- Do NOT propose stack, repos, references, constraints, or non-goals not stated by the user. Treat user input as the strongest source of truth; record verbatim where possible.
- **No human respondent (unattended or fleet-dispatched run, or a background session failing the ADR-0237 test; ADR-0044 doctrine):** do NOT self-answer and do NOT lock anything. Fill each unanswered required field with its `[not decided yet]` / `[to be confirmed]` placeholder, note in `### Command transcript` that the question loop ran unattended, and route the open fields to the next human session. Self-answering a bootstrap question and recording it as user input is a contract violation, not initiative. A required field the dispatching brief answers is an answered field: record it verbatim with the provenance note "from the dispatching brief" (per `wos/cross-cutting-workflow-guardrails.md ### Unattended sessions`); placeholders apply only to the fields the brief leaves open.

Project repository structure to use:
- projects/<client>__<project>/
  - PROJECT_CHARTER.md
  - REFERENCES.md
  - active/                 (empty folder, ready for the first task)
  - archive/                (empty folder)

Mandatory files to create:
- PROJECT_CHARTER.md
- REFERENCES.md (skeleton, or seeded if the user provided references during the question flow)

Task folders must NOT be created in this command. The first task is created by the next `task-init` run.

Project naming rules:
- project folder name must be:
  - `<client>__<project>`
- keep names lowercase and hyphenated when possible
- avoid vague names; the identifier should remain stable across all future tasks for this project

Operating rules:
- Do not implement production code.
- Do not create any task folder (no `active/YYYY-MM-DD_<task-slug>/` content). That is `task-init`'s job.
- Do not invent stack choices, repos, references, constraints, non-goals, or stakeholders. Where unknown, write explicit placeholders such as `[not decided yet]`, `[unknown yet]`, `[to be confirmed]`, `[none recorded yet]`.
- Do not duplicate the `targeted-questions` flow inside this command's output; ask the minimum and stop as soon as the loop control conditions above are satisfied.
- Multi-repo handling: when the user lists 2 or more repositories at bootstrap time, record them in `PROJECT_CHARTER.md` using the multi-repo schema (identifier, path, base branch, role) defined in the spec `## Multi-repo support (v1)`. The first `task-init` for this project should mirror the same repos into `SOURCE_OF_TRUTH.md`. Single-repo and zero-repo projects record only what is known and skip the multi-repo block entirely (the single repo, if any, is recorded under `## Default workspace`).
- When `projects/` does not exist in the task repository yet, this run creates it: apply `### Task memory stays out of git` below.
- References handling: if the user pre-supplies URLs/docs at bootstrap time, seed them into `REFERENCES.md` using the format defined in `capture-references`. Otherwise emit an empty skeleton with the format reminder block intact.
- **Handoff:** end with the adaptive `### Handoff` block per `WORKFLOW_OPERATING_SYSTEM.md` `## Global output contract` (Mode A compact or Mode B full). Default next command is `task-init` in Ask mode.

Files to generate:

1. PROJECT_CHARTER.md
Must use this exact structure:

# PROJECT_CHARTER

## Project name
<client>__<project>

## Status
[active | paused | archived]

## Objective
[Short paragraph describing the product, initiative, or client engagement and the intended outcome]

## Stack
[Languages, frameworks, runtime, hosting; or `[not decided yet]`]

(Emit the `## Repositories` section below ONLY when 2 or more repositories are known. If zero or one repository is known, omit the heading entirely and record the single repo, if any, under `## Default workspace` instead; a dangling empty `## Repositories` heading is a template bug.)

## Repositories
- identifier: [lowercase, hyphenated, unique within the project]
  path: [local path or `[unknown yet]`]
  base branch: [`origin/main` or `[unknown yet]`]
  role: [backend | frontend | shared | infra | mobile | other]

(Repeat one block per repository.)

## Default workspace
[Local path of the primary product workspace, or `[not decided yet]`. Used only when the project does not have 2 or more repositories.]

## Constraints
- [constraint 1, or `[none recorded yet]`]

## Non-goals
- [non-goal 1, or `[none recorded yet]`]

## Stakeholders
- [name or role, or `[not recorded yet]`]

## Initial references
- See `REFERENCES.md` for external references captured at bootstrap time and via subsequent `capture-references` runs.

## Project-level memory pointers
- `PROJECT_CHARTER.md` (this file): high-level project context.
- `REFERENCES.md`: external references with freshness metadata (URL, accessed date, summary, key points, tags).
- `active/`: in-progress task folders.
- `archive/`: completed task folders moved out of `active/` after delivery.

2. REFERENCES.md
Must use this exact structure:

# REFERENCES

Project-level external references for `<client>__<project>`.

This file is appended to by `capture-references`. New entries are grouped under a topic/tag heading using the format defined in that command. Do not paraphrase entries; do not delete entries; deduplicate by URL.

## Format reminder

```text
## <Topic / Tag>
### <Title from the source>
- URL: <url>
- Accessed: YYYY-MM-DD
- Summary: <one paragraph; what this source says, never beyond what is on the page>
- Context within project: <1-3 sentences situating this source in the project; "first reference in this project" when first (ADR-0018)>
- Key points:
  - "<verbatim quote from the source>"
- Consumes-by: <consuming command, task slug, or `TBD` (ADR-0056)>
- Tags: <tag1>, <tag2>
```

## Entries

(empty; populated by `capture-references` or seeded by this `project-bootstrap` run when the user provided references upfront)

Required output:
1. Resolved project folder name (`<client>__<project>`)
2. Full project path to create (`projects/<client>__<project>/`)
3. Why this is a create operation (project did not exist before this run)
4. Exact content for:
   - PROJECT_CHARTER.md
   - REFERENCES.md
5. List of created subfolders (`active/`, `archive/`)
6. Recommended next command (default: `task-init`; verify against the directory listing before output)
7. Recommended editor mode (default: Ask)
8. Why that is the correct next step

### Task memory stays out of git
WHEN this run creates the `projects/` directory itself in the task repository, it writes `projects/.gitignore` in the same batch, holding the single line `*` (ADR-0223). That line ignores everything under `projects/`, the file included, so task memory stays out of the product repository's history without touching a file the user owns. List it `APPLIED` in `### Artifact changes`.
- Never edit the repository's own `.gitignore`.
- Never write `projects/.gitignore` into a `projects/` that already exists. A user who deleted it chose to track the tree.
- Write it outside a git repository too, so a later `git init` inherits the rule.
### Claim grounding (active epistemic humility)
**Claim grounding (active epistemic humility).** This block governs what you may assert and how you record it. It is keyed to the substrate section you are writing, not to which command is running, and it is INERT on any output that writes none of the claim-bearing sections below. Full contract and rationale: `wos/active-epistemic-humility.md`.

1. When this applies. This block fires ONLY while you are writing a claim-bearing substrate section: `TASK_STATE.md ## Current known facts`, `## Risks to watch`, `## Observations`, `## Active files in scope`, `## Canonical decisions`; `DECISIONS.md ## Locked decisions`; `IMPLEMENTATION_PLAN.md ## Current gaps`, `## Risks and mitigations`; `IMPACT_ANALYSIS.md`; `EXTERNAL_RESEARCH.md`; `REFERENCES.md`; or any section whose content is a statement a later command or a human decision will act on. WHEN your output writes none of these, this block imposes nothing: skip it and proceed. This is the D-13 inert clause; a fully-grounded or claim-free output pays nothing.

2. The unit is the load-bearing claim. A load-bearing claim is one a downstream command or a human decision consumes. A passing aside is not load-bearing; a statement someone will act on is. Apply the rest of this block per load-bearing claim, not per sentence.

3. Ground it or abstain. Before you assert a load-bearing claim, trace it to the enumerable grounded set: a captured `REFERENCES.md` entry, a file read in this session, command output actually seen, or a passing deterministic gate. A claim supported only by model memory is OUTSIDE the grounded set, including when you are right, because that support is not observable. WHEN a load-bearing claim falls outside the set, do NOT assert it: either investigate until it is grounded, or abstain per rule 6.

4. Status records provenance, never confidence. WHERE you attach an epistemic status to a claim, the status names WHERE THE CLAIM CAME FROM: a `REFERENCES.md` entry title, a file path plus line, or the gate output it came from. It SHALL NOT express a degree of certainty. Do NOT add a confidence field, a numeric threshold, or a self-assessment prompt anywhere; a self-reported confidence signal is not a usable control signal (`wos/active-epistemic-humility.md` Part 1.3). A status whose referent slot is empty is read as UNKNOWN, not as a weak yes.

5. Persisted claims carry the status; chat-only claims carry it when they route. Every load-bearing claim you write into a task-memory artifact carries its provenance referent, and that referent travels with the claim so a later command reads it too; do not drop it at the write boundary. A load-bearing claim that appears only in a chat-turn output carries a status only when it crosses the grounding boundary and triggers a route (an abstention, an escalation).

6. Abstain as a routed continuation, never a bare refusal. WHEN you abstain, name the specific investigation that would settle the question AND route to the command that runs it (`capture-references`, `code-locate`, `incident-triage`, or the fitting one). A withholding that stalls the work is invalid output. Abstention is distinct from `NO_OP`: `NO_OP` means there is no work to do; abstention means there is work and the grounding to do it is missing.

7. An unfired gate is not evidence. The absence of a fired check does not mean grounding existed. Do not read silence here as a pass.
### Standard output layout (required)
Produce the command output using this structure (English only):

### Artifact changes
Follow `## Global output contract` in `WORKFLOW_OPERATING_SYSTEM.md` for `APPLIED` / `PROPOSED` / `SKIP` rules. Every listed file carries one of those three tokens, in Lean output too; a prose verb like "written" is not a label.

### Command transcript
- Keep this section operational and brief; do not restate file content already listed in `### Artifact changes`.
- Max 4 lines in normal runs.
- Max 3 lines in no-op runs (including `NO_OP_TRACE`).
- Include `NO_OP_TRACE` (1-3 lines) when this run is a no-op (for example, the project folder already exists, in which case route the user to `task-init` or `capture-references` instead).

### Handoff
Use the adaptive ending format of `WORKFLOW_OPERATING_SYSTEM.md` `## Global output contract`. Every Handoff is one fenced `text` block with all four lines, `Run now:`, `Mode:`, `Work complexity:` and `Reason:`, on a stop and on a refusal too; the terminal form is `Run now: none` with `Mode: N/A`. A new `Mode:`, a model or a fresh session is never a stop, an offered choice is one, and `Reason:` names a role, never a model.
### Definition of done (command output)
- Resolved project path is explicit and naming rules are satisfied.
- Both mandatory files (`PROJECT_CHARTER.md`, `REFERENCES.md`) are emitted with the full structure specified in `Files to generate`. Missing or partial files invalidate the run; placeholders are required where facts are unknown but the file itself must exist.
- No task folder is created by this command (no `active/YYYY-MM-DD_<task-slug>/`).
- When the user provided 2 or more repositories, `PROJECT_CHARTER.md` includes the `## Repositories` block with N entries (each: identifier, path, base branch, role) per the schema in the spec `## Multi-repo support (v1)`; identifiers are lowercase, hyphenated, and unique. When the user provided 1 or zero repositories, the `## Repositories` block is omitted and `## Default workspace` records the single known path or a placeholder.
- `### Artifact changes` marks project-memory writes `APPLIED` in every mode. ADR-0199 removed the mode gate for task memory on the grounds that writing a few files under the gitignored `projects/` tree is internal and reversible, and the same holds here. It matters more here: the next `task-init` reads `PROJECT_CHARTER.md` to seed the task, and a charter left `PROPOSED` is not on disk, so the task would start unbootstrapped (ADR-0215).
- The basename in the `Run now:` line corresponds to a real file in `commands/<name>.md` or `commands/<name>/SKILL.md`. The default next step is `task-init`; alternative next steps are `capture-references` or `what-next`. In installed mode use the available Fhorja inventory.
- Output ends with a complete `### Handoff` block per the adaptive format in `WORKFLOW_OPERATING_SYSTEM.md` `## Global output contract`.
- Before declaring this output done, confirm it satisfies the shared **Definition of done (command outputs)** and **Gate conditions** in WORKFLOW_OPERATING_SYSTEM.md.

Quality bar:
Optimize for clean project initialization, low ambiguity at the project level, durable memory shared across all future tasks, and strict alignment with the official task repository structure.