~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
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ~aod-bugfixSkill
- ~aod-buildSkill
- ~aod-defineSkill
- ~aod-deliverSkill
- ~aod-discoverSkill
- aod-foundationSkill
- ~aod-kickstartSkill
- aod-lensSkill
- aod-orchestrateSkill
- ~aod-planSkill
- ~aod-project-planSkill
- ~aod-runSkill
- ~aod-scoreSkill
- ~aod-specSkill
- aod-stackSkill
- ~aod-statusSkill
- code-execution-helperSkill
- git-workflow-helperSkill
- kb-createSkill
- kb-querySkill
- root-cause-analyzerSkill
- securitySkill
- tachi-control-analysisSkill
- tachi-infographicsSkill
- tachi-orchestrationSkill
- tachi-report-assemblySkill
- tachi-risk-scoringSkill
- tachi-sharedSkill
- tachi-threat-reportingSkill
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
- Distinctive: line 22
All modes end with issue creation, lifecycle sync, consumer guide generation, and a completion report.
- Very specific: line 32
Run gh --version via Bash tool.
- Distinctive: line 34
If the command succeeds, continue to Step 0.2.
- Distinctive: line 35
If the command fails, display the following error and STOP:
- Distinctive: line 44
Run the following command via Bash tool:
- Distinctive: line 50
If the command succeeds (exit code 0), display "Prerequisites OK" and continue to Step 1.
- Very specific: line 68
If the command succeeds, extract the repo name from the URL: take the last path segment and strip any .git suffix.
- Very specific: line 69
If the command fails (no remote configured), run basename $(pwd) via Bash tool and store the result as {project_name}.
- Very specific: line 92
Check $ARGUMENTS for the --demo flag.
- Very specific: line 94
If $ARGUMENTS contains --demo → set demo = true
- Distinctive: line 115
Create the GitHub repo (if needed), register the project with the orchestrator API, and activate it.
- Very specific: line 125
If exit code is 0 (repo exists): skip repo creation.
- Distinctive: line 126
If exit code is non-zero (no repo): continue to Step 2.2.
- Distinctive: line 132
If no remote is available, use AskUserQuestion to ask: "What is your GitHub org or username?
- Distinctive: line 179
Use AskUserQuestion to capture the project idea:
- Distinctive: line 212
If more than 5: "You listed {count} capabilities.
- Distinctive: line 213
If fewer than 3: "A blueprint typically needs at least 3 capabilities to generate meaningful stories.
- Distinctive: line 230
Use AskUserQuestion: "Does this look right?" with options:
- Distinctive: line 236
If "Yes": proceed to Step 3.5.
- Very specific: line 240
Read .aod/stack-active.json using the Read tool.
- Very specific: line 246
If "Yes": store {selected_pack} = {pack_name}, proceed to Step 3.6
- Distinctive: line 250
If "Help me choose": ask 4 guided questions (project type, deployment, language, database), recommend best-fit pack
- Very specific: line 251
If "Custom stack" or no packs exist: AskUserQuestion "Describe your technology stack (languages, frameworks, database, deployment target)".
- Very specific: line 255
If
{selected_pack}is set: Read stacks/{selected_pack}/STACK.md for full stack context. - Very specific: line 256
If custom stack: Use {custom_stack_description} as stack context.
- Very specific: line 273
When demo = true, skip all interactive intake.
- Very specific: line 275
Read docs/guides/HELLO_WORLD_STORIES.md via Read tool.
- Distinctive: line 276
If file is missing, display error and STOP:
- Distinctive: line 299
Run via Bash tool:
- Distinctive: line 313
If no match: Create the issue via Bash tool:
- Very specific: line 321
After each creation, run sleep 1 (rate limit protection per FR-010)
- Distinctive: line 326
After all stories are processed, display:
- Distinctive: line 338
After all issues are created, sync with the orchestrator lifecycle engine.
- Distinctive: line 340
Run via Bash tool (non-blocking per KB #14):
- Distinctive: line 347
If the command succeeds: Display "Issues synced with orchestrator"
- Very specific: line 348
If the command fails (caught by || true): Display "Warning: Issue sync failed.
- Very specific: line 356
Read BLUEPRINT_TEMPLATE.md (co-located with this SKILL.md in .claude/skills/~aod-blueprint/) via the Read tool.
- Very specific: line 373
Write the generated guide to docs/guides/BLUEPRINT_{PROJECT}.md via Write tool.
- Very specific: line 375
If write succeeds: Display "Consumer guide written to docs/guides/BLUEPRINT_{PROJECT}.md"
- Distinctive: line 376
If write fails: Display "Warning: Guide generation failed.
- Very specific: line 416
Issue creation script: All GitHub Issue creation must use .aod/scripts/bash/create-issue.sh (KB #20), not raw gh issue create.
≈ “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.
Files
/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:
- First-Run -- Creates GitHub repo, registers project with orchestrator API, activates it, runs interactive intake, generates stories, creates issues
- Subsequent-Run -- Skips setup, runs interactive intake, generates new stories with deduplication against existing issues
- Demo Mode (
--demo) -- Loads pre-built Hello World stories fromHELLO_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
.gitsuffix. For example,https://github.com/org/my-project.gityieldsmy-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
namefield matches{project_name}(case-insensitive comparison), OR - The
repo_urlfield 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'sidas{project_id}
1.4: Parse Demo Flag
Check $ARGUMENTS for the --demo flag.
- If
$ARGUMENTScontains--demo→ setdemo = 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} --publicStore 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:
- Extract
{pack_name}, readstacks/{pack_name}/STACK.md(first 20 lines) for{stack_description} - Display: "Active pack detected: {pack_name} ({stack_description})"
- AskUserQuestion: "Use this pack for story generation?" — "Yes" or "Select different stack"
- If "Yes": store
{selected_pack} = {pack_name}, proceed to Step 3.6
If no active pack or user wants different:
- Glob
stacks/*/STACK.md. If packs found, display numbered list and ask user to select, with options for "Help me choose" and "Custom stack" - If "Help me choose": ask 4 guided questions (project type, deployment, language, database), recommend best-fit pack
- 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.
- Read
docs/guides/HELLO_WORLD_STORIES.mdvia 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.
- If file is missing, display error and STOP:
- 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 Criteriasection - Technical notes from
### Technical Notessection
- Title from
- 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.
- 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,urlParse 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:
- Compare the story title against existing issue titles (case-insensitive exact match)
- If match found: Log "Skipping duplicate: {title} (matches #{number})". Store the matched issue number and URL.
- If no match: Create the issue via Bash tool:
bash .aod/scripts/bash/create-issue.sh --title "{story_title}" --body "{formatted_body}" --stage discoverThe {formatted_body} must include: user story, ICE score breakdown, DoD checklist, dependency tier, and description.
- After each creation, run
sleep 1(rate limit protection per FR-010) - 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 skippedStore 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.runEdge Cases
- Orchestrator API unreachable: Fast-fail at Step 0.2 with setup instructions. No partial state created.
ghCLI not installed or not authenticated: Fast-fail at Step 0.1. Display install link andgh auth logininstructions.- 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.shcalls (Step 4.2) provides baseline protection. Ifcreate-issue.shfails, log the error and continue with remaining stories. HELLO_WORLD_STORIES.mdmissing with--demo: Error with suggestion to run without--demo(Step 3D).worktree_rootnot a git repo:POST /api/v1/projectsreturns 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.kickstartmust remain unmodified (FR-018). Blueprint implements patterns independently. - ADR-016 headers: All
curlcalls 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 rawgh 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
|| trueguards (KB #14).
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
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.

