bootstrap-repo

Bootstrap Repo

Initialize a repository with a useful README.md and the standard agent workflow docs. When invoked with --reset-existing, first archive stale implementation and documentation files from a non-empty stuck repo so the fresh start is not built on old code or old assumptions by accident.

Process

1. Parse the project brief and mode from $ARGUMENTS:

   • Detect --reset-existing, --in-place-reset, or an explicit request to archive/reset the current codebase before bootstrap.
   • Extract the project name, purpose, setup instructions, run/test commands, and any constraints.
   • If the brief is missing or too thin to write a useful README, ask for the project name and one-sentence purpose. Ask for setup or run instructions only when the repository does not make them discoverable.

2. Inspect the target repository:

   • Read existing README.md, CLAUDE.md, AGENTS.md, package manifests, obvious build files, and directory names.
   • Preserve discovered commands and facts. Do not invent dependency managers, deployment targets, or product claims.

3. Reset existing stale repo when explicitly requested:

   • Only perform this step when reset mode is explicit. Never archive or move files during ordinary bootstrap.
   • Confirm the repo is non-empty and contains stale implementation, docs, research, specs, task files, design notes, or generated app structure. If it is already empty or freshly initialized, skip archival and note why.
   • Create archive/YYYY-MM-DD-HHMMSS/ and move stale implementation and documentation files/directories there before writing fresh bootstrap docs.
   • Archive old docs by default, including docs/, alignment/, research/, specs/, tasks/, planning reports, implementation notes, design docs, old README content, and prior roadmap/todo/history files. These may remain useful as historical evidence in the archive, but they must not stay active as source-of-truth inputs.
   • Do not archive .git/, .agents/, archive/, desk-flip-report.md, root agent config files needed for the current session, or the newly written high-level concept artifact.
   • Preserve exactly one active concept seed, such as concept.md or README.md ## Concept, derived from the bootstrap brief or desk-flip-report.md. Keep it high level: product name, target user, core problem, value proposition, non-goals, and open questions. Do not preserve old research/spec detail as active files.
   • Preserve a manifest at archive/YYYY-MM-DD-HHMMSS/MANIFEST.md listing every moved path, every intentionally preserved path, and the high-level concept source that justified the reset.
   • Prefer git mv for tracked paths so history remains understandable. Use ordinary moves only for untracked paths.
   • Do not delete old files outright. If a path cannot be moved safely, stop and report the blocker instead of partially resetting further.
   • After archival, the root should contain only the fresh-start sources of truth: git metadata, agent config, the archive directory, desk-flip-report.md, the high-level concept artifact, and any newly written bootstrap docs. Old docs/research/specs belong in the archive.

4. Create or update README.md:

   • If README.md is absent, empty, or placeholder-like, write a concise README with:
     • # <Project Name>
     • A short purpose summary.
     • ## Getting Started
     • ## Development
     • ## Notes
   • If README.md already has substantial content, preserve it. Ask before replacing it; otherwise add a small bootstrap section only when it improves the file.
   • Use the project brief as the primary source and repository inspection as supporting evidence.

5. Provision agent workflow docs:

   • Run /provision-agentic-config for the same repository.
   • Confirm CLAUDE.md and AGENTS.md exist after provisioning.
   • Preserve unrelated existing content in both files.

6. Verify the result:

   • Check that README.md, CLAUDE.md, and AGENTS.md exist.
   • Confirm the corresponding workflow orchestration block appears exactly once in each of CLAUDE.md and AGENTS.md.
   • Report whether the monorepo safety block was included or skipped by /provision-agentic-config.
   • In reset mode, check that archive/YYYY-MM-DD-HHMMSS/MANIFEST.md exists and lists moved and preserved paths, and verify old docs/research/specs/tasks were archived rather than left active.

7. Route research-first after product bootstrap:

   • If this is a product, app, SaaS, dashboard, internal tool, marketplace, website, or other user-facing restart, rebuild market and lifecycle alignment from the high-level concept before UI requirements or prototypes.
   • Check .agents/project.json.enabled_packs when present. If business-discovery is not enabled, recommend /pack install business-discovery before /icp. If customer-lifecycle is not enabled, include /pack install customer-lifecycle before /journey-map.
   • When required packs are available, recommend /icp <concept> as the next command. After /icp, the intended sequence is /competitive-analysis -> /journey-map -> /ux-variations -> /ui-interview -> prototype work.
   • If current, accepted research/icp.md, research/competitive-analysis.md, and research/journey-map.md already exist from the fresh reset, then recommend /ux-variations <topic>.
   • If UX variations already exist but interface details are missing, recommend /ui-interview <topic>.
   • Only route directly to /roadmap or /exec when the project is non-UI/non-product work or already has accepted alignment artifacts and a consolidated prototype.
   • The intended product sequence after reset is: /icp -> /competitive-analysis -> /journey-map -> /ux-variations -> /ui-interview -> build variants/prototypes via /exec or the applicable prototype-building route -> /uat --variant-evaluation -> /consolidate-variations -> /research-roadmap --post-prototype -> /spec-interview or /roadmap.

Output

Bootstrapped repository
- README.md: [created | updated | preserved], source: [arguments | prompts | existing content]
- Reset archive: [created archive/YYYY-MM-DD-HHMMSS | skipped (<reason>)]
- Active concept seed: [concept.md | README.md ## Concept | other]
- CLAUDE.md: [created | updated | unchanged], corresponding workflow block appears once
- AGENTS.md: [created | updated | unchanged], corresponding workflow block appears once
- Monorepo safety block: [included (<heuristic>) | skipped]
- Verification: [commands/checks run]
- Recommended next command: [/pack install business-discovery | /pack install customer-lifecycle | /icp <concept> | /ux-variations <topic> | /ui-interview <topic> | /roadmap | /exec]

Constraints

• Do not overwrite substantial existing README.md content without explicit user confirmation.
• Do not invent setup, test, deploy, or architecture details that are not in the brief or repository.
• Keep the README concise and useful for a new contributor.
• Do not modify files other than README.md, CLAUDE.md, and AGENTS.md unless the user explicitly asks or invokes reset mode.
• Reset mode may move stale files, including old docs/research/specs/tasks, into archive/YYYY-MM-DD-HHMMSS/ and write that archive's MANIFEST.md; it may not delete files outright.
• In reset mode, do not preserve old docs as active files just because they were marked salvageable. Use them only as archived historical evidence; active research and requirements restart from the high-level concept.
• Do not create, modify, or suggest GitHub Actions workflows.

Default Shipping Contract

Follow the shared shipping contract convention in CLAUDE.md.