cfsa-antigravity 1.0.0

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

@@ -0,0 +1,207 @@
+---
+description: Verify operational infrastructure after the infrastructure or auth slice — CI/CD green, staging live, migrations clean, auth working
+pipeline:
+  position: 9.5
+  stage: verification
+  predecessors: [implement-slice]
+  successors: [implement-slice, validate-phase]
+  skills: [testing-strategist, deployment-procedures, systematic-debugging, prd-templates]
+  calls-bootstrap: false
+---
+
+// turbo-all
+
+# Verify Infrastructure
+
+Operational verification gate that runs after the `00-infrastructure` slice and again after the auth slice. No feature slice may begin until this workflow produces a green report.
+
+---
+
+## 0. Placeholder audit
+
+Scan the repository for any remaining `{{PLACEHOLDER}}` values:
+
+```bash
+grep -rn '{{' --include='*.md' --include='*.ts' --include='*.json' . | grep -v node_modules | grep -v '.git/'
+```
+
+**If any `{{PLACEHOLDER}}` values are found** → **STOP.** Run `/bootstrap-agents` to fill them before proceeding.
+
+**Pass criteria**: Zero `{{PLACEHOLDER}}` values in the repository (excluding `node_modules` and `.git`).
+
+> Update report: Mark check 0 as `✅` in the report file.
+
+---
+
+## 0.5. Determine trigger
+
+Read the current phase plan (e.g., `docs/plans/phases/phase-1.md`) to identify which slice just completed.
+
+- **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`.
+
+---
+
+## 0.6. Initialize report
+
+Read `.agent/skills/prd-templates/references/infrastructure-report-template.md` for the report structure. Create the report file at the path determined in Step 0.5 using the **Initial Report** template with all checks marked `⏳`.
+
+---
+
+## 1. CI/CD config check
+
+Read .agent/skills/testing-strategist/SKILL.md and follow its methodology.
+Read .agent/skills/systematic-debugging/SKILL.md and follow its methodology.
+
+Read .agent/skills/{{CI_CD_SKILL}}/SKILL.md and follow its pipeline configuration conventions.
+
+Locate the CI/CD configuration file (e.g., `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`).
+
+Verify the configuration includes: lint step, type-check step, test step, build step.
+
+**If no CI/CD config exists** → **STOP.** Mark check 1 as `❌` in the report.
+
+**Pass criteria**: CI/CD configuration exists and covers lint, type-check, test, and build.
+
+> Update report: Mark check 1 as `✅`.
+
+---
+
+## 2. CI/CD green check
+
+Verify the CI/CD pipeline has run for the latest commit and ALL jobs are passing.
+
+**If CI/CD is red** → **STOP.** Mark check 2 as `❌` with failing job names and errors.
+
+**Pass criteria**: CI/CD pipeline is green for the latest commit.
+
+> Update report: Mark check 2 as `✅`.
+
+---
+
+## 3. Environment audit
+
+1. Read the project's environment template (`.env.example`, `.env.template`, or equivalent)
+2. Verify all required environment variables are documented with descriptions
+3. Verify no secrets are hardcoded in source code — scan for patterns like `sk_live_`, `AKIA`, hardcoded tokens
+4. Verify `.env` files are in `.gitignore`
+
+**If secrets are found in source** → **STOP.** Mark check 3 as `❌`. Remove them immediately, rotate credentials, re-run.
+
+**Pass criteria**: All env vars documented, no secrets in source, `.env` in `.gitignore`.
+
+> Update report: Mark check 3 as `✅`.
+
+---
+
+## 4. Migration check
+
+Read .agent/skills/{{ORM_SKILL}}/SKILL.md and follow its migration and schema conventions.
+
+1. Run the migration status command (e.g., `prisma migrate status`, `drizzle-kit status`, or equivalent)
+2. Verify no pending or failed migrations
+3. Verify migration files exist in the expected directory
+4. Check that rollback scripts or down migrations exist for each migration
+
+**If migrations are pending or failed** → **STOP.** Mark check 4 as `❌`.
+
+**Pass criteria**: Migration status clean. All migrations successful. Rollback capability exists.
+
+> Update report: Mark check 4 as `✅`.
+
+---
+
+## 5. Staging deployment
+
+Read .agent/skills/{{HOSTING_SKILL}}/SKILL.md and follow its deployment conventions.
+Read .agent/skills/deployment-procedures/SKILL.md and follow its pre-deployment checklist and verification protocol.
+
+1. Deploy to staging using the project's deployment process
+2. Verify deployment succeeded — no rollback triggered, no error logs
+3. Verify the application is accessible at the staging URL
+4. Hit the health check endpoint (e.g., `GET /api/health` or `/healthz`)
+5. Verify it returns HTTP 200 with a valid response body confirming database connectivity
+
+**If deployment or health check fails** → **STOP.** Mark check 5 as `❌`.
+
+**Pass criteria**: Staging deployment succeeds, application accessible, health endpoint returns 200.
+
+> Update report: Mark check 5 as `✅`.
+
+---
+
+## 6. Auth smoke test (conditional)
+
+Read the phase plan to determine if the auth slice has been completed.
+
+**If auth has NOT been implemented** → Skip this step and mark as ⏭️ in the report.
+
+If auth IS implemented:
+1. Obtain a valid auth token using the project's authentication flow
+2. Hit at least one authenticated route with a valid token — verify 200 response
+3. Hit at least one protected route without a token — verify 401 response
+4. Hit at least one protected route with an expired/invalid token — verify 401/403 response
+
+**If any auth check fails** → **STOP.** Mark check 6 as `❌`.
+
+**Pass criteria**: Authenticated routes accept valid tokens. Protected routes reject missing/invalid tokens.
+
+> Update report: Mark check 6 as `✅` or `⏭️ skipped`.
+
+---
+
+## 6.5. Logging gate
+
+Read `docs/plans/*-architecture-design.md` section `## Observability Architecture` to load the confirmed logging decisions.
+
+1. Verify structured startup log is emitted on application boot with the following 5 required fields:
+   - `timestamp` (ISO 8601)
+   - `level` (info or higher)
+   - `service` (application name)
+   - `env` (environment name)
+   - Correlation ID field (name as specified in architecture-design.md, e.g., `requestId`, `traceId`)
+2. Verify log reaches configured destination (stdout, file, or cloud service as documented)
+3. Verify PII fields named in `## Observability Architecture` are NOT present in any log output
+
+**If startup log is missing any of the 5 required fields** → **STOP.** Mark check 6.5 as `❌`.
+**If log does not reach configured destination** → **STOP.** Mark check 6.5 as `❌`.
+**If PII fields appear in log output** → **STOP.** Mark check 6.5 as `❌`.
+
+**Pass criteria**: Structured startup log emitted with all 5 fields. Log reaches destination. No PII fields in output.
+
+> Update report: Mark check 6.5 as `✅`.
+
+---
+
+## 6.6. Error tracking gate
+
+1. Confirm error tracking SDK is initialized (Sentry, Datadog, or equivalent as documented in `## Observability Architecture`)
+2. Send a test error event from the application and verify it appears in the error tracking dashboard
+3. Verify PII scrubbing is active — test error event must NOT contain any PII field values named in the architecture document
+
+**If SDK is not initialized** → **STOP.** Mark check 6.6 as `❌`.
+**If test error event does not appear in dashboard** → **STOP.** Mark check 6.6 as `❌`.
+**If PII fields appear in error event** → **STOP.** Mark check 6.6 as `❌`.
+
+**Pass criteria**: Error tracking SDK initialized. Test event received. PII scrubbing active.
+
+> Update report: Mark check 6.6 as `✅`.
+
+---
+
+## 7-8. Finalize report
+
+Finalize the report using the **Final Report** template from `.agent/skills/prd-templates/references/infrastructure-report-template.md`. Update the Verdict field to `✅ PASS` or `❌ FAIL` and fill in Failures and Next Steps sections.
+
+The final report must include all eight gate checks: 0 (placeholder audit), 1 (CI/CD config), 2 (CI/CD green), 3 (environment audit), 4 (migration check), 5 (staging deployment), 6 (auth smoke test), 6.5 (logging gate), 6.6 (error tracking gate).
+
+---
+
+## 9. Present results
+
+Use `notify_user` to present the verification verdict:
+
+- **GREEN (all checks pass)**: "✅ Infrastructure verification passed. Next: proceed to the next feature slice with `/implement-slice`."
+- **RED (any check fails)**: "❌ Infrastructure verification failed. [list failures]. Fix and re-run `/verify-infrastructure`."

package/template/.agent/workflows/write-architecture-spec-deepen.md

@@ -0,0 +1,139 @@
+---
+description: Iterative deepening passes, spec writing, index updates, and ambiguity gate for the write-architecture-spec workflow
+parent: write-architecture-spec
+shard: deepen
+standalone: true
+position: 2
+pipeline:
+  position: 4.2
+  stage: specification
+  predecessors: [write-architecture-spec-design]
+  successors: [write-be-spec, write-fe-spec]
+  skills: [technical-writer, resolve-ambiguity]
+  calls-bootstrap: true
+---
+
+// turbo-all
+
+# Write Architecture Spec — Deepen & Finalize
+
+Run iterative deepening passes, write the completed spec, update indexes, run the ambiguity gate, and present for review.
+
+**Prerequisite**: Read the shard file at `docs/plans/ia/[shard-name].md`. Sections should be filled in from the design shard (not skeleton placeholders). If sections are still skeleton placeholders, the design shard has not completed — run `/write-architecture-spec-design` first before running this shard.
+
+---
+
+## 8. Iterative deepening passes
+
+Read .agent/skills/resolve-ambiguity/SKILL.md for the adversarial and "what if" passes.
+Read .agent/skills/code-review-pro/SKILL.md and follow its adversarial review methodology.
+
+> **Why multiple passes**: Each pass reveals edge cases that are only visible in
+> the context of the complete draft. The first pass catches obvious gaps. The second
+> catches interactions between sections that create new edge cases. The third catches
+> the subtle "what if" scenarios that only emerge after you've been staring at the
+> full picture. Every pass makes the subsequent pass more productive.
+
+### Pass 1: Cross-section consistency
+
+Re-read the complete draft (interactions + contracts + data model + access control + edge cases together) and look for:
+- Interactions that reference data fields not in the schema
+- Access rules that don't cover all interaction types
+- Edge cases that imply missing error codes in contracts
+- Event schemas that carry fields not in the data model
+
+Fix every inconsistency found. Present findings to the user.
+
+### Pass 2: "What if" scenarios
+
+For each interaction, ask:
+- What if the user does this twice?
+- What if the user does this and then immediately does that?
+- What if the input is technically valid but semantically nonsensical?
+- What if the dependent service is slow/down/returns unexpected data?
+- What if the user's role changes mid-operation?
+
+Add any new edge cases, error codes, or access rules discovered. Present findings to the user.
+
+### Pass 3: Adversarial thinking
+
+Put on the attacker hat:
+
+Read .agent/skills/code-review-pro/SKILL.md and follow its adversarial review methodology for this pass.
+
+- How could someone abuse this feature? (Rate limiting, data scraping, privilege escalation)
+- How could someone bypass the access control? (Direct API calls, parameter tampering, timing attacks)
+- How could someone use this to access another user's data?
+- How could a junior account bypass age restrictions through this domain?
+
+Add any new security edge cases or access rules. Present findings to the user.
+
+### Additional passes
+
+If any pass produces significant new content, do another pass — the new content
+may reveal further edge cases. Stop when a pass produces no meaningful additions.
+
+## 9. Write the spec to `docs/plans/ia/[shard-name].md`
+
+Read .agent/skills/technical-writer/SKILL.md for the spec writing step.
+
+Replace the skeleton sections in `docs/plans/ia/[shard-name].md` with the full content from all passes. Ensure all cross-shard dependencies are bidirectional.
+
+## 10. Update IA index
+
+Change the shard's status from 🔲 to ✅ in `docs/plans/ia/index.md`.
+
+## 11. Update spec pipeline
+
+Read `.agent/skills/session-continuity/protocols/08-spec-pipeline-update.md` and follow the **Spec Pipeline Update Protocol**
+to mark this shard's IA column as complete in `.agent/progress/spec-pipeline.md`.
+
+## 11.5. Bootstrap Tech Stack Skills (if applicable)
+
+If the shard you just completed is `00-architecture-design.md` (which definitively chooses the project's tech stack):
+Read `.agent/workflows/bootstrap-agents.md` and execute its utility instructions immediately to fill placeholders and provision skills based on the finalized tech stack.
+
+## 12. Ambiguity gate
+
+Read `.agent/skills/session-continuity/protocols/ambiguity-gates.md` and run the **Ambiguity Gates**:
+
+- **Micro**: Walk each feature, interaction, data model field, access rule, and edge case.
+  Would an implementer need to guess about any of them? If yes — fix it now.
+- **Macro**: Would the BE spec writer need to guess anything from this IA shard?
+  If yes — fix it now. The shard is not done until the downstream phase can work
+  from it without assumptions.
+
+**Two-implementer test**: For each element that passes the micro check, apply the two-implementer test: *"Would two different developers, reading only this IA shard with no other context, make the same implementation decision?"* If the answer is "probably not" — fix it now.
+
+**Devil's advocate pass**: After the gates pass, run a devil's advocate pass: for each feature, interaction, data model field, and access rule, ask "What would a junior developer get wrong about this?" Any element that reveals a gap gets fixed before presenting.
+
+## 13. Full ambiguity audit (mandatory when this is the last IA shard)
+
+1. Read `docs/plans/ia/index.md`
+2. Check if all shards show ✅
+
+**More shards remain**: Proceed to the next shard. Do not propose `/write-be-spec` yet — the IA layer is not complete.
+
+**This is the last shard** (all shards show ✅): Run `/audit-ambiguity ia` now. This is **not optional** — it is a mandatory gate before any BE spec work begins.
+
+> **Why**: Catching ambiguity across the full IA layer costs minutes. Discovering it during BE spec writing — or worse, during implementation — costs days of rework across multiple specs and slices.
+
+**Hard gate**: Do NOT propose `/write-be-spec` until `/audit-ambiguity ia` scores 0% ambiguity.
+
+## 14. Request review and propose next steps
+
+You may only notify the user of completion if you have completed the Cross-Reference check, the Dependency Graph validation, and the Ambiguity gate.
+
+Use `notify_user` to present the completed IA shard for review. Your message MUST include:
+1. **The shard created** (link to the file)
+2. **Cross-reference verification** (confirmation that links are bidirectional)
+3. **Ambiguity Gate confirmation** (confirmation that no implementer would need to guess)
+4. **The Pipeline State** (propose the next task from the options below)
+
+Do NOT proceed to the next step until the user sends a message explicitly approving this output. Proposing next steps is not the same as receiving approval. Wait for explicit approval before continuing.
+
+Read `.agent/progress/spec-pipeline.md` to determine the pipeline state, then propose the appropriate next step:
+
+- **More skeleton shards remain** → "Next: Run `/write-architecture-spec` for shard [next-shard-number]"
+- **All IA shards complete** → "All IA shards complete and /audit-ambiguity ia has already run (mandatory Step 13 above). If it scored 0%, proceed to /write-be-spec. If it found gaps, resolve them and re-run /audit-ambiguity ia as a fresh invocation before proceeding."
+- **Self-audit found unresolvable issues** → Present the issues for discussion before proposing next step

package/template/.agent/workflows/write-architecture-spec-design.md

@@ -0,0 +1,202 @@
+---
+description: Explore requirements, map interactions, and design contracts/data models/access control for the write-architecture-spec workflow
+parent: write-architecture-spec
+shard: design
+standalone: true
+position: 1
+pipeline:
+  position: 4.1
+  stage: specification
+  predecessors: [decompose-architecture]
+  successors: [write-architecture-spec-deepen]
+  skills: [brainstorming, resolve-ambiguity, database-schema-design]
+  calls-bootstrap: false
+requires_placeholders: [DATABASE_SKILLS, SECURITY_SKILLS]
+---
+
+// turbo-all
+
+# Write Architecture Spec — Design
+
+Explore requirements, map all interactions, and define contracts, data models, access control, event schemas, and edge cases.
+
+**Prerequisite**: Skeleton IA shard must exist in `docs/plans/ia/`. If it does not, tell the user to run `/decompose-architecture` first.
+
+## 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 0.5.
+
+| Placeholder | Filled by | Recovery | Why this matters |
+|---|---|---|---|
+| `{{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 model design (Step 4) would produce schema patterns incompatible with the chosen database. |
+| `{{SECURITY_SKILLS}}` | `/create-prd-stack` when security tooling is confirmed | If `docs/plans/*-architecture-design.md` exists, read it and extract the confirmed security framework, then run `/bootstrap-agents SECURITY=<confirmed-framework>`. Otherwise run `/create-prd-stack` first. | Edge case and attack surface analysis (Step 7) would run without the project's security skill, missing stack-specific threat vectors. |
+
+For the hard stop message format and recovery instructions, see `.agent/skills/prd-templates/references/placeholder-guard-template.md`.
+
+Only proceed to Step 0.5 when both placeholders report no literal `{{` characters.
+
+---
+
+## 0.5. Re-run check
+
+Before loading skills, check whether the shard file at `docs/plans/ia/[shard-name].md` already has content beyond skeleton placeholders (look for filled-in sections vs empty `<!-- TODO -->` markers).
+
+- **If sections are already filled**: Present the current state of the file and ask: "Some sections are already written. Do you want to **continue from where you left off** (skip filled sections), or **redo specific sections** (tell me which ones)?" Wait for the user's answer before proceeding.
+- **If the file is still a skeleton**: Proceed normally.
+
+---
+
+## 1. Explore requirements
+
+### 1a. Read the authoritative sources
+
+Read the following files and build a **reconciliation table** comparing what each source says about this shard's features. `docs/plans/ideation.md` is the **primary source of truth** for sub-features — the architecture design is secondary context.
+
+1. `docs/plans/ideation.md` — the primary sub-feature inventory (locate the section for this shard's domain)
+2. The shard's `## Features` section (seeded during `/decompose-architecture-structure`)
+3. `docs/plans/vision.md` — Must Have features relevant to this domain
+
+Read .agent/skills/architecture-mapping/SKILL.md and follow its Sub-Feature Reconciliation Protocol. Build the reconciliation table comparing ideation.md against the shard skeleton and apply mismatch handling rules before proceeding to Step 1b.
+
+### 1b. Scope confirmation
+
+Present the reconciled `## Features` list to the user, including a count of newly added sub-features:
+
+> **Reconciled features for [Shard NN — Domain Name]:**
+> 
+> [bullet list of all sub-features, with `[Architecture-only]` markers where applicable]
+> 
+> **[N] sub-features added from ideation.md** that were missing from the shard skeleton.
+> **[M] sub-features marked `[Architecture-only]`** — not found in ideation.md, added during decomposition.
+> 
+> "Does this feature list match your intent for this domain? Any sub-features to add, remove, or re-scope?"
+
+**Wait for explicit user confirmation before proceeding.** If the user modifies the list, update the shard's `## Features` section in `docs/plans/ia/[shard-name].md` immediately.
+
+**Post-reconciliation calibration check**: Count the total confirmed sub-features. If the count is **≥ 10**, follow the **Sub-Feature Complexity Split Protocol** in `.agent/skills/architecture-mapping/SKILL.md` — present the split proposal, wait for approval, and redirect to `/decompose-architecture-validate` before continuing. Do NOT proceed to Step 2 with an oversized shard.
+
+If the sub-feature count is **< 10**, proceed directly to Step 1c.
+
+### 1c. Load brainstorming skill
+
+Read `.agent/skills/brainstorming/SKILL.md` and use it to explore any remaining ambiguous sub-features — those marked `[Architecture-only]` that the user hasn't explicitly confirmed, or any sub-feature whose scope boundary (what's in, what's out) is still unclear after 1b.
+
+> **Authoring pattern for Steps 2–7**: After designing each section, (1) present it to the user with the targeted review questions listed below, (2) refine based on their feedback, (3) write the completed section to `docs/plans/ia/[shard-name].md` immediately — do not batch writes until Step 8.
+
+## 2. Map all interactions
+
+For each feature in the shard, document:
+- User action → API call → data mutation → response
+- Which surfaces are involved (public, dashboard, admin, API)
+- What events are emitted
+- Error states and edge cases
+
+**Review questions**: "Does this capture all the ways a user touches this domain?" / "Are there admin/system-initiated actions I'm missing?" / "What happens in each failure case?"
+
+## 3. Define contracts
+
+Read .agent/skills/rest-api-design/SKILL.md and follow its methodology.
+
+For each interaction, define the contract shape:
+- Request shape (params, query, body)
+- Response shape (all fields typed)
+- Error shape (specific error codes)
+- Note: actual Zod schemas written in BE spec phase
+
+**Review questions**: "Are there fields I'm missing from these requests/responses?" / "Are these error codes specific enough?"
+
+## 4. Design data models
+
+Read each skill listed in `{{DATABASE_SKILLS}}` (comma-separated). For each skill directory name, read `.agent/skills/[skill]/SKILL.md` before proceeding. Also load these community skills for guidance:
+- `.agent/skills/database-schema-design/SKILL.md` — Schema design principles
+- `.agent/skills/error-handling-patterns/SKILL.md` — Error categories for contracts
+- `.agent/skills/technical-writer/SKILL.md` — Specification clarity
+- Tables/collections, fields, types
+- Relationships (graph edges, foreign keys, etc.)
+- Indexes for query patterns
+- Constraints and validation rules
+
+**Review questions**: "Does this schema capture everything this domain needs to store?" / "Are the relationships and cardinalities correct?" / "Are there derived/computed fields I should account for?"
+
+**Missing skill fallback**: If any database or security skill listed above is not installed and not in the MANIFEST, read `.agent/skills/find-skills/SKILL.md` and follow its discovery methodology before proceeding.
+
+## 5. Design access control
+
+Read .agent/skills/security-scanning-security-hardening/SKILL.md and apply its access control and authorization design methodology.
+
+- Permission matrix (who can read/write/delete what)
+- Role-based restrictions
+- Age restrictions (if applicable)
+- Escalation paths (Guardian, Admin)
+- Admin-only operations
+
+**Review questions**: "Can you think of a scenario where a user should be blocked that this matrix allows?" / "Can you think of a scenario where a user should be allowed that this matrix blocks?"
+
+## 5.5. Accessibility specifications
+
+Read `{{SURFACES}}` to determine the project's target surfaces.
+
+**If surfaces include `web`, `mobile`, or `desktop`:**
+
+Read `.agent/skills/accessibility/SKILL.md` and apply its WCAG 2.1 AA methodology.
+
+For each user interaction documented in Step 2 (`## User Interactions`), identify and document:
+- **Keyboard navigation path** — tab order and focus management for this interaction
+- **Screen reader semantics** — ARIA roles, labels, and live regions required
+- **Color contrast** — requirements for any new visual states (loading, error, empty, disabled)
+- **Motion/animation** — `prefers-reduced-motion` implications for any transitions or animations
+- **Touch target sizes** — minimum 44×44 px (mobile surfaces only)
+
+**Review questions**: "Are there any interactions in this domain that could be problematic for keyboard-only users?" / "Are there any visual states (loading, error, empty, disabled) that need specific ARIA announcements?" / For mobile: "Do any touch targets fall below 44×44px minimum?"
+
+**If surfaces are `api`, `cli`, or `extension` only:** Write `"Not applicable — no visual surfaces"` in the `## Accessibility` section.
+
+## 6. Design event schemas (if applicable)
+
+- Event name, payload shape, emitter, consumers
+- Async vs sync processing
+- Retry semantics
+
+## 7. Document edge cases
+
+Read .agent/skills/resolve-ambiguity/SKILL.md and follow its methodology.
+
+Read each skill listed in `{{SECURITY_SKILLS}}` (comma-separated). For each skill directory name, read `.agent/skills/[skill]/SKILL.md` before proceeding.
+For each skill in {{SECURITY_SKILLS}}, follow its attack surface methodology for edge case identification.
+
+- Rate limits and abuse scenarios
+- Concurrent access handling
+- Deletion cascades
+- State transition conflicts
+- Empty/null states
+
+**Review questions**: "What's the worst thing a malicious user could try in this domain?" / "What happens if two users do the same thing at the same time?" / "What happens when related data is deleted?"
+
+## 7.5. Write deep dive files (if applicable)
+
+Check whether the current shard references any deep dive candidates. To do this:
+1. Read the shard file at `docs/plans/ia/[shard-name].md` and look for any links to `docs/plans/ia/deep-dives/` files in the "Deep Dives Needed" section or anywhere in the document.
+2. List the files in `docs/plans/ia/deep-dives/` and identify which ones are referenced by this shard.
+
+**If no deep dives are referenced**: Skip this step entirely.
+
+**If deep dives are referenced**: For each referenced deep dive file:
+
+1. Read the current content of `docs/plans/ia/deep-dives/[feature-name].md` to check if it is still a skeleton (empty or contains only placeholder comments).
+2. **If already has full content**: Skip — do not overwrite.
+3. **If still a skeleton**: Write exhaustive subsystem detail — algorithms/state machines, technology choices with rationale, phasing strategy, detailed data schemas, failure modes and recovery, integration contracts, performance characteristics, and security considerations.
+
+   The parent shard's "Deep Dives Needed" section should already contain a summary + link. Do not duplicate the full content in the parent shard — the deep dive file IS the content.
+
+> **Write now**: Write the completed deep dive content to `docs/plans/ia/deep-dives/[feature-name].md`. Do not wait until Step 8.
+
+## 8. Present all sections and request approval
+
+All sections are now written to `docs/plans/ia/[shard-name].md`. Please review the file directly and confirm it's ready for deepening passes.
+
+> **Do NOT proceed to `/write-architecture-spec-deepen` until the user approves all sections. Proposing next steps is not the same as receiving approval.**
+
+Once approved, run `/write-architecture-spec-deepen`.
+
+> **Note**: The deepen shard will run iterative passes over the approved content — the user does not need to re-approve individual sections during deepening.
+

package/template/.agent/workflows/write-architecture-spec.md

@@ -0,0 +1,63 @@
+---
+description: Create or update Layer 1 architecture spec — interactions, contracts, data models, RBAC, event schemas
+pipeline:
+  position: 4
+  stage: specification
+  predecessors: [decompose-architecture]
+  successors: [write-be-spec, write-fe-spec] # parallel fork
+  skills: [resolve-ambiguity, database-schema-design, error-handling-patterns, technical-writer]
+  calls-bootstrap: true # may introduce new contracts/patterns
+shards: [write-architecture-spec-design, write-architecture-spec-deepen]
+---
+
+// turbo-all
+
+# Write Architecture Spec (IA Shard)
+
+Fill in a skeleton IA shard with full interaction details, data models, access control, and edge cases.
+
+**Input**: A skeleton IA shard from `/decompose-architecture`
+**Output**: Complete IA shard ready for BE spec writing
+
+> **Process model**: This workflow is collaborative and iterative. Each section
+> is drafted, presented to the user for discussion, and refined before moving on.
+> After all sections are drafted, multiple deepening passes catch edge cases that
+> only become visible in the context of the complete picture. The shard is not done
+> until both the agent and the user agree it's deep enough for a developer to
+> implement without asking a single clarifying question.
+
+---
+
+## Shard Overview
+
+| # | Shard | What It Does |
+|---|-------|-------------|
+| 1 | [`write-architecture-spec-design`](.agent/workflows/write-architecture-spec-design.md) | Explores requirements, maps interactions, defines contracts, data models, access control, events, and edge cases |
+| 2 | [`write-architecture-spec-deepen`](.agent/workflows/write-architecture-spec-deepen.md) | Runs iterative deepening passes, writes the spec, updates indexes, runs ambiguity gate, presents for review |
+
+---
+
+## Orchestration
+
+### Step A — Run `.agent/workflows/write-architecture-spec-design.md`
+
+Uses the brainstorming skill to clarify scope, then systematically designs all sections: interaction maps, contract shapes, data models, access control, event schemas, and edge cases. Each section is presented to the user for discussion and refinement.
+
+### Step B — Run `.agent/workflows/write-architecture-spec-deepen.md`
+
+Runs multiple deepening passes (cross-section consistency, "what if" scenarios, adversarial thinking), writes the completed spec to the IA directory, updates the IA index, runs the ambiguity gate, and presents for review.
+
+---
+
+## Quality Gate
+
+Before presenting to the user, verify:
+
+Read .agent/skills/code-review-pro/SKILL.md and apply its adversarial review discipline.
+
+- [ ] Every interaction has a complete flow (action → call → mutation → response)
+- [ ] Every contract has typed request, response, and error shapes
+- [ ] Data model has all fields, relationships, indexes, and constraints
+- [ ] Access control covers all roles and all interaction types
+- [ ] Edge cases cover concurrent access, deletion cascades, and state conflicts
+- [ ] Cross-shard dependencies are bidirectional