Create design documents for Aitana Labs features in the correct format and location. Use when user asks to create a design doc, plan a feature, write a spec, or document a design. Also use when user says "design", "RFC", "proposal", or wants to think through a feature before implementing. Handles both planned and implemented docs.
Create design documents for Aitana Labs features in the correct format and location. Use when user asks to create a design doc, plan a feature, write a spec, or document a design. Also use when user says "design", "RFC", "proposal", or wants to think through a feature before implementing. Handles both planned and implemented docs.
Design Doc Creator
Create well-structured design documents for Aitana Labs features following the project's conventions.
Quick Start
# User says: "Create a design doc for adding Slack integration"# This skill will:# 1. Search for existing related design docs# 2. Create docs/design/<version>/slack-integration.md# 3. Fill template with proper structure (problem, goals, design, testing)# 4. Include frontend/backend impact analysis
When to Use This Skill
Invoke this skill when:
User asks to "create a design doc", "write a design doc", or "write a spec"
User says "plan a feature" or "design a feature"
User mentions "RFC", "proposal", or "technical design"
Before starting implementation of a non-trivial feature
After completing a feature (to move doc to implemented/)
Available Scripts
scripts/create_design_doc.sh <version> <doc-name>
Create a new design document in docs/design/v<version>/.
Move a completed design document into its version's implemented/ subfolder
and flip the Status frontmatter. Idempotent.
.claude/skills/design-doc-creator/scripts/move_to_implemented.sh slack-integration
# docs/design/v6.0.0/slack-integration.md# -> docs/design/v6.0.0/implemented/slack-integration.md# Also moves the companion *-sprint.md if present.# Flips **Status**: Planned|Proposed -> Implemented, refreshes Last Updated,# and appends an Implementation Report stub to the design doc.
Workflow
Creating a Design Doc
1. Gather Requirements
Ask the user:
What feature are you designing?
What priority? (P0/P1/P2)
Estimated effort? (e.g., 2 days, 1 week)
Frontend-only, backend-only, or fullstack?
Any dependencies on other features?
2. Check for Existing Work
Before writing, search for related design docs and existing code:
# Check existing design docsls docs/design/ docs/design/implemented/
# Search for related components/services
grep -r "FeatureName" src/ backend/ --include="*.tsx" --include="*.ts" --include="*.py"
3. Audit for Systemic Issues
Before writing a design doc for a bug fix, ALWAYS ask: "Is this part of a larger pattern?"
The Anti-Pattern (incremental special-casing):
v1: Add feature for case A
v2: Bug! Add special case for B
v3: Bug! Add special case for C
...forever patching
Analysis Checklist:
Is this a one-off or part of a pattern?
Search codebase for similar code paths
Check if other types/cases have the same gap
Look at git history - has this area been patched repeatedly?
Design fix to cover ALL cases, not just the reported one
Read docs/product-axioms.md and fill the Axiom Alignment table in the design doc:
Score each of the 10 axioms: +1 (Aligned), 0 (Neutral), -1 (Conflicts)
Write a brief note for each non-zero score explaining the reasoning
For any -1 score, write a justification in the Conflict Justifications section
Calculate the net score and verify it meets the threshold (>= +4)
Verify hard-fail rules:
No more than 2 axioms score -1
EARNED TRUST is not -1 if feature involves user-facing data
SECURE BY CONSTRUCTION is not -1 if feature introduces new data access
If the net score is below +4 or hard-fail rules are violated, redesign before proceeding. Discuss tradeoffs with the user and adjust the design to improve alignment.
5b. Standards Compliance Check (MANDATORY)
Before defining any schema, format, protocol, or data model, check whether an established standard already exists. Do not invent custom formats when open standards apply (Axiom #6: Protocol Over Custom).
Checklist:
Search for existing standards in the domain (specs, RFCs, open protocols)
Check ADK docs (adk.dev) for native support (skills, agents, tools, sessions)
Check Agent Skills spec (agentskills.io/specification) for skill definitions
Check protocol standards: AG-UI, A2UI, MCP, A2A
If using Claude Code patterns, check existing SKILL.md conventions
If a standard exists: adopt it, extend via metadata — do not reinvent
If the design invents a custom format where a standard exists, it must score -1 on Axiom #6 and provide a written justification for why the standard is insufficient.
5b-ter. Framework-Native Capability Check (MANDATORY — "is this already supported?")
5b checks whether a format already exists. This step checks whether a
capability already exists. Before specifying ANY custom plumbing — a
side-channel for passing data, a custom store, a bespoke retention/persistence
mechanism, a hand-rolled injection/transform hook — prove the framework stack
doesn't already do it natively. The most expensive mistakes on this project
have been re-implementing something the protocol/framework already ships.
For each piece of custom plumbing the design proposes, answer in the doc:
AG-UI — can the message/event protocol already carry this? Check
UserMessage.content (it's string | InputContent[] — text and
image/audio/video/document parts are native), forwardedProps, state
snapshots, and the event types. Read the installed package types
(backend/.venv/.../ag_ui/core/types.py, frontend/node_modules/@ag-ui/core),
not memory.
ag_ui_adk — does the adapter already convert/persist this? Check
ag_ui_adk/utils/converters.py (convert_message_content_to_parts,
convert_ag_ui_messages_to_adk) before writing a before_model_callback or
a side-channel extractor.
ADK — do sessions/events/artifacts/memory already persist + replay this?
Anything placed in a session event is replayed every turn for the session
lifetime (and survives rejoin) for free; artifacts (GCS-backed) handle
binary blobs. Don't build a custom cache/store for either.
MCP / A2UI / A2A — same question for tools, declarative UI, discovery.
Cautionary example (1.1.7 image upload). A first pass shipped a
forwardedProps.attachments side-channel + a before_model_callback that
stashed image bytes in a module dict and injected them per-turn (and then a
follow-up was about to add artifact storage for retention). All of it was
unnecessary: AG-UI ImageInputContent + ag_ui_adk's media converter +
ADK session events already transport, convert, and retain images
natively. The native path was less code and got session-lifetime
retention for free. The custom version was caught only after it was built.
If after this check custom plumbing is still genuinely required (the native
capability is absent or insufficient), say so explicitly in the doc with the
evidence (the type/converter you checked and why it doesn't cover the case).
Silence is not allowed — the doc must show the check happened.
5b-bis. Consider CLI Affordances (MANDATORY for any feature with developer-facing surface)
The v6 platform ships a local-dev CLI (aitana, see local-dev-cli.md) that hosts every developer touchpoint. Whenever you write a design doc, ask: does this feature need a CLI command to be ergonomic? If yes, scope that command in the same doc so it ships with the feature, not as a follow-up.
Heuristic — add a CLI command when the feature involves any of:
A new resource type that gets created/listed/updated/deleted by developers (e.g., skills, MCP servers, datastores, evalsets, channels) — typically aitana <resource> new/list/get/push/pull/diff
A new local process developers will run (e.g., a sidecar service) — add to cli/services.yaml so aitana dev up starts it
A new file format developers parse or generate locally (e.g., a new document type) — aitana <subsystem> parse <file> for a quick local check
A new external system to inspect (e.g., MCP servers, A2A endpoints, BigQuery tables) — aitana <subsystem> probe/list/call
A new evaluation or smoke-test target — aitana eval run <name>
Anything currently requiring a curl + a Firebase token + JSON-by-hand to test — replace with a typed CLI command
What to include in the design doc when a CLI command is in scope:
A small "CLI Surface" subsection under Design listing the new commands, their flags, and their position in the existing aitana command tree
A line item in the Implementation Plan for the CLI work (typically 0.1-0.25 day per command — Click subcommand + an httpx call + a unit test)
A line in Success Criteria asserting the new command works end-to-end
Update cli/services.yaml if the feature adds a local process
When to skip:
Pure frontend features with no developer-facing API (e.g., a CSS refactor, a Tailwind theme tweak)
Features whose only "config" is a code change (not a runtime resource)
One-off bug fixes
The anti-pattern: shipping a feature, then six weeks later writing a follow-up design doc to "add CLI support". By then, three other features have shipped without CLI support either, and the dev loop has decayed to "open three terminals and curl with Firebase tokens". Bake the command into the original doc.
5c. Verify API and Technical Details Against Authoritative Sources (MANDATORY)
Design docs that include code examples, API usage, or integration patterns MUST verify those details against authoritative sources. Do not write API calls, class names, or function signatures from memory — LLM training data goes stale and APIs change frequently.
Verification sources (in priority order):
Domain
Source
How to Access
ADK (agents, tools, sessions)
ADK MCP server
mcp__adk-mcp__search_code (search by class/function name), mcp__adk-mcp__read_docs (search by topic)
ADK (skills)
adk.dev
WebFetch on https://adk.dev/skills/ (MCP server doesn't cover skills yet)
WebFetch on https://ag-ui.com/ or https://docs.ag-ui.com/
A2UI protocol
a2ui.org
WebFetch on https://a2ui.org/
MCP protocol
modelcontextprotocol.io
WebFetch on https://modelcontextprotocol.io/docs/
A2A protocol
a2a-protocol.org
WebFetch on https://a2a-protocol.org/latest/specification/
CopilotKit (AG-UI React client)
docs.copilotkit.ai
WebFetch on https://docs.copilotkit.ai/
Firebase (Auth, Firestore)
firebase.google.com
WebFetch on https://firebase.google.com/docs/ or mcp__google-dev-knowledge__search_documents
OpenTelemetry
opentelemetry.io
WebFetch on https://opentelemetry.io/docs/
Langfuse (observability)
langfuse.com
WebFetch on https://langfuse.com/docs
AILANG Parse
PyPI
WebFetch on https://pypi.org/project/ailang-parse/
Google Cloud (Cloud Run, GCS, etc.)
Google Dev Knowledge MCP
mcp__google-dev-knowledge__search_documents
NPM packages
npm registry
WebFetch on https://www.npmjs.com/package/<pkg> (verify package exists)
Python packages
PyPI
WebFetch on https://pypi.org/project/<pkg>/ (verify version)
Verification checklist for code examples in design docs:
Every class/function name verified against current source (not recalled from memory)
Import paths checked (e.g., google.adk.agents.Agent not google.adk.Agent)
Constructor/method signatures match current API version
Callback signatures verified (ADK changes these between versions)
Package versions in pyproject.toml / package.json confirmed to exist
If an API is experimental/unstable, note the minimum version required
Common pitfalls to avoid:
ADK API changes rapidly — FunctionTool, callback signatures, Runner API, and SessionService all differ between versions. Always verify via mcp__adk-mcp__search_code.
NPM package names for A2UI, AG-UI, MCP Apps may not exist yet or may use different names than expected. Verify on npm before including in design docs.
ADK SkillToolset is experimental (v1.25.0+) — note version requirements.
6. Update SEQUENCE.md
After writing the doc, add it to the version's SEQUENCE.md ordering table. Every design doc must have an entry — this is how the build order stays coherent.
Find the right version's docs/design/v<version>/SEQUENCE.md
Add a row to the Ordering table: order number, doc link, priority, estimate, dependencies, notes
Add a row to the Timeline estimate table
Add a line to What ships in vX.Y.Z
Update the Dependency Graph if the doc has non-trivial dependencies
If the doc is already done (moved to implemented/), mark it ✅ in the timeline row
Finds the doc under docs/design/<version>/<name>.md
Moves it (with git mv when tracked) to docs/design/<version>/implemented/<name>.md
Moves the companion <name>-sprint.md too if present
Flips **Status**: Planned|Proposed → Implemented in the moved file
Refreshes **Last Updated** to today
Appends an Implementation Report stub to the design doc (sprint plans skipped)
Naming Conventions
Use lowercase with hyphens: feature-name.md
For milestone features: m-XXX-feature-name.md
Be specific: slack-channel-integration.md not integration.md
Design Doc Locations
docs/design/
planned/ # Active design docs being worked on
v6.0.0/ # Organized by version (MAJOR.MINOR.PATCH)
v6.1.0/
implemented/ # Completed features
v5.0.0/
v6.0.0/
Versioning
Design docs are organized by product version, not by date:
MAJOR (6.x.x): Breaking changes, major architecture shifts
MINOR (6.1.x): New features, significant enhancements
PATCH (6.0.1): Bug fixes, small improvements
Ask the user which version the feature targets if not obvious. Current version: v6.0.0.
Notes
All design docs follow the template in templates/design-doc.md
Keep design docs focused - split large features into multiple docs
Update the design doc as reality diverges from plan
Link design docs from sprint plans when they exist
