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

~aod-blueprint

Skill95 starsChanged 38 days agoApache-2.0View on GitHub

Unified project setup and story generation skill that auto-detects new vs existing projects. Three modes: first-run (creates repo, registers project, activates), subsequent-run (skips setup, adds new stories with deduplication), and demo (loads pre-built Hello World stories). Generates ICE-scored, dependency-ordered stories as GitHub Issues and outputs a consumer guide. Use when a developer invokes /aod.blueprint to bootstrap or extend a project.

  • Sends data out

The file

Show its rules and text

We split this skill into the rules it gives an agent

41 rules. About 0 are common, 22 are distinctive, and 19 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈22

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 19

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    All modes end with issue creation, lifecycle sync, consumer guide generation, and a completion report.

    line 22
  2. Very specific:

    Run gh --version via Bash tool.

    line 32
  3. Distinctive:

    If the command succeeds, continue to Step 0.2.

    line 34
  4. Distinctive:

    If the command fails, display the following error and STOP:

    line 35
  5. Distinctive:

    Run the following command via Bash tool:

    line 44
  6. Distinctive:

    If the command succeeds (exit code 0), display "Prerequisites OK" and continue to Step 1.

    line 50
  7. Very specific:

    If the command succeeds, extract the repo name from the URL: take the last path segment and strip any .git suffix.

    line 68
  8. Very specific:

    If the command fails (no remote configured), run basename $(pwd) via Bash tool and store the result as {project_name}.

    line 69
  9. Very specific:

    Check $ARGUMENTS for the --demo flag.

    line 92
  10. Very specific:

    If $ARGUMENTS contains --demo → set demo = true

    line 94
  11. Distinctive:

    Create the GitHub repo (if needed), register the project with the orchestrator API, and activate it.

    line 115
  12. Very specific:

    If exit code is 0 (repo exists): skip repo creation.

    line 125
  13. Distinctive:

    If exit code is non-zero (no repo): continue to Step 2.2.

    line 126
  14. Distinctive:

    If no remote is available, use AskUserQuestion to ask: "What is your GitHub org or username?

    line 132
  15. Distinctive:

    Use AskUserQuestion to capture the project idea:

    line 179
  16. Distinctive:

    If more than 5: "You listed {count} capabilities.

    line 212
  17. Distinctive:

    If fewer than 3: "A blueprint typically needs at least 3 capabilities to generate meaningful stories.

    line 213
  18. Distinctive:

    Use AskUserQuestion: "Does this look right?" with options:

    line 230
  19. Distinctive:

    If "Yes": proceed to Step 3.5.

    line 236
  20. Very specific:

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

    line 240
  21. Very specific:

    If "Yes": store {selected_pack} = {pack_name}, proceed to Step 3.6

    line 246
  22. Distinctive:

    If "Help me choose": ask 4 guided questions (project type, deployment, language, database), recommend best-fit pack

    line 250
  23. Very specific:

    If "Custom stack" or no packs exist: AskUserQuestion "Describe your technology stack (languages, frameworks, database, deployment target)".

    line 251
  24. Very specific:

    If {selected_pack} is set: Read stacks/{selected_pack}/STACK.md for full stack context.

    line 255
  25. Very specific:

    If custom stack: Use {custom_stack_description} as stack context.

    line 256
  26. Very specific:

    When demo = true, skip all interactive intake.

    line 273
  27. Very specific:

    Read docs/guides/HELLO_WORLD_STORIES.md via Read tool.

    line 275
  28. Distinctive:

    If file is missing, display error and STOP:

    line 276
  29. Distinctive:

    Run via Bash tool:

    line 299
  30. Distinctive:

    If no match: Create the issue via Bash tool:

    line 313
  31. Very specific:

    After each creation, run sleep 1 (rate limit protection per FR-010)

    line 321
  32. Distinctive:

    After all stories are processed, display:

    line 326
  33. Distinctive:

    After all issues are created, sync with the orchestrator lifecycle engine.

    line 338
  34. Distinctive:

    Run via Bash tool (non-blocking per KB #14):

    line 340
  35. Distinctive:

    If the command succeeds: Display "Issues synced with orchestrator"

    line 347
  36. Very specific:

    If the command fails (caught by || true): Display "Warning: Issue sync failed.

    line 348
  37. Very specific:

    Read BLUEPRINT_TEMPLATE.md (co-located with this SKILL.md in .claude/skills/~aod-blueprint/) via the Read tool.

    line 356
  38. Very specific:

    Write the generated guide to docs/guides/BLUEPRINT_{PROJECT}.md via Write tool.

    line 373
  39. Very specific:

    If write succeeds: Display "Consumer guide written to docs/guides/BLUEPRINT_{PROJECT}.md"

    line 375
  40. Distinctive:

    If write fails: Display "Warning: Guide generation failed.

    line 376
  41. Very specific:

    Issue creation script: All GitHub Issue creation must use .aod/scripts/bash/create-issue.sh (KB #20), not raw gh issue create.

    line 416

≈ “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.blueprint Skill

Purpose

Unified project setup and story generation in a single command. The skill auto-detects whether the current project is new or existing, then runs the appropriate workflow:

  1. First-Run -- Creates GitHub repo, registers project with orchestrator API, activates it, runs interactive intake, generates stories, creates issues
  2. Subsequent-Run -- Skips setup, runs interactive intake, generates new stories with deduplication against existing issues
  3. Demo Mode (--demo) -- Loads pre-built Hello World stories from HELLO_WORLD_STORIES.md, skips interactive intake entirely

All modes end with issue creation, lifecycle sync, consumer guide generation, and a completion report.


Step 0: Prerequisites Check

Validate that required tools and services are available before proceeding.

0.1: Check gh CLI

Run gh --version via Bash tool.

  • If the command succeeds, continue to Step 0.2.
  • If the command fails, display the following error and STOP:
ERROR: GitHub CLI (gh) is not installed or not in PATH.
Install it from https://cli.github.com/ and run `gh auth login` to authenticate.

0.2: Check API Health

Run the following command via Bash tool:

curl -sf ${AOD_API_URL:-http://localhost:8000}/health -H "X-AOD-Source: skill"
  • If the command succeeds (exit code 0), display "Prerequisites OK" and continue to Step 1.
  • If the command fails, display the following error and STOP:
ERROR: AOD Orchestrator API is not reachable at ${AOD_API_URL:-http://localhost:8000}.
Start the API with `make run` and try again.

Step 1: Auto-Detection

Determine the project name, check for an existing project in the orchestrator, and set the execution mode.

1.1: Derive Project Name

Run git remote get-url origin via Bash tool.

  • If the command succeeds, extract the repo name from the URL: take the last path segment and strip any .git suffix. For example, https://github.com/org/my-project.git yields my-project. Store as {project_name}.
  • If the command fails (no remote configured), run basename $(pwd) via Bash tool and store the result as {project_name}.

1.2: Check for Existing Project

Run the following command via Bash tool:

curl -sf ${AOD_API_URL:-http://localhost:8000}/api/v1/projects -H "X-AOD-Source: skill"

Parse the JSON response. Filter for a project where:

  • The name field matches {project_name} (case-insensitive comparison), OR
  • The repo_url field contains {project_name}

1.3: Set Mode

Based on the result of Step 1.2:

  • If no matching project found → set mode = first-run
  • If a matching project found → set mode = subsequent-run, store the matched project's id as {project_id}

1.4: Parse Demo Flag

Check $ARGUMENTS for the --demo flag.

  • If $ARGUMENTS contains --demo → set demo = true
  • Otherwise → set demo = false

1.5: Display Detection Result

Display the detected configuration:

Mode: {first-run|subsequent-run}
Demo: {yes|no}
Project: {project_name}

Continue to Step 2.


Step 2: First-Run Setup

If mode = subsequent-run: Skip this step entirely. The {project_id} was stored in Step 1.3. Continue to Step 3.

Create the GitHub repo (if needed), register the project with the orchestrator API, and activate it.

2.1: Check for Existing GitHub Repo

Run the following command via Bash tool:

gh repo view {project_name} 2>/dev/null
  • If exit code is 0 (repo exists): skip repo creation. Extract the repo URL from the output and store as {repo_url}. Continue to Step 2.3.
  • If exit code is non-zero (no repo): continue to Step 2.2.

2.2: Create GitHub Repo

Derive the GitHub org from the git remote. Run git remote get-url origin via Bash tool and extract the org/owner segment from the URL. For example, https://github.com/my-org/some-repo.git yields my-org.

  • If no remote is available, use AskUserQuestion to ask: "What is your GitHub org or username? (used for repo creation)"
  • Store the result as {github_org}.

Run the following command via Bash tool:

gh repo create {github_org}/{project_name} --public

Store the created repo URL as {repo_url}.

2.3: Register Project

Run the following command via Bash tool:

curl -sf -X POST ${AOD_API_URL:-http://localhost:8000}/api/v1/projects \
  -H "Content-Type: application/json" \
  -H "X-AOD-Source: skill" \
  -d '{"name":"{project_name}","repo_url":"{repo_url}","github_owner":"{github_org}","github_repo":"{project_name}","worktree_root":"{pwd}","aod_kit_path":"{pwd}"}'

Parse the JSON response and extract the id field. Store as {project_id}.

2.4: Activate Project

Run the following command via Bash tool:

curl -sf -X PATCH ${AOD_API_URL:-http://localhost:8000}/api/v1/projects/{project_id}/activate \
  -H "X-AOD-Source: skill"

2.5: Confirm Setup

Display: "Project '{project_name}' registered and activated (ID: {project_id})"

Continue to Step 3.


Step 3: Story Generation

If demo = true: Skip to Step 3D (Demo Mode) below.

3.1: Capture Idea (Stage 1)

Use AskUserQuestion to capture the project idea:

Question: "Describe your project idea (what are you building and why?)"

Store as {idea_description}. Count words — if fewer than 20, 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 clarification rounds. If still under 20 words after 2 rounds, accept as-is with note: "Note: Idea description is brief. Generated stories may need refinement."

3.2: Capture Target User

Use AskUserQuestion:

Question: "Who is the target user for this project?"

Store as {target_user}.

3.3: Capture Key Capabilities

Use AskUserQuestion:

Question: "List 3-5 key capabilities this project needs (one per line)"

Store as {capabilities}. Count the listed items:

  • If more than 5: "You listed {count} capabilities. For a blueprint, recommend narrowing to 3-5 core capabilities. Which ones are essential?" Re-prompt once.
  • If fewer than 3: "A blueprint typically needs at least 3 capabilities to generate meaningful stories. Can you add more?" Re-prompt once.

3.4: Confirm Summary

Display the captured information:

BLUEPRINT INTAKE SUMMARY

Idea: {idea_description}
Target User: {target_user}
Key Capabilities:
  1. {capability_1}
  2. {capability_2}
  ...

Use AskUserQuestion: "Does this look right?" with options:

  • "Yes, proceed to stack selection"
  • "Edit idea"
  • "Edit target user"
  • "Edit capabilities"

If "Yes": proceed to Step 3.5. Otherwise loop back to the relevant step.

3.5: Stack Selection (Stage 2)

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

If file exists with valid JSON and a pack field:

  1. Extract {pack_name}, read stacks/{pack_name}/STACK.md (first 20 lines) for {stack_description}
  2. Display: "Active pack detected: {pack_name} ({stack_description})"
  3. AskUserQuestion: "Use this pack for story generation?" — "Yes" or "Select different stack"
  4. If "Yes": store {selected_pack} = {pack_name}, proceed to Step 3.6

If no active pack or user wants different:

  1. Glob stacks/*/STACK.md. If packs found, display numbered list and ask user to select, with options for "Help me choose" and "Custom stack"
  2. If "Help me choose": ask 4 guided questions (project type, deployment, language, database), recommend best-fit pack
  3. If "Custom stack" or no packs exist: AskUserQuestion "Describe your technology stack (languages, frameworks, database, deployment target)". Store as {custom_stack_description}, set {selected_pack} to empty

3.6: Generate Stories (Stage 3)

If {selected_pack} is set: Read stacks/{selected_pack}/STACK.md for full stack context. If custom stack: Use {custom_stack_description} as stack context.

Generate 6-10 stories from the captured idea, capabilities, and stack. Each story must include:

  • Title: Short descriptive name
  • Description: 1-2 sentence summary
  • User Story: As a {target_user}, I want {capability}, so that {benefit}
  • ICE Score: Impact (1-10), Confidence (1-10), Effort (1-10)
  • DoD Checklist: 3-5 concrete acceptance criteria

Order by dependency tier: Foundation → Core → User-Facing → Polish.

Display all stories to the user for confirmation before proceeding. Use AskUserQuestion: "Confirm these stories?" — "Yes, create issues" or "Regenerate stories". If regenerate, re-run generation with user feedback.

Store confirmed stories as {stories} list. Continue to Step 4.

Step 3D: Demo Mode

When demo = true, skip all interactive intake.

  1. Read docs/guides/HELLO_WORLD_STORIES.md via Read tool.
    • If file is missing, display error and STOP:
      ERROR: Demo stories file not found at docs/guides/HELLO_WORLD_STORIES.md.
      Run without --demo for interactive mode.
  2. Parse stories by ## Story N: headings. For each story, extract:
    • Title from **Title**: line (strip backticks)
    • User story from **As a ...** line
    • Acceptance criteria from ### Acceptance Criteria section
    • Technical notes from ### Technical Notes section
  3. Convert to internal story format with pre-set ICE scores: Impact 8, Confidence 9, Effort 7 for all demo stories. Derive DoD from acceptance criteria.
  4. Set {idea_description} = "Hello World Greeting Dashboard", {target_user} = "developer evaluating AOD", {capabilities} from The App section.

Store parsed stories as {stories} list. Continue to Step 4.


Step 4: Issue Creation with Deduplication

Derive {owner} and {repo} from the git remote URL (or from {github_org} and {project_name} used in Step 2).

4.1: Fetch Existing Issues

Run via Bash tool:

gh issue list --repo {owner}/{repo} --limit 200 --json title,number,url

Parse the JSON response into a list of existing issue titles and numbers.

4.2: Create Issues with Dedup

For each story in {stories}, in order:

  1. Compare the story title against existing issue titles (case-insensitive exact match)
  2. If match found: Log "Skipping duplicate: {title} (matches #{number})". Store the matched issue number and URL.
  3. If no match: Create the issue via Bash tool:
bash .aod/scripts/bash/create-issue.sh --title "{story_title}" --body "{formatted_body}" --stage discover

The {formatted_body} must include: user story, ICE score breakdown, DoD checklist, dependency tier, and description.

  1. After each creation, run sleep 1 (rate limit protection per FR-010)
  2. Store the created issue number (from script stdout) and construct the URL as https://github.com/{owner}/{repo}/issues/{number}

4.3: Summary

After all stories are processed, display:

Issues: {created_count} created, {skipped_count} duplicates skipped

Store all issue numbers and URLs (both new and matched) as {issue_results} for Step 6.


Step 5: Lifecycle Sync

After all issues are created, sync with the orchestrator lifecycle engine.

Run via Bash tool (non-blocking per KB #14):

curl -sf -X POST ${AOD_API_URL:-http://localhost:8000}/api/v1/projects/{project_id}/issues/sync \
  -H "X-AOD-Source: skill" || true
  • If the command succeeds: Display "Issues synced with orchestrator"
  • If the command fails (caught by || true): Display "Warning: Issue sync failed. Issues are created but may not appear in orchestrator until next sync." Continue to Step 6 regardless.

Step 6: Consumer Guide Generation

6.1: Load Template

Read BLUEPRINT_TEMPLATE.md (co-located with this SKILL.md in .claude/skills/~aod-blueprint/) via the Read tool.

6.2: Generate Guide Content

Replace all template placeholders with actual values:

  • {project_name}: from Step 1.1
  • {idea_description}, {target_user}, {capabilities_list}: from Step 3 intake (or demo defaults)
  • {stack_description}: from {selected_pack} STACK.md description, or {custom_stack_description} if custom
  • {date}: current date (YYYY-MM-DD)
  • {story_*} fields: from {stories} list
  • {issue_number}, {issue_url}: from {issue_results} (Step 4)
  • Tier groupings for execution order table

Derive {PROJECT} as SCREAMING_SNAKE_CASE from {project_name} (e.g., my-project → MY_PROJECT).

6.3: Write Guide (Non-Blocking)

Write the generated guide to docs/guides/BLUEPRINT_{PROJECT}.md via Write tool. On subsequent runs, overwrite the existing file (full regeneration per FR-016).

  • If write succeeds: Display "Consumer guide written to docs/guides/BLUEPRINT_{PROJECT}.md"
  • If write fails: Display "Warning: Guide generation failed. Issues are created — guide can be regenerated by re-running /aod.blueprint." Continue to Step 7 regardless.

Step 7: Completion Report

Display a summary of everything that was done:

BLUEPRINT COMPLETE

Mode: {first-run|subsequent-run|demo}
Project: {project_name} (ID: {project_id})
Stories: {story_count} generated
Issues: {created_count} created, {skipped_count} duplicates skipped
Guide: docs/guides/BLUEPRINT_{PROJECT}.md

Next step: /aod.run

Edge Cases

  • Orchestrator API unreachable: Fast-fail at Step 0.2 with setup instructions. No partial state created.
  • gh CLI not installed or not authenticated: Fast-fail at Step 0.1. Display install link and gh auth login instructions.
  • Project exists in GitHub but not in orchestrator: First-run mode — skip repo creation (Step 2.1 detects existing repo), proceed with registration.
  • GitHub API rate limiting during issue creation: The 1-second delay between create-issue.sh calls (Step 4.2) provides baseline protection. If create-issue.sh fails, log the error and continue with remaining stories.
  • HELLO_WORLD_STORIES.md missing with --demo: Error with suggestion to run without --demo (Step 3D).
  • worktree_root not a git repo: POST /api/v1/projects returns validation error. Display the error message and STOP.
  • User aborts at any intake step: Exit gracefully. No issues created, no partial state.
  • Generated story count outside 6-10: Adjust during generation — merge small stories if >10, expand scope if <6.

Constraints

  • SKILL.md line budget: This file must stay ≤500 lines (KB #12). Use BLUEPRINT_TEMPLATE.md for guide structure.
  • No kickstart modifications: /aod.kickstart must remain unmodified (FR-018). Blueprint implements patterns independently.
  • ADR-016 headers: All curl calls must include -H "X-AOD-Source: skill".
  • Issue creation script: All GitHub Issue creation must use .aod/scripts/bash/create-issue.sh (KB #20), not raw gh issue create.
  • Bash 3.2 compatibility: Any inline bash scripts must avoid declare -A, ${var^}, readarray, |&, &> (KB #6).
  • Non-fatal pattern: Sync (Step 5) and guide generation (Step 6) must never block the critical workflow. Use || true guards (KB #14).

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.