| name | ~aod-kickstart |
| description | POC kickstart skill that transforms a project idea into a sequenced consumer guide with 6-10 seed features. Use when a developer invokes /aod.kickstart to generate a consumer guide, when starting a new project and needing a structured backlog plan, or when converting a project idea into seed features for the AOD lifecycle. Three-stage workflow: Idea Intake, Stack Selection, Guide Generation. |
/aod.kickstart Skill
Purpose
Transform a project idea into a sequenced consumer guide with 6-10 seed features ready for the AOD lifecycle. The skill runs three stages:
- Idea Intake -- Capture the project idea, target user, and key capabilities through structured prompts
- Stack Selection -- Detect an active stack pack or guide the developer to select/describe a stack
- Guide Generation -- Produce a consumer guide at
docs/guides/CONSUMER_GUIDE_{PROJECT_NAME}.md with setup phases, a feature summary table, and per-feature seed blocks ordered for incremental value delivery
Each seed feature block is structured for direct copy-paste into /aod.discover.
Prerequisites Check
Before starting, validate the output directory exists.
- Use Glob to check for
docs/guides/ directory
- If
docs/guides/ does not exist, display the following error and stop:
ERROR: docs/guides/ directory not found.
Run `make init` to set up project structure.
Do not proceed to Stage 1 until docs/guides/ is confirmed to exist.
Stage 1: Idea Intake
Capture the project idea through 5 structured prompts. Store responses in variables for use in later stages.
Step 1.1: Capture Idea Description
Use AskUserQuestion:
Question: "Describe your project idea (what are you building and why?)"
Store the response as {idea_description}.
Vagueness validation (FR-014): Count the words in the response. If fewer than 20 words, ask for elaboration:
Question: "Your idea description is brief. Add more detail about what the project does, the problem it solves, or key workflows (aim for 2-3 sentences)."
Allow up to 2 rounds of clarification. If still under 20 words after 2 rounds, accept the response as-is and proceed with a note:
Note: Idea description is brief. The generated guide may need refinement.
Step 1.2: Capture Target User
Use AskUserQuestion:
Question: "Who is the target user for this project?"
Store the response as {target_user}.
Expected responses: persona descriptions such as "solo developer," "small team lead," "project manager," "end consumer."
Step 1.3: Capture Key Capabilities
Use AskUserQuestion:
Question: "List 3-5 key capabilities this project needs (one per line)"
Store the response as {capabilities}.
Scope check (FR-015): Count the listed capabilities.
- If more than 5 capabilities, display:
You listed {count} capabilities. For a POC, recommend narrowing to 3-5 core capabilities. Which ones are essential for the first version?
Then re-prompt with AskUserQuestion to capture the narrowed list. Accept the revised list.
- If fewer than 3 capabilities, display:
A POC typically needs at least 3 capabilities to demonstrate value. Can you add more?
Then re-prompt with AskUserQuestion to capture additional capabilities.
Step 1.4: Capture GitHub Org
Use AskUserQuestion:
Question: "What is your GitHub org or username? (used for repo creation in the guide)"
Store the response as {github_org}.
Step 1.5: Confirm Summary
Display the captured information:
PROJECT IDEA SUMMARY
Idea: {idea_description}
Target User: {target_user}
GitHub Org: {github_org}
Key Capabilities:
1. {capability_1}
2. {capability_2}
3. {capability_3}
...
Use AskUserQuestion:
Question: "Does this look right?"
Options:
- Yes: "Proceed to stack selection"
- Edit idea: "Change the project idea description"
- Edit user: "Change the target user"
- Edit org: "Change the GitHub org"
- Edit capabilities: "Change the key capabilities"
- If "Yes": proceed to Stage 2
- If "Edit idea": return to Step 1.1
- If "Edit user": return to Step 1.2
- If "Edit org": return to Step 1.4
- If "Edit capabilities": return to Step 1.3
Stage 2: Stack Selection
Determine the technology stack for guide generation. Four paths based on current state and developer preference.
Step 2.1: Check for Active Pack
Read .aod/stack-active.json using the Read tool.
- If file exists and contains valid JSON with a
pack field: extract {pack_name} and proceed to Step 2.2 (Path A)
- If file does not exist, is empty, or has invalid JSON: proceed to Step 2.3 (Path B — no active pack)
Step 2.2: Active Pack Detected (Path A)
- Read
stacks/{pack_name}/STACK.md (first 20 lines)
- Extract the
**Stack**: line value as {stack_description}
- Display:
Active pack detected: {pack_name} ({stack_description})
- Use AskUserQuestion:
Question: "Use this pack for guide generation?"
Options:
- Yes: "Use {pack_name}"
- Change: "Select a different pack or describe a custom stack"
- If "Yes": store
{selected_pack} = {pack_name}, proceed to Stage 3
- If "Change": proceed to Step 2.3 (Path B)
Step 2.3: No Active Pack — Enumerate Available Packs (Path B)
- Glob
stacks/*/STACK.md. If none found: skip to Path C (custom stack)
- For each STACK.md, read first 20 lines and extract pack name (directory name),
**Stack**: value, **Use Case**: value
- Display numbered list:
{N}. {pack_name} — {stack_value} with Use case: {use_case} on next line
- AskUserQuestion: "Select a stack pack for guide generation" with options: one per discovered pack + "Help me choose" (→ Step 2.4 Path D) + "Custom stack" (→ Step 2.5 Path C)
- If pack selected: store
{selected_pack}, proceed to Stage 3
Step 2.4: Guided Selection Questions (Path D)
Ask 4 questions via AskUserQuestion to recommend the best-fit pack from those discovered in Step 2.3:
- "What type of project?" → Options: Web app | Mobile app | CLI tool | API service | Knowledge system → store
{project_type}
- "Where will this be deployed?" → Options: Local development | Cloud (AWS/GCP/Azure) | Serverless | App Store → store
{deployment_target}
- "Primary programming language?" → Options: Python | TypeScript | Swift | Rust | Other → store
{primary_language}
- "Database preference?" → Options: SQL (PostgreSQL, SQLite) | NoSQL (MongoDB, DynamoDB) | Managed (Supabase, Firebase) | None → store
{db_preference}
Recommendation: Match answers against pack metadata (**Stack**: for language, **Deployment**: for target, **Use Case**: for project type). Display:
Recommended: {best_fit_pack} ({stack_description})
Rationale: {1-2 sentences}
Alternatives: {alt_pack_1} — {reason}, {alt_pack_2} — {reason}
AskUserQuestion: "Use the recommended pack?" with options: "Yes" (use recommendation) | each alternative pack | "Custom stack" (→ Step 2.5 Path C). Store {selected_pack}, proceed to Stage 3.
Step 2.5: Custom Stack Capture (Path C)
When the developer selects "Custom stack" from Path B or Path D, capture their technology stack.
Use AskUserQuestion:
Question: "Describe your technology stack (languages, frameworks, database, deployment target)"
Store the response as {custom_stack_description}. Set {selected_pack} to empty (no pack selected). Proceed to Stage 3.
Stage 3: Guide Generation
Generate the consumer guide document. This stage is autonomous — no user interaction except conflict detection.
Step 3.1: Load Pack Conventions
If {selected_pack} is set (pack-based generation):
- Read
stacks/{selected_pack}/STACK.md in full
- Extract these fields from the file:
**Stack**: → {stack_tech} (e.g., "Python 3.12, FastAPI, React 18, SQLite")
**Use Case**: → {use_case}
**Target**: → {pack_target}
**Deployment**: → {deployment}
## Architecture Pattern section → {architecture_notes} (key conventions)
- Store all extracted fields for use in guide content
If no pack selected (custom stack path):
Use the {custom_stack_description} captured in Stage 2 Path C as the stack context. Set {stack_tech} to the developer's described technologies.
Step 3.2: Derive Project Name
From {idea_description}, derive a short project name:
- Extract the core noun phrase (e.g., "a task management API" → "Task Manager API")
- Convert to SCREAMING_SNAKE_CASE for the filename:
TASK_MANAGER_API
- Store as
{project_name} (display) and {file_name} (SCREAMING_SNAKE_CASE)
- Output path:
docs/guides/CONSUMER_GUIDE_{file_name}.md
Step 3.3: Generate Guide Content
Using the Guide Template (below), generate the full consumer guide. The content must:
- Header: Use
{idea_description}, {target_user}, and {capabilities} from Stage 1
- Setup phases: Use
{selected_pack} conventions if pack-based, or generic instructions if custom stack
- Requirements: Derive functional requirements from
{capabilities}
- Feature summary table: List all seed features with IDs, groups, story counts, and dependency annotations
- Seed feature blocks: Generate 6-10 features following the Ordering Principles (below), each with goal, stories, interface contracts, and DoD
- Execution guide: Standard AOD lifecycle instructions
- Quick Start Commands: Pre-formatted
/aod.discover --seed read #### F-NNN: {name} in {guide_path} commands for every feature, enabling one-command-per-feature GitHub Issue creation
- Completion tracker: Checkbox table for all features
Custom stack generation: When {selected_pack} is empty (custom stack), use {custom_stack_description} for all stack-dependent content. Seed features must be technology-appropriate — e.g., a Django + HTMX project should reference Django views, HTMX partials, and Django ORM patterns, not generic REST boilerplate. Infer architecture patterns from the described technologies.
Step 3.4: Conflict Detection (FR-012)
Before writing, check for an existing guide at the target path.
- Glob
docs/guides/CONSUMER_GUIDE_*.md
- If a file matching
docs/guides/CONSUMER_GUIDE_{file_name}.md exists, display:
Existing guide found: docs/guides/CONSUMER_GUIDE_{file_name}.md
- Use AskUserQuestion:
Question: "A consumer guide already exists at this path. What would you like to do?"
Options:
- Overwrite: "Replace the existing guide"
- Rename: "Save as a date-suffixed alternative (CONSUMER_GUIDE_{file_name}_{YYYY-MM-DD}.md)"
- Cancel: "Cancel guide generation"
- If "Overwrite": proceed to Step 3.5 with the original path
docs/guides/CONSUMER_GUIDE_{file_name}.md
- If "Rename": update output path to
docs/guides/CONSUMER_GUIDE_{file_name}_{YYYY-MM-DD}.md (using today's date), proceed to Step 3.5
- If "Cancel": display "Kickstart cancelled. No files were written." and stop execution
- If no matching file exists: proceed to Step 3.5 with the original path
Step 3.5: Write Guide File
- Use the Write tool to create the guide at the determined output path
- Display completion summary:
Guide written to docs/guides/CONSUMER_GUIDE_{file_name}.md
- {feature_count} seed features across {group_count} groups
- {line_count} lines
- Quick Start Commands included for one-command seeding
- Ready for /aod.discover intake
Next steps:
Use the Quick Start Commands section to seed all features into GitHub Issues.
Copy-paste each command into Claude Code — one per feature, in dependency order.
Then run the AOD lifecycle for each: /aod.define → /aod.deliver
Guide Template
At the start of Step 3.3, use the Read tool to load KICKSTART_TEMPLATE.md (co-located with this SKILL.md in .claude/skills/~aod-kickstart/). This template defines the exact structure, section ordering, and formatting for all generated consumer guides — including setup phases, feature blocks, and tail sections. Follow it section by section, replacing all {placeholders} with actual content derived from Stages 1-2.
Derive {project_slug} from {project_name} (lowercase, kebab-case). Use {github_org} from Step 1.4.
Ordering Principles
Order seed features according to these tiers (FR-009). Every generated guide must follow this sequence.
| Tier | Position | Examples |
|---|
| Foundation | First | Project skeleton, health check, data models, config, environment setup |
| Core Value | Second | Primary CRUD/workflow, business logic, core API endpoints or CLI commands |
| User-Facing | Third | Dashboard/UI views, interactions, forms, notifications, auth |
| Polish | Last | Error handling, external integrations, performance, monitoring |
Ordering Rules
- Each feature must be independently demonstrable — a developer can verify it works after completion
- Each feature only depends on earlier features — never on a later feature in the sequence
- No circular dependencies — validate the dependency graph is a DAG before writing
- Group related features — use Group headings (Foundation, Core, User-Facing, Polish)
- Dependency chain in summary table —
Depends On column must reflect the actual dependency graph
Edge Cases
- No
stacks/ directory: Skip pack recommendation entirely. Proceed directly to custom stack path (Path C)
- Empty
stacks/ directory (no STACK.md files found): Same as above — proceed to custom stack path
- Invalid
.aod/stack-active.json (malformed JSON or missing pack field): Treat as no active pack — proceed to Path B
- Pack in
stack-active.json not found on disk: Display warning "Pack '{pack_name}' is configured but not found in stacks/. Proceeding without pack." then proceed to Path B
- Vague idea after 2 clarification rounds: Accept the response as-is. Display note: "Idea description is brief. The generated guide may need refinement." Generate best-effort guide
- User aborts at any stage: Exit gracefully. Do not write any files. Display "Kickstart cancelled. No files were written."
- Generated feature count outside 6-10 range: Adjust by merging small features (if > 10) or expanding scope (if < 6) to stay within the required range
- Dependency cycle detected: Reorder features to eliminate the cycle before writing the guide. Foundation features must have no upstream dependencies
Constraints
- Read-only enforcement (FR-016): This skill MUST NOT modify any files outside of
docs/guides/. The following directories are read-only: .aod/, .claude/, stacks/. Only the Write tool targeting docs/guides/CONSUMER_GUIDE_*.md is permitted
- No pack state modification (FR-017): This skill MUST NOT activate, deactivate, or modify stack pack state. Stack activation is handled separately via
/aod.stack use. Never write to .aod/stack-active.json
- Feature count (FR-010): Generate exactly 6-10 seed features. Fewer than 6 does not demonstrate enough scope; more than 10 overwhelms a POC
- Guide line budget (SC-007): Generated guides must be 200-600 lines. Enough detail to be actionable, not so much that it overwhelms
- Discover compatibility (FR-013, SC-004): Each seed feature block (from
#### F-NNN: to ---) must be directly copy-pasteable into /aod.discover as the idea description. The block must contain goal, stories with acceptance criteria, interface contracts, and DoD in the exact format shown in KICKSTART_TEMPLATE.md
- Skill file budget (SC-008): This SKILL.md file must remain under 500 lines
- No GitHub Issues (NFR-5): This skill is idempotent — it only produces a guide document. It does not create GitHub Issues, modify backlog state, or trigger any side effects beyond writing the guide file