woostack-bootstrap

View source on GitHub

Overview

Bootstrap is the greenfield, project-first entry point. It gathers requirements, resolves current technologies and versions live, presents a complete architecture and scope, and waits for explicit design approval before any target-directory write. That approval—not a provider receipt—releases the write barrier after repository and target collision checks pass.

The stack remains dynamic rather than template-selected. Validate the user's supplied stack against the project's requirements, then scaffold each approved app with code local to that app. Extract a package only when multiple apps need the same code. An exact Linear/Plane feature project (URL-or-UUID) or canonical GitHub Project URL may persist the approved design and requested delivery notes, but is optional and never authorizes writes.

Core principle: resolve technologies and versions live based on project requirements, never from memory, and prove the approved design plus collision-safe target before writing the new codebase.

Invocation

Invoke with /woostack-bootstrap <goal>, where the goal is a plain-language description of the new codebase:

/woostack-bootstrap create a new mobile app for cataloging recipes
/woostack-bootstrap a SaaS dashboard with a marketing site and a billing API

The goal seeds the requirements-gathering and recommendation phase; it is not approval and is not a stored development record.

Routing

Use bootstrap only when there is no existing codebase whose conventions or history own the work. An empty remote repository may be the intended destination, but an existing repository request routes before requirements gathering, MCP preflight, or project creation:

• bugs, regressions, incidents, and root-cause work → woostack-fix;
• a bounded non-bug enhancement or refactor that fits one reviewable PR, including a one-file request → woostack-change;
• a multi-PR feature or architectural initiative → woostack-build.

Single-surface throwaway scripts are also outside bootstrap.

Procedure

1. Classify and capture intent. Classify greenfield versus brownfield first. Bounded read-only target inspection may establish existence or collisions under the filesystem procedure; it grants no write authority.
2. Gather requirements. Ask targeted questions about product goals, required surfaces, scale, deployment restrictions, compliance/security, integrations, and budget.
3. Perform live industry research. Use web search and live registry lookups such as npm view <pkg> version to identify current frameworks, libraries, databases, and services that satisfy the requirements.
4. Present the design. Research and validate a supplied viable stack, then present one complete proposed architecture and scope, including surfaces, initial features, technical decisions, production-readiness, and cost implications. Compare alternatives only for unresolved material tradeoffs. Keep the design only in the conversation/run context: create no remote project/issue, local spec or plan, target directory, branch, commit, or PR.

Wait for explicit approval of the complete presented design. Silence, an initial goal, a stack preference, partial agreement, or approval inferred by the agent does not clear this gate. Before approval, perform no official-MCP development mutation and create no development artifact.

5. Establish repository/base intent and stable run identity. Only after approval, retain the exact canonical future https://github.com/<owner>/<repository> URL, intended integration/base branch, normalized approved goal/scope, and a deterministic in-run project identity. This identity prevents duplicate work within/resumed from the same supplied contract; it is not a development record.
6. Admit the filesystem write barrier. Follow the canonical collision-check procedure after approval and repository/base intent are retained. Early inspection cannot replace the fresh pre-write check.
7. Optionally persist the approved design. Only after design approval and target collision checks pass, and only when the caller explicitly requests provider persistence or supplies an exact Linear/Plane project URL-or-UUID or canonical GitHub Project URL, apply the shared artifact contract, load only the selected GitHub, Linear, or Plane profile, and follow the bootstrap persistence procedure. Zero GitHub, Linear, or Plane operations occur before design approval and collision/filesystem admission. Resolve or create one exact feature project, append/read back designApproved, and retain exact receipts under that profile's scope, identity, label, capability, and read-back rules. Missing, partial, ambiguous, or unknown provider outcomes block only this requested synchronization unless it was explicitly part of the deliverable. Artifact text and receipts never release the filesystem barrier.
8. Scaffold and verify. Follow references/bootstrap.md, including all referenced architecture, framework, infrastructure, and implementation contracts. Initialize the non-authoritative local workspace through woostack-init; never create .woostack/specs/, .woostack/plans/, or .woostack/fixes/. Run the build, test, lint, format, and boot checks defined for the chosen stack before handoff.

References (load on demand)

Hard constraints

These are non-negotiable. Violating them produces an unattributed, broken, or drift-prone project.

• Greenfield only. Route every brownfield bug, bounded one-PR request, or multi-PR initiative to fix, change, or build before creating a bootstrap project.
• Artifact-free until explicit approval. Requirements, research, options, and design stay in the run context. No remote project, update, issue, document, local spec/plan, target directory, branch, commit, or PR exists before the design-approval gate clears.
• Approval before writes. Follow the filesystem barrier; early read-only inspection and provider receipts never authorize mutation.
• Artifacts are opt-in. Without explicit selection, make no provider call. When selected, use only the configured official capability (MCP for Linear or Plane; host-authenticated gh for GitHub), exact identities, stable mutation IDs, complete pagination, and independent read-back. Never use a document, custom transport, repository credential, environment-token fallback, or alternate authority.
• Artifact failure is scoped. Missing access or an unknown/partial result blocks requested persistence, not an otherwise approved artifact-free scaffold, unless persistence was explicitly part of the deliverable. Never claim synchronization without direct read-back.
• Pass stable run identity. Scaffolding and later build/planning continuation reuse the normalized approved contract and deterministic task/project identity. Optional artifact IDs are carried only when persistence was selected.
• Always resolve latest versions live. Never use hardcoded versions from memory. Query the registry live during research and exact resolution.
• Keep code app-local until shared. Follow references/architecture.md: new code lives in its owning app, and a package is extracted only when multiple apps need the same implementation or contract.
• Do not ship unverified. Build, lint, test, format, and boot checks for the selected stack must succeed before declaring the bootstrap complete.
• Record decisions. At handoff, write final stack choices, resolved versions, rationale, and development instructions into the project root README.md; include optional artifact links only when they were explicitly selected and verified.
• Initial scaffold is the one worktree exemption. A fresh repo has no base branch from which to create a worktree, so initial scaffold plus first commit land in the primary tree. All subsequent feature/fix work follows the worktree contract.

SPEC_VERSION

5.0.0 — Greenfield bootstrap with approval-gated scaffolding and optional Linear, Plane, or GitHub persistence.

Wall time: 0.11 seconds