bootstrapping-design-docs
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".
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.
Note: Templates are bundled with the skill (not in design-docs/) per Agent Skills progressive disclosure pattern.
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
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
Stop and ask for [blocking] answers before proceeding.
[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.
- "Can we store captured payloads under
[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.
- 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.