agentleFS
davidmatousekdavidmatousek/tachi/.claude/skills/~aod-kickstart/SKILL.md

~aod-kickstart

Skill95 starsChanged 37 days agoApache-2.0View on GitHub

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.

The file

Show its rules and text

We split this skill into the rules it gives an agent

29 rules. About 0 are common, 15 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈15

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before starting, validate the output directory exists.

    line 27
  2. Very specific:

    Use Glob to check for docs/guides/ directory

    line 29
  3. Very specific:

    If docs/guides/ does not exist, display the following error and stop:

    line 30
  4. Very specific:

    Do not proceed to Stage 1 until docs/guides/ is confirmed to exist.

    line 37
  5. Distinctive:

    If more than 5 capabilities, display:

    line 91
  6. Distinctive:

    If fewer than 3 capabilities, display:

    line 99
  7. Distinctive:

    If "Yes": proceed to Stage 2

    line 146
  8. Distinctive:

    If "Edit idea": return to Step 1.1

    line 147
  9. Distinctive:

    If "Edit user": return to Step 1.2

    line 148
  10. Distinctive:

    If "Edit org": return to Step 1.4

    line 149
  11. Distinctive:

    If "Edit capabilities": return to Step 1.3

    line 150
  12. Very specific:

    Read .aod/stack-active.json using the Read tool.

    line 160
  13. Very specific:

    Read stacks/{pack_name}/STACK.md (first 20 lines)

    line 167
  14. Very specific:

    If "Yes": store {selected_pack} = {pack_name}, proceed to Stage 3

    line 184
  15. Distinctive:

    If "Change": proceed to Step 2.3 (Path B)

    line 185
  16. Very specific:

    If pack selected: store {selected_pack}, proceed to Stage 3

    line 193
  17. Distinctive:

    Ask 4 questions via AskUserQuestion to recommend the best-fit pack from those discovered in Step 2.3:

    line 197
  18. Distinctive:

    When the developer selects "Custom stack" from Path B or Path D, capture their technology stack.

    line 216
  19. Very specific:

    Read stacks/{selected_pack}/STACK.md in full

    line 236
  20. Very specific:

    Use the {custom_stack_description} captured in Stage 2 Path C as the stack context.

    line 247
  21. Very specific:

    Header: Use {idea_description}, {target_user}, and {capabilities} from Stage 1

    line 262
  22. Very specific:

    Setup phases: Use {selected_pack} conventions if pack-based, or generic instructions if custom stack

    line 263
  23. Distinctive:

    Before writing, check for an existing guide at the target path.

    line 275
  24. Very specific:

    If a file matching docs/guides/CONSUMER_GUIDE_{file_name}.md exists, display:

    line 278
  25. Very specific:

    If "Overwrite": proceed to Step 3.5 with the original path docs/guides/CONSUMER_GUIDE_{file_name}.md

    line 294
  26. Very specific:

    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

    line 295
  27. Distinctive:

    If "Cancel": display "Kickstart cancelled.

    line 296
  28. Distinctive:

    If no matching file exists: proceed to Step 3.5 with the original path

    line 298
  29. Distinctive:

    Use the Write tool to create the guide at the determined output path

    line 302

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/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:

  1. Idea Intake -- Capture the project idea, target user, and key capabilities through structured prompts
  2. Stack Selection -- Detect an active stack pack or guide the developer to select/describe a stack
  3. 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.

  1. Use Glob to check for docs/guides/ directory
  2. 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)

  1. Read stacks/{pack_name}/STACK.md (first 20 lines)
  2. Extract the **Stack**: line value as {stack_description}
  3. Display:
Active pack detected: {pack_name} ({stack_description})
  1. 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)

  1. Glob stacks/*/STACK.md. If none found: skip to Path C (custom stack)
  2. For each STACK.md, read first 20 lines and extract pack name (directory name), **Stack**: value, **Use Case**: value
  3. Display numbered list: {N}. {pack_name} — {stack_value} with Use case: {use_case} on next line
  4. 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)
  5. 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:

  1. "What type of project?" → Options: Web app | Mobile app | CLI tool | API service | Knowledge system → store {project_type}
  2. "Where will this be deployed?" → Options: Local development | Cloud (AWS/GCP/Azure) | Serverless | App Store → store {deployment_target}
  3. "Primary programming language?" → Options: Python | TypeScript | Swift | Rust | Other → store {primary_language}
  4. "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):

  1. Read stacks/{selected_pack}/STACK.md in full
  2. 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)
  3. 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:

  1. Extract the core noun phrase (e.g., "a task management API" → "Task Manager API")
  2. Convert to SCREAMING_SNAKE_CASE for the filename: TASK_MANAGER_API
  3. Store as {project_name} (display) and {file_name} (SCREAMING_SNAKE_CASE)
  4. 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:

  1. Header: Use {idea_description}, {target_user}, and {capabilities} from Stage 1
  2. Setup phases: Use {selected_pack} conventions if pack-based, or generic instructions if custom stack
  3. Requirements: Derive functional requirements from {capabilities}
  4. Feature summary table: List all seed features with IDs, groups, story counts, and dependency annotations
  5. Seed feature blocks: Generate 6-10 features following the Ordering Principles (below), each with goal, stories, interface contracts, and DoD
  6. Execution guide: Standard AOD lifecycle instructions
  7. 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
  8. 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.

  1. Glob docs/guides/CONSUMER_GUIDE_*.md
  2. If a file matching docs/guides/CONSUMER_GUIDE_{file_name}.md exists, display:
Existing guide found: docs/guides/CONSUMER_GUIDE_{file_name}.md
  1. 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
  1. If no matching file exists: proceed to Step 3.5 with the original path

Step 3.5: Write Guide File

  1. Use the Write tool to create the guide at the determined output path
  2. 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.

TierPositionExamples
FoundationFirstProject skeleton, health check, data models, config, environment setup
Core ValueSecondPrimary CRUD/workflow, business logic, core API endpoints or CLI commands
User-FacingThirdDashboard/UI views, interactions, forms, notifications, auth
PolishLastError handling, external integrations, performance, monitoring

Ordering Rules

  1. Each feature must be independently demonstrable — a developer can verify it works after completion
  2. Each feature only depends on earlier features — never on a later feature in the sequence
  3. No circular dependencies — validate the dependency graph is a DAG before writing
  4. Group related features — use Group headings (Foundation, Core, User-Facing, Polish)
  5. 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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.