project-bootstrap

Project Bootstrap

Use this skill to make a project ready for sustained multi-agent work across Codex, Claude Code, and OpenCode. The output is a shared project operating system: Beads for task state and audit records, AGENTS.md and CLAUDE.md for always-on guidance, reference rule docs for deeper policy, and optional RepoPrompt/Entire/agent-browser integration notes.

First: Decide Whether You Know Enough

If the user already gave the project purpose, core goals, expected quality bar, and collaboration model, proceed. If any of those are unclear, run a progressive interview before writing project-specific files.

Ask one question at a time, then summarize what you learned before asking the next question. The interview is not a form; use it to brainstorm, narrow scope, and discover the documents the project needs. Good interview areas:

• Project purpose and target users.
• Initial product scope and later expansion scope.
• Main agent roles for the project.
• Next meaningful milestone and success criteria.
• Build, test, lint, benchmark, or manual verification commands.
• Whether the local Git repo should also get a remote on GitHub or GitLab.
• Domains, files, tools, audiences, or workflows agents should avoid.

Do not run a generic bootstrap when the project purpose is unknown. AGENTS.md and CLAUDE.md should anchor the actual project, not a placeholder. For early projects, create context documents that let future agents restart from the current concept without rereading the whole conversation.

Operating Principles

Start from live state. Run pwd, detect the Git root if present, inspect existing AGENTS.md, CLAUDE.md, .beads/, .opencode/, .claude/, and current dirty state before changing anything.

Decontaminate a copied harness layer before bootstrapping. A .claude/, .codex/, or .opencode/ directory is often copied from another project as a starting point. When it is, it carries the previous project's identity, and layering new content on top leaves a hybrid that misroutes agents. Before writing, check whether any existing harness surface names a DIFFERENT project:

• */settings.json identity. Inspect .claude/settings.json (and any .codex//.opencode/ settings) for a project.name/description or a skills: array that references another project. A name that does not match this project, or a skills list scoped to a different pipeline, is a copied layer.
• Stray */rules/* files. Look for .claude/rules/* (or the equivalent under .codex//.opencode/) describing another project's pipeline, conventions, or contracts. These belong to the source project, not this one.
• A foreign README.md. A .claude/README.md (or equivalent) that describes another project's purpose is a copied artifact.

Reconcile or flag what you find; never blind-delete user content. Update project.name/description to this project, prune or rewrite a stale skills: array, and surface any stray rules/* or README.md to the user with a recommendation (keep, rewrite for this project, or remove) before proceeding. The bundled script runs this scan automatically and reports findings under decontamination in its JSON report; treat any mismatch there as a required reconciliation step, not an optional one.

Keep the setup project-local. Do not widen to a parent repo unless the user explicitly names that boundary.

Use Beads as the source of task truth. Do not create competing markdown TODO systems. For issue state, use bd prime, bd ready, bd show <id>, bd update <id> --claim, bd close <id>, and bd remember.

Use Entire for historical intent when available. Check entire status before explaining unfamiliar code or continuing past work. Label checkpoint-backed facts separately from code inference.

Use three-agent coordination for substantial work: orchestrator, executor, and reviewer. The orchestrator must define success criteria, acceptance criteria, scope boundaries, and verification evidence before dispatching executors. The reviewer audits against those criteria rather than inventing a new target.

Use RepoPrompt/rp-cli when available as a planning, soundboard, and final QA gate. Verify the correct RepoPrompt window/root first with rp-cli -e 'windows' and rp-cli -w <id> -e 'tree --type roots'.

Use agent-browser for browser automation, UI smoke checks, screenshots, and web workflows that need interaction. Browser automation must be canonical and resource-bounded: use one explicit named session per target or work lane (agent-browser --session <project-or-target> open <url>), do not use the default session for project work, do not use --auto-connect unless the task is explicitly about importing state from the user's browser, and do not mix in Chrome DevTools MCP or other browser controllers unless the user explicitly chooses that path. For multi-agent research, the orchestrator owns the browser budget: normally at most two live browser sessions at a time, each with a clear target URL and cleanup instruction. Close named sessions when done and verify with agent-browser session list. If a browser window shows an unrelated site or stale profile state, stop and reset the named session before continuing.

Initialize local Git as part of bootstrap when no .git/ exists. After local Git exists, ask the user whether they want a private remote on GitHub, GitLab, both, or neither. Check gh and glab availability and authentication before creating remotes. Do not assume both CLIs are installed.

Bootstrap Workflow

1. Orient

   pwd
   git rev-parse --show-toplevel 2>/dev/null || true
   git status --short --branch 2>/dev/null || true
   command -v bd beads opencode claude codex entire agent-browser rp-cli 2>/dev/null || true
   command -v git gh glab 2>/dev/null || true
   gh auth status 2>/dev/null || true
   glab auth status 2>/dev/null || true
   

2. Inspect existing guidance and check for a copied harness layer

   find . -maxdepth 3 \( -name AGENTS.md -o -name CLAUDE.md -o -path './.beads' -o -path './.opencode' -o -path './.claude' \) -print
   bd where 2>/dev/null || true
   bd status --json 2>/dev/null || true
   # Decontamination scan: does an existing harness layer name another project?
   grep -nE '"(name|description)"|^\s*skills:' .claude/settings.json .codex/settings.json .opencode/settings.json 2>/dev/null || true
   ls .claude/rules .codex/rules .opencode/rules .claude/README.md 2>/dev/null || true
   

   See "Decontaminate a copied harness layer" under Operating Principles. The bootstrap script (step 4) also runs this scan and reports findings under decontamination in its JSON output. Reconcile any mismatch before relying on the bootstrapped layer.

3. Write down success criteria before setup State the project purpose, agent roles, build/test commands, acceptance criteria, and goal-achievement definition in your own words. If the user has not supplied enough detail, ask the interview questions above.

4. Run the bundled bootstrap script From this skill directory:

   python scripts/bootstrap_harnesses.py \
     --project-root /absolute/path/to/project \
     --project-name "Project Name" \
     --purpose "What this project is for" \
     --goal "First major goal" \
     --benchmark-url "https://example.com/reference-product" \
     --context-note "Important project fact or scope boundary" \
     --remote-provider github \
     --repo-name "repo-name" \
     --remote-visibility private \
     --test-command "command to verify behavior"
   

   Add --dry-run to preview without writing. Add repeated --goal, --build-command, or --test-command flags as needed.

5. Verify

   git status --short --branch
   git remote -v
   bd where
   bd setup codex --check
   bd setup claude --check
   bd setup opencode --check
   agent-browser session list 2>/dev/null || true
   test -f AGENTS.md
   test -f CLAUDE.md
   test -f docs/agent-rules/orchestration.md
   test -f .beads/interactions.jsonl
   

6. Report Use this concise report shape:

   **Bootstrap Complete**
   Project: <path>
   Harnesses: Codex <ok/missing>, Claude Code <ok/missing>, OpenCode <ok/missing>
   Git: local <initialized/existing>, remote <github/gitlab/none>
   Beads: <initialized/existing>, audit <recorded/missing>
   Rules: <list key docs>
   RepoPrompt: <available/unavailable/not configured>
   Verification: <commands run and result>
   Next: <first bd issue or next setup step>
   

What The Script Creates

• AGENTS.md: shared guidance for Codex and OpenCode.
• CLAUDE.md: matching guidance for Claude Code.
• docs/agent-rules/mission.md: project purpose, goals, and constraints.
• docs/agent-rules/operating-principles.md: autonomy, TDD, commits, and work discipline.
• docs/agent-rules/toolchain.md: Beads, Entire, RepoPrompt, agent-browser, and harness-specific commands.
• docs/agent-rules/orchestration.md: orchestrator/executor/reviewer loop.
• docs/agent-rules/success-criteria.md: acceptance criteria and final QA.
• docs/project-context/kickoff-context.md: project concept, audience, and scope captured during the interview.
• docs/project-context/benchmark-targets.md: reference products or sites to inspect during discovery.
• docs/project-context/discovery-questions.md: open questions for future brainstorming and benchmarking.
• .opencode/agents/project-orchestrator.md, .opencode/agents/project-executor.md, and .opencode/agents/project-reviewer.md.
• .claude/agents/project-orchestrator.md, .claude/agents/project-executor.md, and .claude/agents/project-reviewer.md.

Safety Notes

The script updates managed blocks in AGENTS.md and CLAUDE.md instead of deleting unrelated content. For generated role/rule files, it writes the project-specific bootstrap content and records changed paths in its final report. Existing Beads databases are reused, not reinitialized.

The decontamination scan is advisory and read-only: it reports a copied harness layer under decontamination in the JSON report but never edits or deletes the flagged files. Reconciling a foreign project.name, stale skills: array, stray rules/*, or a copied README.md is a deliberate follow-up step, taken with the user's knowledge rather than silently.

If setup fails partway through, inspect the JSON report, fix the concrete missing command or permission problem, and rerun the script. It is designed to be idempotent.