cfsa-antigravity 1.0.0

package/template/.agent/workflows/bootstrap-agents-fill.md

@@ -0,0 +1,201 @@
+---
+description: Receive template values and fill instruction/rule/AGENTS.md templates for the bootstrap-agents workflow
+parent: bootstrap-agents
+shard: fill
+standalone: true
+position: 1
+pipeline:
+  position: infrastructure
+  stage: provisioning
+  predecessors: []
+  successors: [bootstrap-agents-provision]
+  skills: []
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Bootstrap Agents — Fill Templates
+
+Receive template values from the calling workflow and fill `{{PLACEHOLDER}}` values across all instruction, rule, skill, and root-level templates.
+
+**Prerequisite**: If invoked standalone, the caller must provide at least one template key-value pair. If no values are provided, there is nothing to fill — report and exit.
+
+> [!IMPORTANT]
+> This workflow fills template-level placeholders (project name, description, tech stack summary, architecture doc path). It does **NOT** fill workflow command placeholders (`{{VALIDATION_COMMAND}}`, `{{TEST_COMMAND}}`, `{{LINT_COMMAND}}`, etc.) or skill path placeholders (`{{DATABASE_SKILLS}}`, `{{AUTH_SKILL}}`, etc.). Those are filled exclusively by `.agent/workflows/bootstrap-agents-provision.md` during the `/create-prd` stage. Running this workflow standalone will leave those placeholders unfilled with no indication — they require the provision step.
+
+---
+
+## 1. Receive template values
+
+The calling workflow provides these values (all optional — fill only what's provided, leave others as `{{PLACEHOLDER}}`):
+
+### Command & Tool Values
+
+| Key | Example |
+|-----|---------|
+| `PACKAGE_MANAGER` | pnpm |
+| `DEV_COMMAND` | pnpm dev |
+| `TEST_COMMAND` | pnpm test |
+| `TEST_WATCH_COMMAND` | pnpm test:watch |
+| `TEST_COVERAGE_COMMAND` | pnpm test:coverage |
+| `LINT_COMMAND` | pnpm lint |
+| `LINT_FIX_COMMAND` | pnpm lint:fix |
+| `FORMAT_COMMAND` | pnpm format |
+| `TYPE_CHECK_COMMAND` | pnpm type-check |
+| `BUILD_COMMAND` | pnpm build |
+| `PREVIEW_COMMAND` | pnpm preview |
+| `VALIDATION_COMMAND` | pnpm test && pnpm lint && pnpm type-check && pnpm build |
+
+### Project Identity
+
+| Key | Example |
+|-----|---------|
+| `PROJECT_NAME` | My Project |
+| `DESCRIPTION` | One-line description |
+| `TECH_STACK_SUMMARY` | Astro + React + SurrealDB + Firebase Auth |
+
+### Architecture & Structure
+
+| Key | Example |
+|-----|---------|
+| `FRAMEWORK_PATTERNS` | Framework-specific patterns block |
+| `PROJECT_STRUCTURE` | Directory layout block |
+| `ARCHITECTURE_TABLE` | Concern/Location/Runtime table rows |
+| `ARCHITECTURE_DOC` | docs/plans/2026-02-10-architecture-design.md |
+| `CONTRACTS_DIR` | src/contracts/ |
+| `BUILD_OUTPUT_DIR` | dist/ |
+
+### Stack Values (trigger skill provisioning)
+
+| Key | Example |
+|-----|---------|
+| `DATABASE` | SurrealDB (self-hosted) |
+| `DATABASE_PRIMARY` | PostgreSQL |
+| `DATABASE_VECTOR` | Qdrant |
+| `DATABASE_GRAPH` | Neo4j |
+| `DATABASE_CACHE` | Redis |
+| `DATABASE_TIMESERIES` | TimescaleDB |
+| `FRONTEND_FRAMEWORK` | Astro + React Islands |
+| `BACKEND_FRAMEWORK` | Hono |
+| `API_LAYER` | tRPC |
+| `BACKEND_RUNTIME` | Cloudflare Workers |
+| `ORM` | Drizzle |
+| `CSS_FRAMEWORK` | Tailwind CSS v4 |
+| `UI_LIBRARY` | shadcn/ui |
+| `AUTH_PROVIDER` | Firebase Auth |
+| `PAYMENTS` | Stripe |
+| `AI_SDK` | Vercel AI SDK |
+| `STATE_MANAGEMENT` | TanStack Query |
+| `E2E_TESTING` | Playwright |
+| `UNIT_TESTING` | Vitest |
+| `HOSTING` | Cloudflare Pages + Workers |
+| `CDN_ASSETS` | Cloudflare R2 |
+| `MONITORING` | Sentry |
+| `OBSERVABILITY` | OpenTelemetry |
+| `ANALYTICS` | Google Analytics |
+| `EMAIL` | Resend |
+| `QUEUE` | Inngest |
+| `REALTIME` | Socket.io |
+| `SEARCH` | Meilisearch |
+| `CMS` | Payload CMS |
+| `STORAGE` | AWS S3 |
+| `CI_CD` | GitHub Actions |
+| `MOBILE_FRAMEWORK` | Expo |
+| `LANGUAGE` | TypeScript |
+| `3D_FRAMEWORK` | Three.js / R3F |
+| `DESKTOP_FRAMEWORK` | Tauri |
+| `GAME_ENGINE` | Godot |
+| `SECURITY` | OWASP |
+| `TEST_RUNNER` | Vitest |
+| `LINTER` | ESLint |
+| `TYPE_CHECKER` | TypeScript (tsc) |
+| `CONTRACT_LIBRARY` | Zod |
+
+> **Note**: `DATABASE` is an alias for `DATABASE_PRIMARY` — it triggers the same MANIFEST match. When multiple `DATABASE_*` sub-keys are present, the `DATABASE` row in `tech-stack.md` should expand to show sub-rows (`DATABASE_PRIMARY`, `DATABASE_VECTOR`, etc.) rather than a single combined string. Bootstrap fills each sub-row individually as the user confirms each store.
+
+### Infrastructure Values
+
+| Key | Example |
+|-----|---------|
+| `SSH_HOST` | my-vps |
+| `DB_PORT` | 19000 |
+| `CREDENTIAL_TOOL` | agent-auth ssh-add |
+| `SECRET_MANAGEMENT` | wrangler secret |
+| `DEPLOY_COMMAND` | wrangler deploy |
+
+### Surface Types
+
+| Key | Example |
+|-----|---------|
+| `SURFACES` | web, api |
+
+**Pipeline Context**
+
+| Key | Example | Purpose |
+|-----|---------|---------|
+| `PIPELINE_STAGE` | `create-prd`, `write-be-spec`, `write-fe-spec`, `implement-slice` | Context of this invocation — used to validate correct keys are being passed |
+| `SKILL_BUNDLE` | `database-schema-design,migration-management,error-handling-patterns` | When provided, bootstrap loads all listed skills in one invocation |
+
+If any values are missing, leave those `{{PLACEHOLDER}}`s in place — they'll be filled on a future invocation.
+
+---
+
+## 2. Fill instruction templates
+
+### `.agent/instructions/commands.md`
+Replace: `{{PACKAGE_MANAGER}}`, `{{DEV_COMMAND}}`, `{{TEST_COMMAND}}`, `{{TEST_WATCH_COMMAND}}`, `{{TEST_COVERAGE_COMMAND}}`, `{{LINT_COMMAND}}`, `{{LINT_FIX_COMMAND}}`, `{{FORMAT_COMMAND}}`, `{{TYPE_CHECK_COMMAND}}`, `{{BUILD_COMMAND}}`, `{{PREVIEW_COMMAND}}`, `{{VALIDATION_COMMAND}}`
+
+### `.agent/instructions/workflow.md`
+Replace: `{{VALIDATION_COMMAND}}`
+
+### `.agent/instructions/patterns.md`
+Replace: `{{FRAMEWORK_PATTERNS}}` if provided
+
+### `.agent/instructions/structure.md`
+Replace: `{{PROJECT_STRUCTURE}}`, `{{ARCHITECTURE_TABLE}}` if provided
+
+### `.agent/instructions/tech-stack.md`
+Replace: `{{TECH_STACK_SUMMARY}}`, `{{FRONTEND_FRAMEWORK}}`, `{{BACKEND_RUNTIME}}`, `{{DATABASE}}`, `{{AUTH_PROVIDER}}`, `{{HOSTING}}`, `{{CDN_ASSETS}}`, `{{CICD}}`, `{{MONITORING}}`, `{{PACKAGE_MANAGER}}`, `{{TEST_RUNNER}}`, `{{LINTER}}`, `{{TYPE_CHECKER}}`, `{{INSTALLED_SKILLS}}`, `{{ARCHITECTURE_DOC}}`
+Replace: `{{ARCHITECTURE_DOC}}` with the dated architecture design filename (e.g., `docs/plans/YYYY-MM-DD-architecture-design.md`)
+
+---
+
+## 3. Fill default operational skill templates
+
+Scan all `.agent/skills/*/SKILL.md` files for `{{PLACEHOLDER}}` values and fill any that match the provided template values:
+
+- `{{VALIDATION_COMMAND}}` — in `fix-bug`, `main-workflow`, `deploy`, `refactor`
+- `{{PACKAGE_MANAGER}}` — in `refactor`, `security-audit`
+- `{{TEST_COVERAGE_COMMAND}}` — in `refactor`
+- `{{BUILD_COMMAND}}` — in `deploy`
+- `{{DEPLOY_COMMAND}}` — in `deploy`
+- `{{BUILD_OUTPUT_DIR}}` — in `deploy`
+- `{{SSH_HOST}}` — in `setup-session`
+- `{{DB_PORT}}` — in `setup-session`
+- `{{CREDENTIAL_TOOL}}` — in `setup-session`
+
+Also scan all `.agent/rules/*.md` files for `{{PLACEHOLDER}}` values and fill any that match the provided template values. Currently applicable: `{{CONTRACT_LIBRARY}}` in `tdd-contract-first.md`.
+
+---
+
+## 4. Fill root agent config files (AGENTS.md and GEMINI.md)
+
+Replace in **both** `AGENTS.md` and `GEMINI.md`:
+- `{{PROJECT_NAME}}`
+- `{{DESCRIPTION}}`
+- `{{TECH_STACK_SUMMARY}}`
+- `{{VALIDATION_COMMAND}}`
+- `{{ARCHITECTURE_DOC}}`
+- `{{INSTALLED_SKILLS}}` (if provided at this invocation; otherwise leave for `bootstrap-agents-provision` Step 8 to fill after skill provisioning)
+
+> **Note**: Both files serve as root agent config for their respective agents (`AGENTS.md` for Claude Code / Antigravity, `GEMINI.md` for Gemini CLI). Both must be kept in sync — any placeholder filled in one must be filled in the other.
+
+### Report and proceed
+
+Report which `{{PLACEHOLDER}}`s were filled and their values, which remain unfilled, and any errors encountered.
+
+If invoked standalone, the next step is `/bootstrap-agents-provision` to provision skills from the library based on the stack values just filled.
+
+If invoked by another workflow (e.g., `/create-prd`), return this report to the calling workflow — the caller will invoke `/bootstrap-agents-provision` automatically.
+

package/template/.agent/workflows/bootstrap-agents-provision.md

@@ -0,0 +1,197 @@
+---
+description: Skill library provisioning, workflow placeholder filling, and result reporting for the bootstrap-agents workflow
+parent: bootstrap-agents
+shard: provision
+standalone: true
+position: 2
+pipeline:
+  position: infrastructure
+  stage: provisioning
+  predecessors: [bootstrap-agents-fill]
+  successors: []
+  skills: []
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Bootstrap Agents — Provision Skills
+
+Read the skill library manifest, provision matching skills, fill workflow placeholders, and report results.
+
+**Prerequisite**: If invoked standalone, the caller must have template values available (from a previous `/bootstrap-agents-fill` run or direct invocation with stack/surface keys).
+
+---
+
+## 6. Read skill library manifest
+
+Read `.agent/skill-library/MANIFEST.md` to load the trigger tables.
+
+If `.agent/skill-library/MANIFEST.md` does not exist (e.g., user deleted it or is using a minimal kit), skip steps 7-8 and go to step 9.
+
+---
+
+## 7. Provision skills from library
+
+For each stack key provided in the template values, check the **Stack Triggers** table in the manifest:
+
+1. Match the provided value against the manifest's `Value Pattern` (case-insensitive)
+2. If a match is found AND the skill is NOT already in `.agent/skills/[installed-as]/`:
+   - Copy the entire directory from `.agent/skill-library/[library-path]/` → `.agent/skills/[installed-as]/`
+   - Fill any `{{PLACEHOLDER}}`s in the newly-copied `SKILL.md` with current template values
+3. If the skill already exists in `.agent/skills/`, skip it (idempotent)
+
+For each surface type provided in `SURFACES`, check the **Surface Triggers** table:
+
+1. Match the surface type against the manifest's `Surface Type` column
+2. Copy matching skills that don't already exist, same as above
+
+### Matching rules
+
+| Manifest Pattern | Matches |
+|-----------------|---------|
+| `*surrealdb*` | "SurrealDB", "surrealdb (self-hosted)", "SurrealDB Cloud" |
+| `*cloudflare*` | "Cloudflare Workers", "Cloudflare Pages + Workers" |
+| `*tailwind*` | "Tailwind CSS v4", "Tailwind CSS" |
+| `*vercel*` OR `*ai-sdk*` | "Vercel AI SDK", "AI SDK" |
+| `*three*` OR `*r3f*` | "Three.js", "React Three Fiber", "R3F" |
+
+Pattern matching is glob-style with `*` as wildcard, case-insensitive.
+
+---
+
+## 8. Update installed skills list
+
+After provisioning, build a markdown list of all installed skills (both defaults and library-provisioned) and update `{{INSTALLED_SKILLS}}` in the tech stack instruction.
+
+Also update `{{INSTALLED_SKILLS}}` in `AGENTS.md` and `GEMINI.md` with the same installed skills list. These root agent config files must reflect the full skill inventory so agents reading them have complete context.
+
+Read `.agent/skills/prd-templates/references/operational-templates.md` for the **Installed Skills List** template. Use the template structure, filling in actual installed skill names and descriptions.
+
+### 8.5. Compose and fill FRAMEWORK_PATTERNS
+
+Identify any frontend-capable framework skill provisioned or matched during this invocation by checking across all relevant stack axes:
+
+| Stack Axis | Example Skills |
+|------------|---------------|
+| `FRONTEND_FRAMEWORK` | `nextjs`, `astro-framework`, `sveltekit`, `nuxt`, `react-best-practices` |
+| `MOBILE_FRAMEWORK` | `expo-react-native` |
+
+If any of these axes resolved to a provisioned skill in Step 7, use that skill for composition.
+
+**If a frontend-capable framework skill is present:**
+1. Read the installed skill's `SKILL.md` from `.agent/skills/[installed-as]/SKILL.md`
+2. Extract the component patterns section (file structure, naming conventions, composition patterns, what to avoid)
+3. Compose a `FRAMEWORK_PATTERNS` markdown block summarising these component conventions
+4. Fire `bootstrap-agents-fill` with `FRAMEWORK_PATTERNS=[composed value]` to fill the `## Components` section of `.agent/instructions/patterns.md`
+5. If multiple frontend-capable skills are present (e.g., `FRONTEND_FRAMEWORK` + `MOBILE_FRAMEWORK`), merge their patterns into a single `FRAMEWORK_PATTERNS` block with clearly labelled sections per surface
+
+This step is idempotent — it can be re-run on existing projects to fill `patterns.md` without re-provisioning the skill. For remediation flows, provide the relevant stack axis value(s) so this step resolves the correct skill(s).
+
+**If no frontend-capable framework skill is present:** Skip — `patterns.md` already has a sensible fallback for non-visual projects.
+
+---
+
+## 9. Fill workflow skill placeholders
+
+In the generic workflows, replace the following placeholders with the **directory name** of the installed skill (e.g., `surrealdb-expert`, `typescript-advanced-patterns`). The surrounding path `.agent/skills/.../SKILL.md` is hardcoded in each workflow. If no skill was installed for a given category, instruct the agent to skip it or provide a reasonable default.
+
+### DATABASE_SKILLS accumulation logic
+
+`{{DATABASE_SKILLS}}` is a comma-separated list of installed skill directory names (one per confirmed database store, e.g., `postgresql,qdrant,redis`). Bootstrap appends the new skill name to the existing list value rather than overwriting it. If the list is empty, set it to the single name. If the name is already present, skip (idempotent).
+
+The following sub-keys all trigger the `{{DATABASE_SKILLS}}` accumulation logic:
+- `DATABASE_PRIMARY` — Main relational/document/multi-model store
+- `DATABASE_VECTOR` — Semantic search, embeddings, similarity
+- `DATABASE_GRAPH` — Graph traversal, relationship queries
+- `DATABASE_CACHE` — Caching layer
+- `DATABASE_TIMESERIES` — Time-ordered data, metrics, IoT
+
+> **Backward compatibility**: If the incoming key is `DATABASE`, treat it as `DATABASE_PRIMARY` and proceed identically.
+
+### SECURITY_SKILLS accumulation logic
+
+`{{SECURITY_SKILLS}}` is a comma-separated list of all security skill directory names provisioned for this project. Bootstrap appends the new skill name to the existing list value rather than overwriting it. If the list is empty, set it to the single name. If the name is already present, skip (idempotent).
+
+The following keys all contribute to `{{SECURITY_SKILLS}}` accumulation:
+- `SECURITY` — Explicit user-named security skill (e.g., `SECURITY=owasp-web-security`)
+- Surface trigger: web → appends `owasp-web-security`, `csp-cors-headers`, `input-sanitization`
+- Surface trigger: api → appends `input-sanitization` (if not already present)
+- Surface trigger: desktop → appends `desktop-security-sandboxing`
+- Surface trigger: any → appends `dependency-auditing`
+
+`{{SECURITY_SKILLS}}` is used in `create-prd-security.md` Step 6 to load all relevant security skills before designing the security model.
+
+### Placeholder → Workflow mapping
+
+| Placeholder | Source Key | Workflows |
+|---|---|---|
+| `{{DATABASE_SKILLS}}` | `DATABASE_*` (accumulated) | create-prd, write-architecture-spec, write-be-spec-classify |
+| `{{AUTH_SKILL}}` | `AUTH_PROVIDER` | create-prd, write-be-spec-classify |
+| `{{BACKEND_FRAMEWORK_SKILL}}` | `BACKEND_FRAMEWORK` / `API_LAYER` | write-be-spec-classify |
+| `{{FRONTEND_FRAMEWORK_SKILL}}` | `FRONTEND_FRAMEWORK` | write-fe-spec-classify |
+| `{{FRONTEND_DESIGN_SKILL}}` | `CSS_FRAMEWORK` / `UI_LIBRARY` | write-fe-spec-classify |
+| `{{ACCESSIBILITY_SKILL}}` | surface: `accessibility-compliance` | write-fe-spec-classify |
+| `{{LANGUAGE_SKILL}}` | `LANGUAGE` | implement-slice-setup, implement-slice-tdd, write-be-spec-classify, write-fe-spec-classify, evolve-contract |
+| `{{CI_CD_SKILL}}` | `CI_CD` | create-prd-compile, decompose-architecture-structure, plan-phase, verify-infrastructure, validate-phase |
+| `{{HOSTING_SKILL}}` | `HOSTING` | create-prd-architecture, decompose-architecture-structure, plan-phase, verify-infrastructure, validate-phase |
+| `{{ORM_SKILL}}` | `ORM` | create-prd-architecture, write-be-spec-classify, implement-slice-setup, verify-infrastructure, validate-phase |
+| `{{UNIT_TESTING_SKILL}}` | `UNIT_TESTING` | create-prd-compile, implement-slice-setup, implement-slice-tdd, write-be-spec-classify, evolve-contract |
+| `{{E2E_TESTING_SKILL}}` | `E2E_TESTING` | create-prd-compile, implement-slice-tdd, validate-phase |
+| `{{STATE_MANAGEMENT_SKILL}}` | `STATE_MANAGEMENT` | write-fe-spec-classify, implement-slice-setup |
+| `{{SECURITY_SKILLS}}` | `SECURITY` + surface triggers (accumulated) | create-prd-security, write-architecture-spec-design |
+
+### 9.1. CONTRACT_LIBRARY resolution
+
+This step fires when the `LANGUAGE` key is confirmed (either from the current invocation or from an already-filled `tech-stack.md`).
+
+Derive `CONTRACT_LIBRARY` using the following mapping table:
+
+| `LANGUAGE` value | `CONTRACT_LIBRARY` value |
+|---|---|
+| TypeScript / JavaScript | Zod |
+| Python | Pydantic |
+| Go | ozzo-validation |
+| Rust | Serde |
+| Java | Jakarta Bean Validation |
+| Kotlin | kotlinx.serialization |
+| C / C++ | (prompt user — no dominant standard) |
+| Bash / Shell | (none — validate inline with functions) |
+
+For any language **not in this table**: prompt the user — "What is your preferred schema validation / contract library for [LANGUAGE]?" — and use their confirmed answer as the `CONTRACT_LIBRARY` value.
+
+Once the value is confirmed, invoke `bootstrap-agents-fill` with `CONTRACT_LIBRARY=[value]` so that `tdd-contract-first.md` is filled at the same time as the language skill is provisioned (the fill workflow's extended Step 3 scan will now reach `.agent/rules/`).
+
+---
+
+## 9.5. Fill workflow command placeholders
+
+Workflows use `{{COMMAND}}` placeholders for test, lint, build, and validation commands. Replace them with the values gathered during tech stack decisions (step 1).
+
+In `.agent/workflows/implement-slice-tdd.md`:
+- `{{TEST_COMMAND}}` → the project's test runner command
+- `{{VALIDATION_COMMAND}}` → the full validation pipeline command
+
+In `.agent/workflows/validate-phase.md`:
+- `{{TEST_COMMAND}}` → the project's test runner command
+- `{{TEST_COVERAGE_COMMAND}}` → the test runner with coverage enabled
+- `{{LINT_COMMAND}}` → the linter command
+- `{{TYPE_CHECK_COMMAND}}` → the type checker command
+- `{{BUILD_COMMAND}}` → the production build command
+
+In `.agent/workflows/evolve-contract.md`:
+- `{{TEST_COMMAND}}` → the project's test runner command
+- `{{VALIDATION_COMMAND}}` → the full validation pipeline command
+
+
+---
+
+## 10. Report results
+
+Return to the calling workflow a summary:
+
+- Which `{{PLACEHOLDER}}`s were filled (and their values)
+- Which `{{PLACEHOLDER}}`s remain unfilled
+- Which skills were provisioned from the library (if any)
+- Which skills were already installed and skipped
+- Any errors (missing files, missing library paths)

package/template/.agent/workflows/bootstrap-agents.md

@@ -0,0 +1,66 @@
+---
+description: Utility — fill {{PLACEHOLDER}} values and provision skills from `.agent/skill-library/`. Called by pipeline workflows when tech stack info changes.
+pipeline:
+  position: infrastructure
+  stage: provisioning
+  predecessors: [] # called inline by other workflows
+  successors: [] # returns to caller
+  skills: [] # this IS the skill provisioner
+  calls-bootstrap: false # is bootstrap
+shards: [bootstrap-agents-fill, bootstrap-agents-provision]
+---
+
+# Bootstrap Agents
+
+**This is a utility workflow, not an entry point.** It gets called by other pipeline workflows (like `/create-prd`, `/iterate-plan`, `/write-be-spec`, `/write-fe-spec`, `/add-feature`, `/implement-slice`) whenever they make tech stack decisions or introduce new dependencies.
+
+> Bootstrap is a **surgical, additive, idempotent provisioner**. Each invocation fills ONLY the placeholders for the decisions just confirmed and provisions ONLY the skills triggered by those decisions. It never touches placeholders that haven't been decided yet and never re-fills placeholders that are already filled.
+
+Bootstrap does two things:
+1. **Fill `{{PLACEHOLDER}}` values** in kit instruction templates
+2. **Provision skills** from `.agent/skill-library/` based on stack and surface triggers
+
+## Invocation Points
+
+| Workflow | When Bootstrap Fires | Keys Passed |
+|---|---|---|
+| `/create-prd` Step 3 | After each confirmed tech decision | The specific key just decided (e.g., `DATABASE=SurrealDB`) |
+| `/create-prd` Step 10 | After architecture doc is written | `ARCHITECTURE_DOC` (the dated filename) |
+| `/write-be-spec` | If spec introduces new backend dependency | New key only (e.g., `QUEUE=BullMQ`) |
+| `/write-fe-spec` | If spec introduces new frontend dependency | New key only (e.g., `CHARTS=Chart.js`) |
+| `/implement-slice` | If implementation adds significant new dependency | New key only |
+
+**Input**: Template values (package manager, framework, database, etc.) + optional stack/surface triggers
+**Output**: Filled templates + newly installed skills in `.agent/skills/`
+
+---
+
+## Shard Overview
+
+| # | Shard | What It Does |
+|---|-------|-------------|
+| 1 | [`bootstrap-agents-fill`](.agent/workflows/bootstrap-agents-fill.md) | Receives template values, fills instruction/rule/AGENTS.md templates |
+| 2 | [`bootstrap-agents-provision`](.agent/workflows/bootstrap-agents-provision.md) | Reads skill library manifest, provisions skills, fills workflow placeholders, reports results |
+
+---
+
+## Orchestration
+
+### Step A — Run `.agent/workflows/bootstrap-agents-fill.md`
+
+Receives template values from the calling workflow and fills `{{PLACEHOLDER}}` values across instruction templates, rule templates, skill templates, and `AGENTS.md`.
+
+### Step B — Run `.agent/workflows/bootstrap-agents-provision.md`
+
+Reads the skill library manifest, provisions matching skills based on stack/surface triggers, updates the installed skills list, fills workflow command/skill placeholders, and reports results.
+
+---
+
+## Idempotency
+
+Bootstrap is safe to call multiple times:
+
+- **Already-filled placeholders**: If a `{{PLACEHOLDER}}` has already been replaced with a value, it is NOT re-filled unless the calling workflow explicitly provides a new value for that key
+- **Already-installed skills**: Skills that already exist in `.agent/skills/` are not re-copied from the library
+- **New values**: New stack/surface values trigger new skill installations without affecting existing ones
+- **Partial invocation**: Bootstrap can be called with just one or two new values — it only fills what's provided

package/template/.agent/workflows/create-prd-architecture.md

@@ -0,0 +1,119 @@
+---
+description: System architecture and data strategy for the create-prd workflow
+parent: create-prd
+shard: architecture
+standalone: true
+position: 2
+pipeline:
+  position: 2.2
+  stage: architecture
+  predecessors: [create-prd-stack]
+  successors: [create-prd-security]
+  skills: [database-schema-design, technical-writer, prd-templates, error-handling-patterns]
+  calls-bootstrap: false
+requires_placeholders: [HOSTING_SKILL, ORM_SKILL, DATABASE_SKILLS]
+---
+
+// turbo-all
+
+# Create PRD — Architecture & Data Strategy
+
+Design the high-level system architecture and data strategy. Create the data placement strategy document.
+
+---
+
+## 0. Placeholder guard
+
+Before any skill reads, verify that the following placeholder values have been filled by `/bootstrap-agents`. For each placeholder, check whether the literal characters `{{` still appear in the value. If **any** are unfilled, emit a **HARD STOP** and do not proceed to Step 4.
+
+| Placeholder | Filled by | Recovery | Why this matters |
+|---|---|---|---|
+| `{{HOSTING_SKILL}}` | `/create-prd-stack` when hosting provider is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed hosting provider, then run `/bootstrap-agents HOSTING=<confirmed-provider>`. Otherwise run `/create-prd-stack` first. | Data strategy and schema design steps (Steps 4 and 5) cannot run without the hosting skill — deployment topology decisions will lack provider-specific conventions. |
+| `{{ORM_SKILL}}` | `/create-prd-stack` when ORM is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed ORM, then run `/bootstrap-agents ORM=<confirmed-orm>`. Otherwise run `/create-prd-stack` first. | Migration strategy (Step 5.4) cannot run without the ORM skill — schema conventions and migration patterns will be generic instead of stack-specific. |
+| `{{DATABASE_SKILLS}}` | `/create-prd-stack` when database technology is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed database, then run `/bootstrap-agents DATABASE=<confirmed-db>`. Otherwise run `/create-prd-stack` first. | Data strategy (Step 5) cannot run without the database skill — schema design patterns will be incompatible with the chosen database. |
+
+For the hard stop message format and recovery instructions, see `.agent/skills/prd-templates/references/placeholder-guard-template.md`.
+
+Only proceed to Step 4 when all three placeholders report no literal `{{` characters.
+
+---
+
+## 4. System architecture
+
+Read .agent/skills/rest-api-design/SKILL.md and .agent/skills/api-design-principles/SKILL.md for API surface design.
+
+Design the high-level system. Each sub-item requires full exploration, not a summary sentence:
+
+1. **Component diagram** — What services exist? How do they communicate? What protocols? What happens if one is down?
+2. **Data flow** — Request lifecycle from client to database and back. Every hop, every transformation, every auth check along the way. Draw the full sequence.
+3. **Deployment topology** — What runs where? Edge? Origin? External? Local machine? App Store? What are the latency implications? What are the cost implications?
+   Read .agent/skills/{{HOSTING_SKILL}}/SKILL.md and follow its deployment conventions.
+   Read .agent/skills/technical-writer/SKILL.md and follow its methodology.
+4. **API surface** — REST? GraphQL? RPC? Versioning strategy? Error format? Pagination? Rate limit headers?
+
+For multi-surface projects, additionally define:
+5. **Surface interconnection** — How do surfaces communicate? What is the source of truth for shared data? What happens when a surface is offline?
+6. **Shared domain boundary** — Which entities/models are shared across surfaces vs surface-specific?
+
+For each component, also define:
+- What it owns (data, logic, auth decisions)
+- What it delegates (to other components or external services)
+- What happens when it fails (graceful degradation, circuit breakers, fallbacks)
+
+**Present to user**: Show the system architecture section and walk through each component. Ask:
+- "Does this component diagram capture every service in the system?"
+- "Are there failure modes I haven't accounted for?"
+- For multi-surface: "What happens if the sync layer goes down? Can each surface degrade gracefully?"
+
+Refine based on discussion before proceeding.
+
+Write the completed `## System Architecture` section to `docs/plans/architecture-draft.md` (create the file if it does not exist). Do not wait until the end — write this section as soon as it is completed and confirmed by the user.
+
+## 4.5. Error architecture
+
+> **Hard gate.** This step is mandatory for every project. All five decisions below must be confirmed by the user before `## 5. Data strategy` begins. Do not proceed to Data Strategy until every decision is explicitly approved.
+
+Read `.agent/skills/error-handling-patterns/SKILL.md` and follow its Error Architecture Interview methodology. All 5 decisions must receive explicit user confirmation before proceeding to Data Strategy. This step is a hard gate — do not proceed until all five decisions are confirmed.
+
+Write the completed decisions to `docs/plans/architecture-draft.md` under a new top-level `## Error Architecture` section (between `## System Architecture` and `## Data Strategy`). The section must contain five sub-sections matching the five decisions above (`### Global Error Envelope`, `### Error Propagation Chain`, `### Unhandled Exception Strategy`, `### Client Fallback Contract`, `### Error Boundary Strategy`), with the locked canonical JSON example included verbatim under `### Global Error Envelope`.
+
+## 5. Data strategy
+
+Read .agent/skills/database-schema-design/SKILL.md and follow its schema design methodology.
+
+Read each skill listed in `{{DATABASE_SKILLS}}` (comma-separated). For each skill directory name, read `.agent/skills/[skill]/SKILL.md` before proceeding. Each sub-item must be explored to field-level depth:
+
+1. **Data placement** — What lives in the database vs cache vs object storage vs external service vs local device storage? For each entity: which service owns it and why
+2. **Schema approach** — Strict schema vs schemaless vs hybrid? Field types, constraints, indexes, relations with cardinality
+3. **Query patterns** — Read-heavy? Write-heavy? What are the hot paths? What needs caching? What are the N+1 risks?
+4. **Migration strategy** — How will schema evolve? Backward compatibility approach? Zero-downtime migration plan?
+   Read .agent/skills/{{ORM_SKILL}}/SKILL.md and follow its migration and schema conventions.
+5. **PII boundaries** — Which fields contain PII? Where is PII stored vs where is it NOT stored? How is PII isolated from AI/analytics pipelines?
+
+For multi-surface projects, additionally define:
+6. **Data ownership** — Which surface is the source of truth for each entity? How are conflicts resolved?
+7. **Sync protocol** — What data syncs between surfaces? How frequently? What happens during network partition?
+
+**Present to user**: Show the data strategy section and walk through placement decisions. Ask:
+- "Does every entity have a clear owner?"
+- "Are there query patterns I'm missing that could become hot paths?"
+
+Refine based on discussion before proceeding.
+
+Write the completed `## Data Strategy` section to `docs/plans/architecture-draft.md`.
+
+### 5.5. Cross-Store Entity Consistency
+
+Read .agent/skills/database-schema-design/SKILL.md and follow its Cross-Store Entity Consistency Protocol for every entity that spans more than one store.
+
+Write the completed cross-store consistency table to `docs/plans/architecture-draft.md` as part of the `## Data Strategy` section.
+
+### Data placement strategy document
+
+Read `.agent/skills/prd-templates/references/data-placement-template.md` for the template structure. Create `docs/plans/data-placement-strategy.md` using the template, filling each section with the data decisions confirmed above.
+
+### Propose next step
+
+System architecture and data placement strategy are complete. Next: Run `/create-prd-security` to define the security model, compliance escalation, and integration points.
+
+> If this shard was invoked standalone (not from `/create-prd`), surface this via `notify_user`.