cfsa-antigravity 2.12.0 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfsa-antigravity",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "CFSA Pipeline — Constraint-First Specification Architecture for AI agents. Production-grade from line one.",
   "scripts": {
     "changeset": "changeset",

package/template/.agent/kit-sync.md

@@ -1,6 +1,6 @@
 # Kit Sync State
 
 upstream: https://github.com/RepairYourTech/cfsa-antigravity
-last_synced_commit: bf1e196564da7c037996f8e3422994f36dbc014e
-last_synced_at: 2026-03-20T00:52:40Z
-kit_version: 2.12.0
+last_synced_commit: e9b6470d468da13d41cd388d9c569146d173418e
+last_synced_at: 2026-03-20T01:29:38Z
+kit_version: 2.13.0

package/template/.agent/skills/prd-templates/references/skill-loading-protocol.md

@@ -24,6 +24,10 @@ Standard procedure for loading skills from the surface stack map before beginnin
 | `write-be-spec-classify` | Languages, Databases, Auth, BE Frameworks, ORMs, Unit Tests |
 | `write-fe-spec-classify` | Languages, FE Frameworks, FE Design, Accessibility, State Mgmt |
 | `write-architecture-spec-design` | Databases, Security, API Design |
+| `setup-workspace-scaffold` | Languages, BE Frameworks, FE Frameworks |
+| `setup-workspace-cicd` | CI/CD, Languages |
+| `setup-workspace-hosting` | Hosting, CI/CD |
+| `setup-workspace-data` | Databases, ORMs |
 | `implement-slice-tdd` | Languages, Unit Tests, E2E Tests |
 | `validate-phase` | Unit Tests, E2E Tests, CI/CD, Hosting, Accessibility, Security |
 

package/template/.agent/workflows/plan-phase-write.md

@@ -82,10 +82,14 @@ Sort slices so each builds on the last:
 
 **Phase 1 special rule**: Before applying this rule, read the surface stack map from `.agent/instructions/tech-stack.md` and verify that the **CI/CD** and **Hosting** cross-cutting categories have filled values. If empty, emit a **HARD STOP**: these are filled by `/create-prd-stack` — run it first.
 
-The `00-infrastructure` shard is always the first slice. Verify it covers: (1) CI/CD pipeline setup — read the CI/CD skill(s) from the cross-cutting section of the surface stack map, (2) environment configuration (`.env.example`), (3) deployment pipeline — read the Hosting skill(s) from the cross-cutting section of the surface stack map, (4) project scaffolding from `.agent/instructions/structure.md` (directories, `README.md` files, base configs), (5) database initialization. Add missing items before proceeding.
+The `00-infrastructure` shard is always the first slice. It covers only **TDD-able application code**: (1) health check endpoint, (2) error handling middleware with structured error responses, (3) logging middleware, (4) structured response envelope, (5) auth middleware stubs (BOUNDARY if auth spec not yet written). Operational setup (CI/CD, hosting, database provisioning, project scaffolding) is handled by `/setup-workspace` which runs before any `/implement-slice`.
+
+> [!IMPORTANT]
+> `/setup-workspace` MUST be run and pass `/verify-infrastructure` BEFORE the first `/implement-slice`. If the workspace has not been set up, emit a **HARD STOP**: "Run `/setup-workspace` first — operational infrastructure must be in place before any TDD slice."
 
 **Verification gates** (hard gates — add explicitly to the phase plan):
-- `/verify-infrastructure` MUST pass after the infrastructure slice, before any feature slice.
+- `/verify-infrastructure` MUST pass after `/setup-workspace`, before any implementation slice.
+- `/verify-infrastructure` MUST pass after the infrastructure code slice, before any feature slice.
 - `/verify-infrastructure` MUST pass again after the auth slice (with auth smoke test), before any auth-dependent feature slice.
 
 - Core entity CRUD second

package/template/.agent/workflows/setup-workspace-cicd.md

@@ -0,0 +1,137 @@
+---
+description: CI/CD pipeline configuration, stages, secrets, and multi-service matrix builds for the setup-workspace workflow
+parent: setup-workspace
+shard: cicd
+standalone: true
+position: 2
+pipeline:
+  position: 8.52
+  stage: setup
+  predecessors: [setup-workspace-scaffold]
+  successors: [setup-workspace-hosting]
+  skills: [git-workflow, workflow-automation]
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Setup Workspace — CI/CD
+
+Create the CI/CD pipeline configuration with lint, type-check, test, and build stages. Gate: pipeline runs to completion (tests may fail — no application code exists yet, but the pipeline itself must execute).
+
+**Prerequisite**: Project scaffolded (dev server starts). Surface stack map CI/CD cell populated.
+
+---
+
+## 1. Load CI/CD skill
+
+Read `.agent/skills/prd-templates/references/skill-loading-protocol.md`.
+
+Load the CI/CD skill from the cross-cutting section of the surface stack map (`.agent/instructions/tech-stack.md`).
+
+Read the loaded skill's `SKILL.md` (e.g., `.agent/skills/github-actions/SKILL.md`).
+
+If the skill is not installed, check `.agent/skill-library/MANIFEST.md` and provision it. If not in the library, read `.agent/skills/find-skills/SKILL.md` for discovery.
+
+---
+
+## 2. Determine pipeline architecture
+
+Read `docs/plans/*-architecture-design.md` for the architecture pattern.
+
+| Pattern | Pipeline Strategy |
+|---------|------------------|
+| **Monolith** | Single pipeline, all stages sequential |
+| **Monorepo** | Matrix or multi-job: each workspace gets lint/test/build; shared deploy stage |
+| **Multi-repo** | Each repo has its own pipeline (scaffold shard already created separate repos) |
+
+For **monorepo**, determine the CI/CD platform's workspace detection mechanism:
+- GitHub Actions: `paths` filter per workspace, or matrix with `workspace` variable
+- GitLab CI: `rules: changes` per directory
+- Other: consult the loaded CI/CD skill
+
+---
+
+## 3. Create pipeline configuration
+
+Using the CI/CD skill's patterns, create the pipeline config file:
+
+### Required stages (in order)
+
+| Stage | What | Fails On |
+|-------|------|----------|
+| **Install** | Install dependencies | Dependency resolution failure |
+| **Lint** | Run linter | Any lint violation |
+| **Type Check** | Run type checker (if applicable) | Any type error |
+| **Test** | Run test suite | Any test failure |
+| **Build** | Production build | Build failure |
+
+Read `.agent/instructions/commands.md` for the exact commands for each stage.
+
+### Pipeline config requirements
+
+1. **Trigger**: Push to main + pull request to main
+2. **Caching**: Cache dependency directories (e.g., `node_modules`, `.cargo`, `__pycache__`) — follow CI/CD skill caching patterns
+3. **Runtime version**: Pin the language runtime version (from surface stack map Languages row)
+4. **Timeout**: Set reasonable timeouts per stage (5 min lint, 10 min test, 10 min build)
+5. **Artifact upload**: Upload build artifacts for deployment stages
+
+For **monorepo** with matrix strategy, add a `strategy.matrix` (or equivalent) that iterates over workspaces.
+
+---
+
+## 4. Configure CI/CD secrets
+
+Enumerate all secrets needed by the pipeline:
+
+1. Read `.env.example` — identify variables that are secrets (API keys, tokens, connection strings)
+2. Read `docs/plans/*-architecture-design.md` integration section — identify external service credentials
+3. Read the Hosting skill — identify deployment credentials
+
+For each secret:
+- Document it in the pipeline config as a required secret/variable
+- Add a comment explaining where to obtain the value
+- **Do NOT hardcode any secret values** — reference platform secret storage only
+
+Present the secrets list to user: "These CI/CD secrets need to be configured in [platform]: [list with descriptions]. Please add them now or after this workflow completes."
+
+> [!CAUTION]
+> Never write actual secret values into any file. Only reference secret names using the CI/CD platform's secret syntax (e.g., `${{ secrets.DATABASE_URL }}` for GitHub Actions).
+
+---
+
+## 5. Multi-service pipeline specialization
+
+For **monorepo** projects, ensure the pipeline handles:
+
+1. **Change detection**: Only run stages for workspaces with changed files
+2. **Dependency order**: If service A depends on service B, build B first
+3. **Shared libraries**: If a shared library changes, rebuild all dependent services
+4. **Independent deploy**: Each service can deploy independently
+
+For **multi-repo** projects: this step is N/A — each repo has its own pipeline created during scaffold.
+
+---
+
+## 6. Verification gate
+
+1. Commit the pipeline configuration: `chore: add CI/CD pipeline configuration`
+2. Push to trigger the pipeline
+3. Wait for the pipeline to start executing
+4. Verify all stages **execute** (not necessarily pass — tests will fail because no test files exist yet, but lint, type-check, and build should pass on the scaffolded project)
+
+**Expected results for a freshly scaffolded project:**
+
+| Stage | Expected |
+|-------|----------|
+| Install | ✅ Pass |
+| Lint | ✅ Pass (no source files to lint, or default files pass) |
+| Type Check | ✅ Pass |
+| Test | ⚠️ May fail (no tests exist yet) or ✅ pass (0 tests) |
+| Build | ✅ Pass |
+
+**If Install, Lint, Type Check, or Build fail** → **STOP.** Debug the pipeline config before proceeding.
+
+**Pass criteria**: Pipeline executes all stages. Install, Lint, Type Check, and Build pass. Test stage exits (pass or "no tests found" is acceptable).
+
+> Present result to user: "✅ CI/CD pipeline running. [N] stages executing. Proceeding to hosting setup." or "❌ Pipeline failed at [stage]: [error]. Fix required."

package/template/.agent/workflows/setup-workspace-data.md

@@ -0,0 +1,169 @@
+---
+description: Database provisioning, migration framework initialization, connection configuration, and seed data setup for the setup-workspace workflow
+parent: setup-workspace
+shard: data
+standalone: true
+position: 4
+pipeline:
+  position: 8.54
+  stage: setup
+  predecessors: [setup-workspace-hosting]
+  successors: [verify-infrastructure]
+  skills: [database-schema-design, deployment-procedures]
+  calls-bootstrap: false
+requires_placeholders: [ORM_SKILL]
+---
+
+// turbo-all
+
+# Setup Workspace — Data
+
+Provision database instances, initialize the migration framework, configure connection strings, and verify database connectivity. Gate: database connectable and migration framework initialized.
+
+**Prerequisite**: Hosting configured (from `/setup-workspace-hosting`). Surface stack map Databases and ORMs cells populated.
+
+---
+
+## 1. Load database and ORM skills
+
+Read `.agent/skills/prd-templates/references/skill-loading-protocol.md`.
+
+Load from the surface stack map (`.agent/instructions/tech-stack.md`):
+- **Databases** skill (e.g., PostgreSQL, MongoDB, SurrealDB)
+- **ORMs** skill (e.g., Prisma, Drizzle, SQLAlchemy)
+
+Read each loaded skill's `SKILL.md`.
+
+Also read `.agent/skills/database-schema-design/SKILL.md` for schema design principles.
+
+If a migration-management skill exists, load it too (check `.agent/skills/migration-management/SKILL.md`).
+
+---
+
+## 2. Determine database architecture
+
+Read `docs/plans/*-architecture-design.md` for the data strategy:
+
+1. **How many database instances?** Monolith typically has 1; multi-service may have per-service databases or a shared database with per-service schemas
+2. **Database engine per instance** (from architecture doc + surface stack map)
+3. **Managed vs self-hosted** — affects provisioning steps
+4. **Read replicas needed?** — typically not at setup, but note for later
+5. **Data placement strategy** — read `docs/plans/data-placement-strategy.md` if it exists
+
+| Pattern | Database Strategy |
+|---------|------------------|
+| **Monolith** | Single database instance |
+| **Monorepo shared DB** | One instance, per-service schemas or prefixed tables |
+| **Monorepo per-service DB** | One instance per service |
+| **Multi-repo** | Fully independent database per repo |
+
+---
+
+## 3. Provision database instance(s)
+
+For each required database instance:
+
+### 3a. Managed database (cloud-hosted)
+
+If using a managed service (Supabase, PlanetScale, Neon, AWS RDS, etc.):
+
+1. Create the database instance through the platform's dashboard, CLI, or API
+2. Record the connection string components:
+   - Host
+   - Port
+   - Database name
+   - Username (non-root, application-specific)
+   - Password (generated, stored in platform secrets)
+3. Configure network access rules (allow from hosting platform's IP range)
+4. Enable SSL/TLS for connections
+
+### 3b. Self-hosted database
+
+If running the database locally or on a VPS:
+
+1. Verify the database engine is installed or create a Docker Compose service
+2. Create the application database
+3. Create the application user with minimum required privileges
+4. Record the connection string
+5. Configure network access (bind address, firewall rules)
+
+> [!IMPORTANT]
+> The database user for the application should have ONLY the privileges it needs — not root/superuser access. Create a dedicated user with table-level permissions. Document the user's privileges.
+
+---
+
+## 4. Configure connection strings
+
+1. **Local development**: Add the connection string to `.env.example` with a placeholder:
+   ```
+   DATABASE_URL="postgresql://user:password@localhost:5432/myapp_dev"
+   ```
+
+2. **CI/CD**: Add the test database connection string to CI/CD secrets (from previous shard). If the CI/CD platform supports service containers (e.g., GitHub Actions services), configure a test database instance in the pipeline config.
+
+3. **Staging**: Set the connection string in the hosting platform's environment variables (from previous shard's hosting config).
+
+4. **Production**: Document the production connection string as a required secret — do not set it yet.
+
+Verify that the connection string variable name matches what the ORM/framework expects (e.g., `DATABASE_URL` for Prisma, `SQLALCHEMY_DATABASE_URL` for SQLAlchemy).
+
+---
+
+## 5. Initialize migration framework
+
+Using the loaded ORM skill:
+
+1. **Initialize the ORM/migration tool**:
+   - Prisma: `npx prisma init`
+   - Drizzle: create `drizzle.config.ts`
+   - Alembic: `alembic init`
+   - SurrealDB: create migration directory structure
+
+2. **Configure the migration tool** to read the connection string from the environment variable
+
+3. **Create the initial schema** based on `docs/plans/data-placement-strategy.md`:
+   - Create only the base tables/collections specified in the strategy
+   - Include audit fields (created_at, updated_at) as specified in `ENGINEERING-STANDARDS.md`
+   - Set up indexes for primary keys and documented unique constraints
+
+4. **Generate and run the initial migration**:
+   - Generate: `prisma migrate dev`, `alembic revision`, etc.
+   - Apply: run the migration against the local development database
+   - Verify: check migration status shows "up to date"
+
+> [!CAUTION]
+> The initial schema should reflect what's in the data placement strategy, not what you think the app needs. If the data placement strategy is incomplete, note the gap but do not invent tables.
+
+---
+
+## 6. Configure test database
+
+For CI/CD and local test runs:
+
+1. Create a separate test database (or configure the test runner to use an in-memory/ephemeral database)
+2. Configure the test environment to use the test database connection string
+3. Set up migration auto-run in test setup (so tests always run against the latest schema)
+4. Verify the test database is isolated from development data
+
+---
+
+## 7. Verification gate
+
+1. **Local connectivity**: Connect to the development database and run a simple query (e.g., `SELECT 1` or equivalent)
+2. **Migration status**: Verify migrations are applied and "up to date"
+3. **ORM connectivity**: Run the ORM's built-in connection test if available
+4. **Staging connectivity** (if staging DB is provisioned): Verify staging database is connectable from the staging environment
+
+Commit changes: `chore: configure database and migration framework`
+
+**Pass criteria:**
+
+- [ ] Database instance(s) provisioned
+- [ ] Connection strings configured for local, CI/CD, and staging
+- [ ] Migration framework initialized
+- [ ] Initial migration created and applied
+- [ ] Test database configured
+- [ ] Local database connectable
+- [ ] Migration status clean
+
+> Present result to user: "✅ Database configured. [engine] at [host]. Migrations initialized. Proceeding to infrastructure verification." or "❌ Database setup failed: [error]. Fix required."

package/template/.agent/workflows/setup-workspace-hosting.md

@@ -0,0 +1,170 @@
+---
+description: Hosting platform provisioning, domain configuration, deployment pipeline, and first staging deploy for the setup-workspace workflow
+parent: setup-workspace
+shard: hosting
+standalone: true
+position: 3
+pipeline:
+  position: 8.53
+  stage: setup
+  predecessors: [setup-workspace-cicd]
+  successors: [setup-workspace-data]
+  skills: [deployment-procedures, workflow-automation]
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Setup Workspace — Hosting
+
+Provision the hosting platform, configure domains, set up the deployment pipeline, and execute the first staging deploy. Gate: staging URL accessible with HTTP 200.
+
+**Prerequisite**: CI/CD pipeline configured (from `/setup-workspace-cicd`). Surface stack map Hosting cell populated.
+
+---
+
+## 1. Load hosting skill
+
+Read `.agent/skills/prd-templates/references/skill-loading-protocol.md`.
+
+Load the Hosting skill from the cross-cutting section of the surface stack map (`.agent/instructions/tech-stack.md`).
+
+Read the loaded skill's `SKILL.md` (e.g., `.agent/skills/vercel/SKILL.md`, `.agent/skills/aws/SKILL.md`, `.agent/skills/cloudflare/SKILL.md`).
+
+Also read `.agent/skills/deployment-procedures/SKILL.md` for deployment principles.
+
+---
+
+## 2. Determine hosting architecture
+
+Read `docs/plans/*-architecture-design.md` for deployment topology.
+
+| Pattern | Hosting Strategy |
+|---------|-----------------|
+| **Monolith** | Single deployment target (one app, one URL) |
+| **Monorepo** | Per-service deploy targets OR single deployment with routing |
+| **Multi-repo** | Each repo deploys independently to its own target |
+| **Hub-and-spoke** | Hub service + spoke services with service discovery / API gateway |
+
+For **hub-and-spoke** or **microservices**, determine:
+- Which services are public-facing vs internal-only
+- Inter-service communication method (HTTP, message queue, gRPC)
+- Whether an API gateway / reverse proxy is needed
+- Load balancing requirements
+
+---
+
+## 3. Provision hosting platform
+
+Using the Hosting skill's patterns:
+
+### 3a. Create project(s) on the hosting platform
+
+For each deployable service:
+
+1. Create the project/app on the hosting platform (e.g., `vercel project create`, Terraform apply, AWS CDK deploy)
+2. Configure the build settings:
+   - Build command (from `.agent/instructions/commands.md`)
+   - Output directory
+   - Install command
+   - Runtime version
+3. Link to the git repository (for auto-deploy on push, if the platform supports it)
+
+### 3b. Configure environments
+
+Each project needs at minimum:
+
+| Environment | Purpose | Branch |
+|-------------|---------|--------|
+| **Staging** | Pre-production testing | `main` or `staging` branch |
+| **Production** | Live traffic | `main` or release tags |
+
+If the architecture doc specifies additional environments (preview, canary), configure those too.
+
+### 3c. Set environment variables
+
+For each environment on the hosting platform:
+
+1. Read `.env.example` for the full variable list
+2. Set non-secret variables directly (e.g., `NODE_ENV=production`, `LOG_LEVEL=info`)
+3. For secrets: configure through the platform's secret management (not hardcoded)
+4. For database connection strings: these will be set after `/setup-workspace-data` — leave a placeholder comment noting this
+
+> [!IMPORTANT]
+> All secrets must go through the hosting platform's secret management system. Never hardcode secrets in build configs, environment files committed to git, or CI/CD pipeline files.
+
+---
+
+## 4. Configure domains and DNS
+
+Read `docs/plans/*-architecture-design.md` for domain requirements.
+
+If custom domains are specified:
+
+1. Configure domain on the hosting platform
+2. Set up DNS records (CNAME, A, or AAAA as required)
+3. Configure SSL/TLS (automatic via platform, or Let's Encrypt, or custom cert)
+4. Verify domain propagation
+
+If no custom domain specified: use the platform's default domain (e.g., `*.vercel.app`, `*.fly.dev`).
+
+For **multi-service**: configure subdomains or path-based routing as specified in the architecture doc.
+
+---
+
+## 5. Create deployment pipeline
+
+Integrate the hosting platform with the CI/CD pipeline created in the previous shard:
+
+1. **Add deploy stage** to the CI/CD config (after build):
+   - Staging: auto-deploy on push to main (or staging branch)
+   - Production: manual approval gate or tag-based trigger
+2. **Configure deploy credentials** in CI/CD secrets
+3. **Add health check** post-deploy step:
+   - Hit staging URL after deploy
+   - Verify HTTP 200 response
+   - If health check fails: trigger rollback
+
+Read `.agent/skills/deployment-procedures/SKILL.md` for rollback strategy patterns. Document the rollback procedure in the project's README or deployment docs.
+
+---
+
+## 6. Execute first staging deploy
+
+1. Commit deployment config changes: `chore: configure hosting and deployment pipeline`
+2. Push to trigger the CI/CD pipeline + deployment
+3. Wait for deployment to complete
+4. Verify the staging URL is accessible:
+   - HTTP GET to staging URL → expect 200
+   - Verify the response is from the scaffolded app (not a platform error page)
+
+**If deployment fails** → **STOP.** Debug using:
+1. CI/CD logs (deploy stage)
+2. Hosting platform logs
+3. Build output
+4. Environment variable configuration
+
+Common first-deploy failures:
+
+| Symptom | Likely Cause |
+|---------|-------------|
+| Build fails on platform | Missing env var, wrong build command, wrong output dir |
+| 404 on staging URL | Routing misconfiguration, wrong root directory |
+| 500 on staging URL | Missing runtime env var, wrong Node/Python version |
+| Deploy timeout | Build too slow, increase timeout or optimize |
+
+---
+
+## 7. Verification gate
+
+**Pass criteria:**
+
+- [ ] Project created on hosting platform
+- [ ] Staging environment configured
+- [ ] Environment variables set (non-secret)
+- [ ] Secret placeholders documented
+- [ ] Deployment pipeline integrated with CI/CD
+- [ ] First staging deploy succeeded
+- [ ] Staging URL returns HTTP 200
+
+> Present result to user: "✅ Hosting configured. Staging at [URL]. Proceeding to database setup." or "❌ Hosting failed: [error]. Fix required."

package/template/.agent/workflows/setup-workspace-scaffold.md

@@ -0,0 +1,157 @@
+---
+description: Project initialization, directory structure, dependencies, and base configurations for the setup-workspace workflow
+parent: setup-workspace
+shard: scaffold
+standalone: true
+position: 1
+pipeline:
+  position: 8.51
+  stage: setup
+  predecessors: [plan-phase]
+  successors: [setup-workspace-cicd]
+  skills: [git-workflow, clean-code]
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Setup Workspace — Scaffold
+
+Initialize the project, create the directory structure, install dependencies, and configure the development environment. Gate: the dev server starts without errors.
+
+**Prerequisite**: Phase plan and architecture-design.md must exist. Surface stack map must have Languages row populated.
+
+---
+
+## 1. Read architecture pattern
+
+Read `docs/plans/*-architecture-design.md` and determine:
+
+1. **Architecture pattern**: monolith / monorepo / multi-repo
+2. **Service list**: enumerate every service/package (for monolith: just one)
+3. **Language per service**: from the surface stack map in `.agent/instructions/tech-stack.md`
+
+If multi-service, present the list to the user: "I'll scaffold these services: [list]. Correct?"
+
+**STOP** until user confirms the service list.
+
+---
+
+## 2. Load skills
+
+Read `.agent/skills/prd-templates/references/skill-loading-protocol.md`.
+
+For each service's surface, load:
+- **Languages** skill (e.g., TypeScript, Python, Rust)
+- **BE Frameworks** skill (e.g., Next.js, Express, FastAPI)
+- **FE Frameworks** skill if applicable (e.g., React, Svelte)
+
+Read `.agent/skills/git-workflow/SKILL.md` for repository initialization patterns.
+
+---
+
+## 3. Initialize project
+
+For each service in the service list:
+
+1. **Create the project** using the framework's official scaffolding tool:
+   - Read the BE/FE framework skill for the exact init command
+   - Run the init command (e.g., `npx create-next-app@latest`, `cargo init`, `uv init`)
+   - Use the project name from `architecture-design.md`
+
+2. **Verify initialization succeeded** — the scaffolding tool should exit 0 and create the expected files
+
+> [!IMPORTANT]
+> Use the framework's OFFICIAL scaffolding tool — never manually create package.json or equivalent. The scaffolding tool sets up the correct defaults, scripts, and configuration that manual creation would miss.
+
+**For monorepo**: Initialize the workspace root first (e.g., `npm init -w`), then init each package within the workspace structure.
+
+---
+
+## 4. Create directory structure
+
+Read `.agent/instructions/structure.md` for the project's directory layout.
+
+1. Create all directories specified in `structure.md`
+2. Create `README.md` files for directories with 3+ expected files (per extensibility rule)
+3. Create placeholder `index` files where the framework convention expects them
+
+**Merge, don't overwrite**: If the scaffolding tool already created some directories, keep them. Only add missing ones.
+
+---
+
+## 5. Install dependencies
+
+Read `docs/plans/*-architecture-design.md` dependency section.
+
+1. **Production dependencies**: Install all runtime dependencies listed in the architecture doc
+2. **Dev dependencies**: Install linter, formatter, type-checker, test framework (from the surface stack map's Unit Tests and E2E Tests cells)
+
+For each dependency:
+- Use exact versions from the architecture doc if specified
+- Use latest stable if no version specified
+- Verify installation succeeded
+
+---
+
+## 6. Create base configurations
+
+Read `.agent/instructions/commands.md` for the validation command and expected tools.
+Read `.agent/instructions/patterns.md` for code conventions.
+
+Create/update configuration files:
+
+| Config | Source | Examples |
+|--------|--------|---------|
+| Linter | Languages skill + commands.md | `.eslintrc`, `ruff.toml`, `clippy.toml` |
+| Formatter | Languages skill + commands.md | `.prettierrc`, `rustfmt.toml` |
+| Type checker | Languages skill | `tsconfig.json`, `mypy.ini` |
+| Git ignore | `git-workflow` skill | `.gitignore` |
+| Editor config | patterns.md | `.editorconfig` |
+
+**Do not invent configurations** — copy patterns from the loaded skills and the project's `patterns.md`.
+
+---
+
+## 7. Create environment template
+
+Read `docs/plans/*-architecture-design.md` environment/configuration section.
+
+1. Create `.env.example` with ALL environment variables documented
+2. Each variable gets a comment explaining its purpose and format
+3. Sensitive values get placeholder markers: `<your-api-key-here>`
+4. Group variables by category (database, auth, hosting, feature flags)
+
+Also verify `.gitignore` includes `.env` and `.env.local` patterns.
+
+---
+
+## 8. Initialize git repository
+
+Read `.agent/skills/git-workflow/SKILL.md` for repository setup patterns.
+
+1. `git init` (if not already initialized)
+2. Verify `.gitignore` is comprehensive (node_modules, .env, build artifacts, OS files)
+3. Create initial commit: `chore: scaffold project structure`
+4. Set up branch protection strategy from `git-workflow` skill (main branch)
+
+For **multi-repo**: Push each repo to its own remote.
+For **monorepo**: Single repo with workspace structure.
+
+---
+
+## 9. Verification gate
+
+Run the dev server command from `.agent/instructions/commands.md`:
+
+1. Start the dev server
+2. Wait for it to be ready (watch for "ready" or "listening" output)
+3. Verify it starts without errors
+4. Verify the default page/endpoint responds (HTTP 200)
+5. Stop the dev server
+
+**If the dev server fails to start** → **STOP.** Debug the issue before proceeding to the next shard. Common causes: missing dependency, wrong Node version, port conflict.
+
+**Pass criteria**: Dev server starts, serves a response, and shuts down cleanly.
+
+> Present result to user: "✅ Scaffold complete. Dev server starts cleanly. Proceeding to CI/CD setup." or "❌ Dev server failed: [error]. Fix required before continuing."

package/template/.agent/workflows/setup-workspace.md

@@ -0,0 +1,75 @@
+---
+description: Pre-code operational workspace setup — project scaffolding, CI/CD, hosting, and database provisioning before any implementation slices
+pipeline:
+  position: 8.5
+  stage: setup
+  predecessors: [plan-phase]
+  successors: [verify-infrastructure, implement-slice]
+  skills: [deployment-procedures, git-workflow, workflow-automation]
+  calls-bootstrap: false
+shards: [setup-workspace-scaffold, setup-workspace-cicd, setup-workspace-hosting, setup-workspace-data]
+---
+
+// turbo-all
+
+# Setup Workspace
+
+Operational setup of the project workspace, CI/CD pipeline, hosting platform, and database infrastructure. Runs after `/plan-phase` and before any `/implement-slice`. These are operational tasks — not TDD-able code.
+
+**Prerequisite**: Phase plan must exist and be approved. If no phase plan exists → **STOP**: run `/plan-phase` first.
+
+---
+
+## 0. Pre-flight
+
+1. Read the approved phase plan from `docs/plans/phases/phase-N.md`
+2. Read `docs/plans/*-architecture-design.md` for the architecture pattern
+
+**Architecture pattern detection** — determines iteration strategy:
+
+| Pattern | How to Detect | Iteration |
+|---------|--------------|-----------|
+| Monolith | Single service in architecture doc | Single pass through all shards |
+| Monorepo | Multiple packages/workspaces listed | Iterate per package in scaffold; shared platform |
+| Multi-repo | Separate repositories listed | Full pass per repo |
+
+If the architecture pattern is not documented → **HARD STOP**: "Architecture pattern (monolith / monorepo / multi-repo) must be decided in `/create-prd-architecture`. Run it first."
+
+3. Read the surface stack map from `.agent/instructions/tech-stack.md`
+4. Verify cross-cutting categories (CI/CD, Hosting, Security) have filled values
+
+**If any cross-cutting cell is empty** → **STOP**: run `/bootstrap-agents` first.
+
+---
+
+## 1. Run shards in sequence
+
+Execute each shard in order. Each shard has its own verification gate — do not proceed to the next shard until the current one passes.
+
+| Order | Shard | What It Does | Gate |
+|-------|-------|-------------|------|
+| 1 | `/setup-workspace-scaffold` | Project init, structure, deps, configs | Dev server starts |
+| 2 | `/setup-workspace-cicd` | CI/CD pipeline configuration | Pipeline runs (even if tests fail — no code yet) |
+| 3 | `/setup-workspace-hosting` | Hosting provisioning + first deploy | Staging URL accessible |
+| 4 | `/setup-workspace-data` | Database provisioning + migration setup | DB connectable + migration framework initialized |
+
+For **monorepo** projects: scaffold iterates per workspace, then CI/CD creates one pipeline with per-workspace jobs, hosting creates per-service deploy targets, data creates per-service databases (or shared if architecture specifies).
+
+For **multi-repo** projects: run the entire 4-shard sequence per repository.
+
+---
+
+## 2. Run verification
+
+After all 4 shards complete, run `/verify-infrastructure` with trigger `workspace`.
+
+**HARD GATE**: Do not proceed to `/implement-slice` until `/verify-infrastructure` produces a `✅ PASS` report.
+
+---
+
+## 3. Completion
+
+Use `notify_user` to present results:
+
+- **All shards + verification pass**: "✅ Workspace operational. Next: `/implement-slice` for the first slice (00-infrastructure code layer)."
+- **Any shard or verification fails**: "❌ Workspace setup incomplete. [list failures]. Fix and re-run the failing shard."

package/template/.agent/workflows/verify-infrastructure.md

@@ -35,12 +35,13 @@ Scan the surface stack map (`.agent/instructions/tech-stack.md`) for completenes
 
 ## 0.5. Determine trigger
 
-Read the current phase plan (e.g., `docs/plans/phases/phase-1.md`) to identify which slice just completed.
+Read the current phase plan (e.g., `docs/plans/phases/phase-1.md`) to identify what just completed.
 
+- **If `/setup-workspace` was just completed** → trigger is `workspace`, report suffix is `-workspace`
 - **If the `00-infrastructure` slice was just completed** → trigger is `infrastructure`, report suffix is empty
 - **If the auth slice was just completed** → trigger is `auth`, report suffix is `-auth`
 
-Set the report filename now: `docs/audits/verify-infrastructure-YYYY-MM-DD-HHMM[-auth].md`.
+Set the report filename now: `docs/audits/verify-infrastructure-YYYY-MM-DD-HHMM[-workspace|-auth].md`.
 
 **Re-run detection**: Check if a previous verification report exists for this trigger (search `docs/audits/` for `verify-infrastructure-*[-auth].md`).\n- If a previous report exists and shows `✅ PASS` → ask: \"A passing verification report already exists (`[filename]`). Re-run all checks or skip?\"\n- If a previous report exists and shows `❌ FAIL` → proceed automatically (re-verification needed).\n- If no previous report exists → proceed normally.
 

package/template/AGENTS.md

@@ -24,8 +24,9 @@ Decisions in this pipeline are **progressively locked**. Each pipeline stage bui
 5. `/write-be-spec` locks the **backend contracts** — API endpoints, schemas, middleware
 6. `/write-fe-spec` locks the **frontend specs** — components, state, interactions
 7. `/plan-phase` locks the **implementation order** — dependency-ordered TDD slices
-7.5. `/verify-infrastructure` locks the **operational foundation** — CI/CD green, staging live, migrations clean, auth working
-8. `/implement-slice` locks the **code** — tests → implementation → validation
+7.5. `/setup-workspace` locks the **operational foundation** — project scaffolded, CI/CD green, staging live, database connectable
+8. `/verify-infrastructure` locks the **infrastructure verification** — all operational gates green
+9. `/implement-slice` locks the **code** — tests → implementation → validation
 
 Once a stage is locked, downstream stages may not contradict it. To change a locked decision, re-run the originating stage and cascade changes downstream.
 
@@ -78,10 +79,15 @@ Once a stage is locked, downstream stages may not contradict it. To change a loc
 | 8 | `/plan-phase` | Architecture + specs | Dependency-ordered TDD slices | Planning |
 | ↳ | `/plan-phase-preflight` | Approved specs | Phase gate + completeness audit + consistency check | Planning |
 | ↳ | `/plan-phase-write` | Preflight pass | Slices + acceptance criteria + progress files | Planning |
+| 8.5 | `/setup-workspace` | Architecture + phase plan | Scaffolded project + CI/CD + staging + database | Setup |
+| ↳ | `/setup-workspace-scaffold` | Architecture + structure | Project init + deps + configs + git | Setup |
+| ↳ | `/setup-workspace-cicd` | Scaffolded project | CI/CD pipeline config + secrets | Setup |
+| ↳ | `/setup-workspace-hosting` | CI/CD configured | Hosting + domains + first staging deploy | Setup |
+| ↳ | `/setup-workspace-data` | Hosting configured | Database + migrations + connections | Setup |
 | 9 | `/implement-slice` | Slice acceptance criteria | Working code via Red→Green→Refactor | Implementation |
 | ↳ | `/implement-slice-setup` | Slice from phase plan | Progress check + skills + contracts + parallel mode | Implementation |
 | ↳ | `/implement-slice-tdd` | Contract + tests | Red→Green→Refactor + validation + progress tracking | Implementation |
-| 9.5 | `/verify-infrastructure` | Implemented infra or auth slice | Operational verification report | Verification |
+| 9.5 | `/verify-infrastructure` | Workspace, infra slice, or auth slice | Operational verification report | Verification |
 | 10 | `/validate-phase` | Completed phase | Full validation gate | Verification |
 | ↳ | `/validate-phase-quality` | Completed phase | Code quality gates — tests, coverage, lint, type-check, build, CI/CD, staging, migrations, spec coverage | Verification |
 | ↳ | `/validate-phase-readiness` | Quality gates passed | Production readiness gates — API docs, accessibility, performance, security, dependency audit, results | Verification |

package/template/GEMINI.md

@@ -13,7 +13,7 @@
 
 ### Progressive Decision Lock
 
-Decisions are **progressively locked**: `/ideate` → vision, `/create-prd` → architecture, `/decompose-architecture` → domain boundaries, `/write-architecture-spec` → interaction specs, `/write-be-spec` → backend contracts, `/write-fe-spec` → frontend specs, `/plan-phase` → implementation order, `/verify-infrastructure` → operational foundation, `/implement-slice` → code.
+Decisions are **progressively locked**: `/ideate` → vision, `/create-prd` → architecture, `/decompose-architecture` → domain boundaries, `/write-architecture-spec` → interaction specs, `/write-be-spec` → backend contracts, `/write-fe-spec` → frontend specs, `/plan-phase` → implementation order, `/setup-workspace` → operational foundation, `/verify-infrastructure` → infrastructure verification, `/implement-slice` → code.
 
 Once locked, downstream stages may not contradict. To change a locked decision, re-run the originating stage and cascade.
 
@@ -62,10 +62,15 @@ Once locked, downstream stages may not contradict. To change a locked decision,
 | 8 | `/plan-phase` | Architecture + specs | Dependency-ordered TDD slices | Planning |
 | ↳ | `/plan-phase-preflight` | Approved specs | Phase gate + completeness audit + consistency check | Planning |
 | ↳ | `/plan-phase-write` | Preflight pass | Slices + acceptance criteria + progress files | Planning |
+| 8.5 | `/setup-workspace` | Architecture + phase plan | Scaffolded project + CI/CD + staging + database | Setup |
+| ↳ | `/setup-workspace-scaffold` | Architecture + structure | Project init + deps + configs + git | Setup |
+| ↳ | `/setup-workspace-cicd` | Scaffolded project | CI/CD pipeline config + secrets | Setup |
+| ↳ | `/setup-workspace-hosting` | CI/CD configured | Hosting + domains + first staging deploy | Setup |
+| ↳ | `/setup-workspace-data` | Hosting configured | Database + migrations + connections | Setup |
 | 9 | `/implement-slice` | Slice acceptance criteria | Working code via Red→Green→Refactor | Implementation |
 | ↳ | `/implement-slice-setup` | Slice from phase plan | Progress check + skills + contracts + parallel mode | Implementation |
 | ↳ | `/implement-slice-tdd` | Contract + tests | Red→Green→Refactor + validation + progress tracking | Implementation |
-| 7.5 | `/verify-infrastructure` | Implemented infra or auth slice | Operational verification report | Verification |
+| 9.5 | `/verify-infrastructure` | Workspace, infra slice, or auth slice | Operational verification report | Verification |
 | 10 | `/validate-phase` | Completed phase | Full validation gate | Verification |
 | ↳ | `/validate-phase-quality` | Completed phase | Code quality gates — tests, coverage, lint, type-check, build, CI/CD, staging, migrations, spec coverage | Verification |
 | ↳ | `/validate-phase-readiness` | Quality gates passed | Production readiness gates — API docs, accessibility, performance, security, dependency audit, results | Verification |
@@ -156,6 +161,7 @@ Before acting on any task, detect the current pipeline phase from filesystem mar
 | Decomposition done | IA shards in `docs/plans/ia/` | `/write-architecture-spec` |
 | Spec writing | BE/FE specs exist | `/write-be-spec`, `/write-fe-spec` |
 | Planning | Phase plan in `docs/plans/phases/` | `/plan-phase` |
+| Workspace setup | Phase plan exists, no `.agent/progress/` content | `/setup-workspace` → `/verify-infrastructure` |
 | Implementation | `.agent/progress/` has content | `/implement-slice` |
 
 **Use this table to gate every action.** If a user runs a command that doesn't match their current phase, explain what phase they're in and what to run instead.