name	bootstrapping-design-docs
description	Creates design document infrastructure including templates, workflows, and a specific design doc skill. Use when setting up design docs for a new project or when the user mentions "bootstrapping-design-docs".

Use the $activate-memories skill if you have not already to get an overview of the project before proceeding. 1. If the `design-docs` folder does not already exist, create a repo-local `design-docs/` workspace (templates + active docs + index). - If the `design-docs` folder already exists, stop and ask the user how to proceed. 2. Create a **project-specific** design doc template. If the user does not specify a specific type of design doc they want to create, we will be creating a general design document template called `base-design-doc.md` for the overall project. 3. Generate a **project-specific** design-doc skill for authoring design docs with: - explicit specs (interfaces, signatures, types) - mandatory test-data acquisition plan for ETL / HTTP / WebSocket work - enforceable guardrails against common agent failure modes - Example: The user wants to make a design doc skill for the ETL pipeline creations in the project. Then your task would be to create a `$etl-design-doc` skill. 4. Support repeated runs to create additional templates (variants) without breaking existing docs.

For the rest of this document {DESIGN_DOC_SKILL_NAME} will refer to the name of the skill we will make that will later be used to generate design docs for this project. Default: creating-design-doc. Once you create the base design doc template and skill, you must ask questions to the user to help clarify anything you are unsure of. This is a joint user-agent process: ask targeted questions when unsure; do not finalize templates without user review.

Create (idempotent; do not overwrite without preserving history): - `design-docs/README.md` - How design docs are written, reviewed, and used for delegated execution. - `design-docs/active/` - Directory for active design documents. - `design-docs/agents/` - Directory for agent-executable XML subtasks. - `.{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/SKILL.md` - The generated `${DESIGN_DOC_SKILL_NAME}` skill. - `.{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/README.md` - Lists available templates and when to use them. - `.{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/base.md` - Meta "base" design doc template (guardrails + structure). - `.{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/.md` - Project-specific templates (e.g., `etl-pipeline.md`, `feature.md`).

Note: Templates are bundled with the skill (not in design-docs/) per Agent Skills progressive disclosure pattern.

**Design docs are written in markdown** - not XML. Markdown is easier for humans to read/edit and for agents to parse during collaboration. Agent-executable subtasks use XML in a separate file under `design-docs/agents/`. Replace `{AGENT_NAME}` with the agent's config directory: - `.aider/` - Aider - `.claude/` - Claude Code - `.codex/` - OpenAI Codex CLI - `.copilot/` - GitHub Copilot - `.cursor/` - Cursor

If the repo has an existing agent config directory, use it. If multiple exist, prefer the current agent's. If none exist, create one.

Before asking questions, scan the repo to ground defaults: If you have not already, run the $activating-memories skill to get an overview of the project.

Languages/frameworks/build files
CI entrypoints
Project Specific Utility modules
DB/migrations
Style rules

1. **Create folder structure** (if missing): - `design-docs/` - `design-docs/active/` - `design-docs/agents/` - `.{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/` - `.{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/`

Write design doc skill and bundled templates:
- design-docs/README.md (workflow + approvals)
- .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/SKILL.md (the skill)
- .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/README.md (template index)
- .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/base.md (meta template with guardrails)
- .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/skill.md (skill creation template)
- .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/feature.md (feature template)
Run Adaptive Questioning Protocol:
- Produce "Detected Defaults Summary"
- Ask triggered questions
- Stop for answers before proceeding
Idempotency:
- Never overwrite existing templates without timestamped backup
- Add new variants to .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/README.md

Ask only questions that materially influence template contents. Every question must be tagged: - `[blocking]` - must be answered to generate correct template or enforce safety - `[important]` - significantly improves template quality / reduces future rework - `[optional]` - preference-level; safe defaults exist - Max 10 questions total. - Each question includes a one-line "why" tying to a template section, guardrail, or convention. Ask only what applies based on scan: - Migrations tooling detected -> ask DB reset/backfill/rollback/testing policy - HTTP/WS dependencies detected -> ask record/replay + fixture storage constraints - Monorepo structure detected -> ask where templates live and how commands differ - No tests/CI detected -> ask what canonical verification commands should be Before writing files, show: - Which variants will be created - Repo-specific defaults that will be baked in - Any tightened guardrails derived from project norms - Any unresolved `[blocking]` items

Stop and ask for [blocking] answers before proceeding.

Ask only what you cannot infer from the scan: 1. `[blocking]` **Template variants desired** - "Which templates do you want generated? (e.g., `feature`, `etl_http_ws`, `db_migration`, `refactor`)" - Why: determines templates bundled with skill.

[blocking] Test integrity policy
- "What is your rule on mocks? (only mock boundaries; prefer record/replay; never mock core transforms)"
- Why: populates guardrails + testing strategy.
[blocking] Data capture constraints
- "Can we store captured payloads under tests/fixtures/? Any size/licensing/PII constraints?"
- Why: populates test-data acquisition plan.
[blocking] Destructive actions boundary
- "What DB reset patterns are allowed in tests? (transactions/temp schema/containers). Forbidden actions?"
- Why: prevents unsafe "delete DB to pass tests" behavior.
[important] Type discipline
- "For Python projects, what is your stance on Optional/None? (forbid unless justified; require invalid states unrepresentable)"
- Why: shapes interface-contract requirements.
[important] Review workflow
- "Stop at Template Delta Preview for approval, or write files and you review diffs?"
- Why: controls collaboration checkpoint.

The base template MUST include these sections (in order):

Identity and lifecycle
Context
Problem
Goals / Non-goals
Requirements (FRs / NFRs)
Constraints and invariants (include DB + test integrity)
Proposed design (architecture, contracts, schemas, idempotency/retries)
Project common utilities that will be used.
Project common utilities that will be created.
Interface contracts (explicit signatures; Optional/None justification required)
Alternatives considered (>=2)
Test data acquisition plan (mandatory for external I/O / ETL)
Testing and verification strategy (commands + CI gates + test integrity rules)
Rollout / migration / ops (flags, backfills, observability, runbook)
Open questions / follow-ups
Subtasks (human-readable checklist for review)

Subtasks Section Format:

## Subtasks

### T1: [Task Title]
- **Summary**: One sentence objective
- **Scope**: What's in / what's out
- **Acceptance**: Binary pass/fail criteria
- **Status**: [ ] Not started / [~] In progress / [x] Complete

### T2: [Task Title]
...

Include verbatim in the design doc skill you create under "Engineering Guardrails for Agent Execution":

Reuse-first rule (anti-duplication): search existing utilities; record decision per task.
No destructive shortcuts: never delete dev/prod data to pass tests; destructive actions require confirmation.
Test integrity (anti-mock-cheating): mock boundaries only; prefer record/replay; do not change tests without spec change approval.
Signature discipline (anti-vagueness): explicit types/invariants; Optional/None requires justification and handling strategy.
Alternatives requirement: evaluate >=2 alternatives + "do nothing".
Uncertainty protocol: ask [blocking] questions when unsure; do not proceed.

- `design-docs/` exists with README + `active/` + `agents/` subdirectories - name of ${DESIGN_DOC_SKILL_NAME} confirmed with user. - `${DESIGN_DOC_SKILL_NAME}` skill exists at `.{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/` - Templates bundled at `.{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/` - `base.md` includes guardrails and human-readable subtasks section format - At least one project-specific template variant exists with repo-specific test commands - Skill workflow: human-readable subtasks in main doc -> user approval -> XML in `design-docs/agents/` - No existing config directory -> create one for current agent - Multiple templates requested -> generate each as separate variant file - User wants immediate write vs preview -> honor preference from question 6 - Scan finds nothing -> ask user for stack/commands explicitly - Conflicting conventions -> note in template as "resolve before use" - Overwriting existing templates -> create backup with timestamp first

Install Skill

SKILL.md