From 72a552c196aa0c17ddc54d0a4296c4b7372abc6e Mon Sep 17 00:00:00 2001 From: David Matousek Date: Mon, 9 Feb 2026 19:26:45 -0500 Subject: [PATCH] =?UTF-8?q?feat:=20sync=20v5.0.0=20=E2=80=94=20AOD=20Lifec?= =?UTF-8?q?ycle=20Formalization=20+=20GitHub=20Projects=20Board?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BREAKING CHANGES: - Command namespace unified: /pdl.* + /triad.* → /aod.* - All 14 old command files deleted, 16 new aod.* commands added - 9 old skill directories deleted, 10 new aod-* skills added Feature 010 — AOD Lifecycle Formalization: - Unified /aod.* command namespace with 16 lifecycle commands - /aod.plan router auto-detects spec/project-plan/tasks sub-step - 3 governance tiers: Light (2 gates), Standard (6), Full (all) - GitHub Issue + label lifecycle tracking across 5 stages - New scripts: github-lifecycle.sh, backlog-regenerate.sh, migrate-backlog.sh - Guides renamed: PDL_TRIAD_* → AOD_LIFECYCLE/QUICKSTART/MIGRATION Feature 011 — GitHub Projects Lifecycle Board: - Visual kanban board via GitHub Projects (v2) with 5 AOD columns - Auto-add/move issues on stage transitions - 7-level graceful degradation (board never blocks core workflow) - Prerequisites: gh CLI 2.40+, project OAuth scope Sync details: - Source: product-led-spec-kit (main @ 5b6d59f) - Method: scripts/extract.sh --sync + manual stale file deletion - Preserved: .github templates, CODE_OF_CONDUCT, CONTRIBUTING, ARTICLE_SERIES - Reset: PRD INDEX, IDEAS, USER_STORIES to template state - Fixed: stale /triad.* refs in example feature specs and PRD template Co-Authored-By: Claude Opus 4.6 --- .aod/memory/constitution.md | 89 +- .aod/scripts/bash/backlog-regenerate.sh | 247 +++++ .aod/scripts/bash/check-prerequisites.sh | 6 +- .aod/scripts/bash/github-lifecycle.sh | 878 ++++++++++++++++++ .aod/scripts/bash/migrate-backlog.sh | 155 ++++ .aod/templates/checklist-template.md | 4 +- .aod/templates/plan-template.md | 4 +- .aod/templates/tasks-template.md | 2 +- .claude/INFRASTRUCTURE_SETUP_SUMMARY.md | 50 +- .claude/README.md | 92 +- .claude/agents/orchestrator.md | 29 +- .claude/agents/product-manager.md | 14 +- .../{triad.analyze.md => aod.analyze.md} | 8 +- .../{triad.implement.md => aod.build.md} | 32 +- .../{triad.checklist.md => aod.checklist.md} | 4 +- .../{triad.clarify.md => aod.clarify.md} | 8 +- ...ad.constitution.md => aod.constitution.md} | 0 .../commands/{triad.prd.md => aod.define.md} | 15 +- ...{triad.close-feature.md => aod.deliver.md} | 31 +- .../commands/{pdl.idea.md => aod.discover.md} | 2 +- .claude/commands/aod.plan.md | 27 + .../{triad.plan.md => aod.project-plan.md} | 13 +- .../commands/{pdl.score.md => aod.score.md} | 4 +- .../{triad.specify.md => aod.spec.md} | 17 +- .claude/commands/aod.status.md | 25 + .../commands/{triad.tasks.md => aod.tasks.md} | 2 +- .claude/commands/continue.md | 6 +- .claude/commands/execute.md | 2 +- .claude/commands/pdl.run.md | 49 - .claude/commands/pdl.validate.md | 51 - .claude/rules/commands.md | 30 +- .claude/rules/governance.md | 8 +- .../README.md | 10 +- .../SKILL.md | 8 +- .../USAGE.md | 12 +- .../assets/CHECKPOINTS_README_template.md | 0 .../references/checkpoint_template.md | 0 .../references/metrics_formulas.md | 0 .../references/naming_conventions.md | 0 .../scripts/analyze_tasks.py | 0 .../scripts/generate_checkpoint.py | 4 +- .../scripts/update_index.py | 0 .../{prd-create => aod-define}/skill.md | 16 +- .claude/skills/aod-deliver/SKILL.md | 318 +++++++ .claude/skills/aod-discover/SKILL.md | 477 ++++++++++ .../{thinking-lens => aod-lens}/SKILL.md | 2 +- .claude/skills/aod-plan/SKILL.md | 138 +++ .../SKILL.md | 4 +- .../skills/{pdl-score => aod-score}/SKILL.md | 14 +- .../{spec-validator => aod-spec}/SKILL.md | 10 +- .claude/skills/aod-status/SKILL.md | 89 ++ .claude/skills/pdl-idea/SKILL.md | 183 ---- .claude/skills/pdl-run/SKILL.md | 238 ----- .claude/skills/pdl-validate/SKILL.md | 254 ----- .claude/skills/triad/architect-review.md | 6 +- .claude/skills/triad/pm-review.md | 6 +- .claude/skills/triad/teamlead-review.md | 2 +- .gitignore | 1 + CHANGELOG.md | 113 ++- CLAUDE.md | 18 +- MIGRATION.md | 4 +- README.md | 328 +++++-- docs/AOD_TRIAD.md | 140 +-- docs/ARTICLE_SERIES.md | 6 +- docs/INSTITUTIONAL_KNOWLEDGE.md | 96 +- ...RIAD_INFOGRAPHIC.md => AOD_INFOGRAPHIC.md} | 102 +- docs/guides/AOD_LIFECYCLE.md | 259 ++++++ docs/guides/AOD_LIFECYCLE_GUIDE.md | 286 ++++++ docs/guides/AOD_MIGRATION.md | 136 +++ docs/guides/AOD_QUICKSTART.md | 186 ++++ docs/guides/PDL_TRIAD_LIFECYCLE.md | 339 ------- docs/guides/PDL_TRIAD_QUICKSTART.md | 191 ---- docs/product/01_Product_Vision/README.md | 4 +- docs/product/02_PRD/000-example-feature.md | 4 +- docs/product/03_Product_Roadmap/README.md | 2 +- docs/product/04_Journey_Maps/README.md | 2 +- docs/product/_backlog/README.md | 26 +- docs/standards/PRODUCT_SPEC_ALIGNMENT.md | 30 +- docs/standards/TRIAD_COLLABORATION.md | 8 +- scripts/extract.sh | 320 +++++++ scripts/init.sh | 12 +- specs/000-example-feature/plan.md | 2 +- specs/000-example-feature/spec.md | 2 +- specs/000-example-feature/tasks.md | 2 +- 84 files changed, 4548 insertions(+), 1766 deletions(-) create mode 100755 .aod/scripts/bash/backlog-regenerate.sh create mode 100755 .aod/scripts/bash/github-lifecycle.sh create mode 100755 .aod/scripts/bash/migrate-backlog.sh rename .claude/commands/{triad.analyze.md => aod.analyze.md} (94%) rename .claude/commands/{triad.implement.md => aod.build.md} (81%) rename .claude/commands/{triad.checklist.md => aod.checklist.md} (98%) rename .claude/commands/{triad.clarify.md => aod.clarify.md} (96%) rename .claude/commands/{triad.constitution.md => aod.constitution.md} (100%) rename .claude/commands/{triad.prd.md => aod.define.md} (88%) rename .claude/commands/{triad.close-feature.md => aod.deliver.md} (78%) rename .claude/commands/{pdl.idea.md => aod.discover.md} (93%) create mode 100644 .claude/commands/aod.plan.md rename .claude/commands/{triad.plan.md => aod.project-plan.md} (94%) rename .claude/commands/{pdl.score.md => aod.score.md} (90%) rename .claude/commands/{triad.specify.md => aod.spec.md} (92%) create mode 100644 .claude/commands/aod.status.md rename .claude/commands/{triad.tasks.md => aod.tasks.md} (99%) delete mode 100644 .claude/commands/pdl.run.md delete mode 100644 .claude/commands/pdl.validate.md rename .claude/skills/{implementation-checkpoint => aod-build}/README.md (97%) rename .claude/skills/{implementation-checkpoint => aod-build}/SKILL.md (98%) rename .claude/skills/{implementation-checkpoint => aod-build}/USAGE.md (96%) rename .claude/skills/{implementation-checkpoint => aod-build}/assets/CHECKPOINTS_README_template.md (100%) rename .claude/skills/{implementation-checkpoint => aod-build}/references/checkpoint_template.md (100%) rename .claude/skills/{implementation-checkpoint => aod-build}/references/metrics_formulas.md (100%) rename .claude/skills/{implementation-checkpoint => aod-build}/references/naming_conventions.md (100%) rename .claude/skills/{implementation-checkpoint => aod-build}/scripts/analyze_tasks.py (100%) rename .claude/skills/{implementation-checkpoint => aod-build}/scripts/generate_checkpoint.py (99%) rename .claude/skills/{implementation-checkpoint => aod-build}/scripts/update_index.py (100%) rename .claude/skills/{prd-create => aod-define}/skill.md (97%) create mode 100644 .claude/skills/aod-deliver/SKILL.md create mode 100644 .claude/skills/aod-discover/SKILL.md rename .claude/skills/{thinking-lens => aod-lens}/SKILL.md (99%) create mode 100644 .claude/skills/aod-plan/SKILL.md rename .claude/skills/{architecture-validator => aod-project-plan}/SKILL.md (98%) rename .claude/skills/{pdl-score => aod-score}/SKILL.md (94%) rename .claude/skills/{spec-validator => aod-spec}/SKILL.md (95%) create mode 100644 .claude/skills/aod-status/SKILL.md delete mode 100644 .claude/skills/pdl-idea/SKILL.md delete mode 100644 .claude/skills/pdl-run/SKILL.md delete mode 100644 .claude/skills/pdl-validate/SKILL.md rename docs/guides/{PDL_TRIAD_INFOGRAPHIC.md => AOD_INFOGRAPHIC.md} (54%) create mode 100644 docs/guides/AOD_LIFECYCLE.md create mode 100644 docs/guides/AOD_LIFECYCLE_GUIDE.md create mode 100644 docs/guides/AOD_MIGRATION.md create mode 100644 docs/guides/AOD_QUICKSTART.md delete mode 100644 docs/guides/PDL_TRIAD_LIFECYCLE.md delete mode 100644 docs/guides/PDL_TRIAD_QUICKSTART.md create mode 100755 scripts/extract.sh diff --git a/.aod/memory/constitution.md b/.aod/memory/constitution.md index 4d56d89..b5a6d03 100644 --- a/.aod/memory/constitution.md +++ b/.aod/memory/constitution.md @@ -214,7 +214,7 @@ Product artifacts in docs/product/ are the strategic foundation, and project arc - **Architecture Review**: Sound product strategy without technical consistency creates fragmented systems. The Architect ensures every technical decision aligns with project architecture, maintains system integrity, and avoids technical debt. **Non-Negotiable Requirements**: -- ALWAYS create PRD before spec.md (use `/triad.prd`) +- ALWAYS create PRD before spec.md (use `/aod.define`) - ALWAYS validate spec.md aligns with product vision, OKRs, and user stories - ALWAYS get PM sign-off on spec.md before creating plan.md - ALWAYS get Architect review on plan.md for technical decisions and architecture alignment @@ -412,7 +412,7 @@ Product Manager is responsible for maintaining alignment between: - Architect ensures technical consistency (architecture ↔ plan.md ↔ tasks.md ↔ code) **Enforcement**: -- Use `/triad.analyze` to validate product-spec-architecture consistency +- Use `/aod.analyze` to validate product-spec-architecture consistency - Triad workflows enforce dual sign-off (PM + Architect) before progression - PRs without PM and Architect approval are blocked from merge - Sign-offs are documented in artifact metadata @@ -420,11 +420,11 @@ Product Manager is responsible for maintaining alignment between: **Tools & Skills**: - **product-manager agent**: Product Manager with alignment validation expertise - **architect agent**: Architect with technical design and review expertise -- **/triad.prd**: Create PRD documents -- **/triad.specify**: Create specifications from PRD inputs -- **/triad.plan**: Create technical plans from specifications -- **/triad.tasks**: Create implementation tasks from plans -- **/triad.analyze**: Validate consistency across artifacts +- **/aod.define**: Create PRD documents +- **/aod.spec**: Create specifications from PRD inputs +- **/aod.project-plan**: Create technical plans from specifications +- **/aod.tasks**: Create implementation tasks from plans +- **/aod.analyze**: Validate consistency across artifacts **Reference**: See `.claude/agents/product-manager.md` for PM responsibilities, `.claude/agents/architect.md` for Architect responsibilities, and `docs/standards/PRODUCT_SPEC_ALIGNMENT.md` for comprehensive alignment guide @@ -454,7 +454,7 @@ Product Manager is responsible for maintaining alignment between: 0. **PM**: Analyze product need (What & Why) - read product vision, OKRs, user stories 0.5. **Architect**: Provide baseline report documenting current infrastructure state -1. **PM**: Draft PRD via `/triad.prd`, incorporating Architect baseline into "Current State" section +1. **PM**: Draft PRD via `/aod.define`, incorporating Architect baseline into "Current State" section 2. **Tech-Lead**: Feasibility review - estimate timeline, identify agents needed, validate capacity 3. **Architect**: Technical review - validate infrastructure claims match baseline, confirm technical feasibility 4. **PM**: Finalize PRD incorporating all Triad feedback @@ -462,7 +462,7 @@ Product Manager is responsible for maintaining alignment between: **For Feature PRDs** (greenfield work): 0. **PM**: Analyze product need (What & Why) -1. **PM**: Draft PRD via `/triad.prd` +1. **PM**: Draft PRD via `/aod.define` 2. **[Parallel]** Architect + Tech-Lead: Review PRD for technical feasibility and timeline accuracy 3. **PM**: Finalize PRD incorporating Triad feedback @@ -540,6 +540,75 @@ All PRDs MUST have: --- +## AOD Lifecycle Model + +### Lifecycle Stages + +The AOD Lifecycle is a single, named sequence of **5 stages** organized into **2 phases**. All work passes through these stages in order. + +**Discovery Phase** (What to build): + +| Stage | Purpose | Primary Command | +|-------|---------|-----------------| +| **Discover** | Capture ideas, score with ICE, gather evidence | `/aod.discover` | +| **Define** | Create PRD with Triad validation | `/aod.define` | + +**Delivery Phase** (How to build and ship): + +| Stage | Purpose | Primary Command | +|-------|---------|-----------------| +| **Plan** | Create spec, architecture plan, and task breakdown | `/aod.plan` | +| **Build** | Implement tasks with Architect checkpoints | `/aod.build` | +| **Deliver** | Validate against DoD, run retrospective, close feature | `/aod.deliver` | + +### Governance Gates + +Governance gates are a **separate layer** from lifecycle stages. Gates are Triad approval checkpoints that operate **at stage boundaries** -- they determine who approves, not what work is done. + +| Gate Location | Checkpoint | Approvers | +|---------------|------------|-----------| +| Discover exit | ICE score + PM validation | PM | +| Define exit | PRD Triad review | PM + Architect + Team-Lead | +| Plan: spec | Spec sign-off | PM | +| Plan: project-plan | Plan sign-off | PM + Architect | +| Plan: tasks | Triple sign-off | PM + Architect + Team-Lead | +| Build (continuous) | Architect checkpoints | Architect | +| Deliver exit | Definition of Done check | PM + Architect + Team-Lead | + +**Invariants**: +- Triple sign-off (PM + Architect + Team-Lead on tasks.md) is the **minimum governance floor** for all tiers +- DoD check applies to **all tiers** +- Architect build checkpoints apply to **all tiers** + +### Governance Tiers + +Three tiers determine which gates are active. Tiers affect only the Discover, Define, and Plan stage gates. + +| Tier | Discover Gate | Define Gate | Plan Gates | Build Gate | Deliver Gate | +|------|---------------|-------------|------------|------------|--------------| +| **Light** | Optional | Skip | Triple sign-off only | On | DoD | +| **Standard** (default) | On | On | PM+Arch + Triple | On | DoD | +| **Full** | On | On | PM spec + PM+Arch plan + Triple | On | DoD | + +**When to use each tier**: + +- **Light** (2 gates): Solo developers, prototypes, internal tools. Minimizes ceremony while preserving the governance floor (Triple sign-off + DoD). +- **Standard** (6 gates, default): Team projects and production features. All Discover, Define, and Plan gates active with Architect checkpoints in Build. +- **Full** (all gates): Regulated industries, critical systems, high-risk deployments. Adds a separate PM spec sign-off in the Plan stage for maximum traceability. + +### Governance Configuration + +Configure the active governance tier in the constitution frontmatter or project configuration: + +```yaml +governance: + tier: standard # valid values: light | standard | full +``` + +The tier is configured **per project**, not per feature. The default tier is `standard`. + +--- + ## System Architecture Constraints ### Backend Requirements @@ -628,7 +697,7 @@ All PRDs MUST have: - All pull requests MUST verify compliance with constitution principles - Architecture decisions MUST reference relevant principles -- Use `/triad.analyze` to verify consistency across spec, plan, and tasks +- Use `/aod.analyze` to verify consistency across spec, plan, and tasks - Constitution supersedes all other practices and conventions ### Living Document diff --git a/.aod/scripts/bash/backlog-regenerate.sh b/.aod/scripts/bash/backlog-regenerate.sh new file mode 100755 index 0000000..9102113 --- /dev/null +++ b/.aod/scripts/bash/backlog-regenerate.sh @@ -0,0 +1,247 @@ +#!/usr/bin/env bash + +# BACKLOG.md regeneration from GitHub Issues +# +# Queries GitHub Issues with stage:* labels and generates a grouped +# Markdown file at docs/product/_backlog/BACKLOG.md. +# +# Usage: ./backlog-regenerate.sh [--json] +# +# Options: +# --json Output summary as JSON instead of text +# +# Algorithm: +# 1. gh issue list with structured JSON fields +# 2. Warn if exactly 100 items returned (pagination limit) +# 3. Group by stage:* label +# 4. Extract stage-specific fields from issue body (defensive parsing) +# 5. Render Markdown tables per stage +# 6. Items without stage:* label → "Untracked" section +# 7. Idempotent: same GitHub state → identical output + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/common.sh" +source "$SCRIPT_DIR/github-lifecycle.sh" + +JSON_MODE=false +for arg in "$@"; do + case "$arg" in + --json) JSON_MODE=true ;; + esac +done + +REPO_ROOT=$(get_repo_root) +BACKLOG_DIR="$REPO_ROOT/docs/product/_backlog" +BACKLOG_FILE="$BACKLOG_DIR/BACKLOG.md" + +# Ensure output directory exists +mkdir -p "$BACKLOG_DIR" + +# Check gh availability +if ! aod_gh_check_available; then + echo "[aod] Cannot regenerate BACKLOG.md without GitHub access." >&2 + exit 0 +fi + +# Fetch all issues (open and closed) with stage:* labels +RAW_JSON=$(gh issue list --json number,title,labels,updatedAt,state,body --state all --limit 100 2>/dev/null) || { + echo "[aod] Warning: Failed to fetch GitHub Issues. BACKLOG.md not updated." >&2 + exit 0 +} + +# Pagination warning (T061) +ISSUE_COUNT=$(echo "$RAW_JSON" | grep -o '"number"' | wc -l | tr -d ' ') +if [[ "$ISSUE_COUNT" -eq 100 ]]; then + echo "[aod] Warning: Backlog may be truncated (100 item limit). Consider implementing pagination or archiving old items." >&2 +fi + +# Helper: extract a section value from issue body (defensive, T062) +# Args: $1 = body text, $2 = section header (e.g., "## ICE Score") +# Returns: first non-empty line after header, or "—" if not found +extract_section() { + local body="$1" + local header="$2" + local value + + # Find content after the header, take first non-empty line + value=$(echo "$body" | sed -n "/^${header}/,/^##/{/^${header}/d;/^##/d;/^$/d;p;}" | head -1 | sed 's/^[[:space:]]*//') + + if [[ -z "$value" ]]; then + echo "—" + else + echo "$value" + fi +} + +# Helper: extract field from Metadata section +# Args: $1 = body text, $2 = field name (e.g., "Source") +extract_metadata() { + local body="$1" + local field="$2" + local value + + value=$(echo "$body" | grep -o "- ${field}: .*" | head -1 | sed "s/- ${field}: //") + + if [[ -z "$value" ]]; then + echo "—" + else + echo "$value" + fi +} + +# Generate BACKLOG.md +generate_backlog() { + local timestamp + timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ") + + cat <
Auto-generated from GitHub Issues on ${timestamp}. +> Source of truth: GitHub Issues with \`stage:*\` labels. +> Regenerate: \`/aod.status\` or \`.aod/scripts/bash/backlog-regenerate.sh\` + +HEADER + + # Process each stage + for stage in discover define plan build deliver; do + local label="stage:${stage}" + + echo "## ${stage^}" + echo "" + + # Filter issues for this stage using label name matching + local stage_issues + stage_issues=$(echo "$RAW_JSON" | python3 -c " +import json, sys +data = json.load(sys.stdin) +for issue in data: + labels = [l['name'] for l in issue.get('labels', [])] + if '${label}' in labels: + # Escape pipe chars in title for markdown table + title = issue['title'].replace('|', '\\\\|') + body = issue.get('body', '') or '' + updated = issue.get('updatedAt', '—')[:10] + number = issue['number'] + print(f'{number}|{title}|{updated}|{body}') +" 2>/dev/null) || stage_issues="" + + # Stage-specific table headers + case "$stage" in + discover) + echo "| # | Title | ICE | Evidence | Updated |" + echo "|---|-------|-----|----------|---------|" + ;; + define) + echo "| # | Title | PRD | Updated |" + echo "|---|-------|-----|---------|" + ;; + plan) + echo "| # | Title | Spec | Plan | Tasks | Updated |" + echo "|---|-------|------|------|-------|---------|" + ;; + build) + echo "| # | Title | Progress | Updated |" + echo "|---|-------|----------|---------|" + ;; + deliver) + echo "| # | Title | Delivered | Retro | Updated |" + echo "|---|-------|-----------|-------|---------|" + ;; + esac + + if [[ -z "$stage_issues" ]]; then + echo "| — | *No items in this stage* | | |" + else + while IFS='|' read -r num title updated body; do + case "$stage" in + discover) + local ice + ice=$(extract_section "$body" "## ICE Score") + local evidence + evidence=$(extract_section "$body" "## Evidence") + # Truncate evidence for table display + if [[ ${#evidence} -gt 60 ]]; then + evidence="${evidence:0:57}..." + fi + echo "| #${num} | ${title} | ${ice} | ${evidence} | ${updated} |" + ;; + define) + local prd + prd=$(extract_metadata "$body" "PRD") + echo "| #${num} | ${title} | ${prd} | ${updated} |" + ;; + plan) + echo "| #${num} | ${title} | — | — | — | ${updated} |" + ;; + build) + echo "| #${num} | ${title} | In progress | ${updated} |" + ;; + deliver) + echo "| #${num} | ${title} | ${updated} | — | ${updated} |" + ;; + esac + done <<< "$stage_issues" + fi + + echo "" + done + + # Untracked section: issues without any stage:* label + local untracked + untracked=$(echo "$RAW_JSON" | python3 -c " +import json, sys +data = json.load(sys.stdin) +stage_labels = {'stage:discover', 'stage:define', 'stage:plan', 'stage:build', 'stage:deliver'} +for issue in data: + labels = {l['name'] for l in issue.get('labels', [])} + if not labels.intersection(stage_labels): + title = issue['title'].replace('|', '\\\\|') + updated = issue.get('updatedAt', '—')[:10] + number = issue['number'] + state = issue.get('state', 'OPEN') + print(f'{number}|{title}|{state}|{updated}') +" 2>/dev/null) || untracked="" + + if [[ -n "$untracked" ]]; then + echo "## Untracked" + echo "" + echo "> These issues have no \`stage:*\` label. Add a label to track them in the lifecycle." + echo "" + echo "| # | Title | State | Updated |" + echo "|---|-------|-------|---------|" + while IFS='|' read -r num title state updated; do + echo "| #${num} | ${title} | ${state} | ${updated} |" + done <<< "$untracked" + echo "" + fi +} + +# Write to file +OUTPUT=$(generate_backlog) +echo "$OUTPUT" > "$BACKLOG_FILE" + +# Summary +if $JSON_MODE; then + # Count items per stage + python3 -c " +import json, sys +data = json.load(sys.stdin) +counts = {'discover': 0, 'define': 0, 'plan': 0, 'build': 0, 'deliver': 0, 'untracked': 0} +stage_labels = {'stage:discover', 'stage:define', 'stage:plan', 'stage:build', 'stage:deliver'} +for issue in data: + labels = {l['name'] for l in issue.get('labels', [])} + matched = labels.intersection(stage_labels) + if matched: + stage = list(matched)[0].split(':')[1] + counts[stage] += 1 + else: + counts['untracked'] += 1 +print(json.dumps({'file': '${BACKLOG_FILE}', 'total': len(data), 'stages': counts})) +" <<< "$RAW_JSON" +else + echo "[aod] BACKLOG.md regenerated at ${BACKLOG_FILE}" + echo "[aod] Total issues: ${ISSUE_COUNT}" +fi diff --git a/.aod/scripts/bash/check-prerequisites.sh b/.aod/scripts/bash/check-prerequisites.sh index 3d338f5..5cc9376 100755 --- a/.aod/scripts/bash/check-prerequisites.sh +++ b/.aod/scripts/bash/check-prerequisites.sh @@ -102,20 +102,20 @@ fi # Validate required directories and files if [[ ! -d "$FEATURE_DIR" ]]; then echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2 - echo "Run /triad.specify first to create the feature structure." >&2 + echo "Run /aod.spec first to create the feature structure." >&2 exit 1 fi if [[ ! -f "$IMPL_PLAN" ]]; then echo "ERROR: plan.md not found in $FEATURE_DIR" >&2 - echo "Run /triad.plan first to create the implementation plan." >&2 + echo "Run /aod.project-plan first to create the implementation plan." >&2 exit 1 fi # Check for tasks.md if required if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2 - echo "Run /triad.tasks first to create the task list." >&2 + echo "Run /aod.tasks first to create the task list." >&2 exit 1 fi diff --git a/.aod/scripts/bash/github-lifecycle.sh b/.aod/scripts/bash/github-lifecycle.sh new file mode 100755 index 0000000..bec7620 --- /dev/null +++ b/.aod/scripts/bash/github-lifecycle.sh @@ -0,0 +1,878 @@ +#!/usr/bin/env bash + +# GitHub Issue lifecycle integration for AOD +# +# Provides functions for creating/updating GitHub Issues with stage:* labels. +# All functions gracefully degrade — they return 0 on failure and emit warnings. +# +# Usage: source this file, then call functions directly. +# +# Functions: +# aod_gh_check_available — verify gh CLI + remote configured +# aod_gh_check_board_prereqs — verify gh version >= 2.40 and project scope +# aod_gh_validate_cache — validate board cache file integrity +# aod_gh_check_board — board availability check (prereqs + cache + hint) +# aod_gh_setup_board — one-time board creation + Status field config + cache +# aod_gh_add_to_board — add issue to Projects board and set Status column +# aod_gh_move_on_board — move issue to new Status column (auto-adds if missing) +# aod_gh_create_issue — create issue with stage:* label (or update existing) +# aod_gh_update_stage — transition issue to new stage label +# aod_gh_find_issue — find existing issue by title or IDEA-NNN tag +# +# Expected Issue body format: +# # [IDEA-NNN] Title +# ## ICE Score +# Impact: N, Confidence: N, Effort: N = **Total** +# ## Evidence +# [evidence statement] +# ## User Story +# As a [role], I want [capability], so that [benefit]. +# ## Acceptance Criteria +# - [ ] Criterion 1 +# ## Metadata +# - Source: [Brainstorm | Customer Feedback | ...] +# - Priority: [P0 | P1 | P2 | P3] + +set -euo pipefail + +# All stage labels used by the AOD lifecycle +AOD_STAGE_LABELS=("stage:discover" "stage:define" "stage:plan" "stage:build" "stage:deliver") + +# Board column mapping: AOD stage name → GitHub Projects Status option name +declare -A AOD_STAGE_TO_COLUMN=( + [discover]="Discover" + [define]="Define" + [plan]="Plan" + [build]="Build" + [deliver]="Deliver" +) + +# Board cache file — stores project ID, field IDs, option IDs after setup +AOD_BOARD_CACHE=".aod/memory/github-project.json" + +# Hint marker — prevents repeated first-run tips +AOD_HINT_MARKER=".aod/memory/.board-hint-shown" + +# One-time warning marker paths for board prerequisite checks +AOD_GH_VERSION_WARNED=".aod/memory/.gh-version-warned" +AOD_GH_SCOPE_WARNED=".aod/memory/.gh-scope-warned" + +# Check board prerequisites: gh CLI version >= 2.40 and project scope +# Returns: 0 if both pass, 1 if not (with one-time warnings on stderr) +aod_gh_check_board_prereqs() { + # Check gh version >= 2.40 + local gh_version + gh_version=$(gh --version 2>/dev/null | head -1) || { + echo "[aod] Warning: Could not determine gh CLI version. Board operations skipped." >&2 + return 1 + } + + # Parse version: "gh version X.Y.Z (YYYY-MM-DD)" → extract X.Y + local version_number + version_number=$(echo "$gh_version" | grep -oE '[0-9]+\.[0-9]+' | head -1) + + if [[ -z "$version_number" ]]; then + echo "[aod] Warning: Could not parse gh CLI version. Board operations skipped." >&2 + return 1 + fi + + local major minor + major=$(echo "$version_number" | cut -d. -f1) + minor=$(echo "$version_number" | cut -d. -f2) + + if [[ "$major" -lt 2 ]] || { [[ "$major" -eq 2 ]] && [[ "$minor" -lt 40 ]]; }; then + if [[ ! -f "$AOD_GH_VERSION_WARNED" ]]; then + echo "[aod] Warning: gh CLI version $version_number is below 2.40. GitHub Projects board operations require gh >= 2.40. Please upgrade: https://cli.github.com" >&2 + mkdir -p "$(dirname "$AOD_GH_VERSION_WARNED")" + touch "$AOD_GH_VERSION_WARNED" + fi + return 1 + fi + + # Check project scope via gh auth status + local auth_output + auth_output=$(gh auth status 2>&1) || true + + if ! echo "$auth_output" | grep -q "project"; then + if [[ ! -f "$AOD_GH_SCOPE_WARNED" ]]; then + echo "[aod] Warning: Projects board sync skipped — 'project' OAuth scope not detected. Run 'gh auth refresh -s project' to enable." >&2 + mkdir -p "$(dirname "$AOD_GH_SCOPE_WARNED")" + touch "$AOD_GH_SCOPE_WARNED" + fi + return 1 + fi + + return 0 +} + +# Validate board cache file integrity and owner match +# Returns: 0 if cache valid, 1 if invalid (clears cache on mismatch) +aod_gh_validate_cache() { + # Check cache file exists + if [[ ! -f "$AOD_BOARD_CACHE" ]]; then + return 1 + fi + + # Check valid JSON + if ! jq empty "$AOD_BOARD_CACHE" 2>/dev/null; then + echo "[aod] Warning: Board cache is not valid JSON. Clearing cache." >&2 + rm -f "$AOD_BOARD_CACHE" + return 1 + fi + + # Verify required fields present + local missing_fields=0 + for field in project_number project_id owner status_field_id status_options; do + if [[ "$(jq -r ".$field // empty" "$AOD_BOARD_CACHE" 2>/dev/null)" == "" ]]; then + missing_fields=1 + break + fi + done + + if [[ "$missing_fields" -eq 1 ]]; then + echo "[aod] Warning: Board cache missing required fields. Clearing cache — run 'aod_gh_setup_board' to reconfigure." >&2 + rm -f "$AOD_BOARD_CACHE" + return 1 + fi + + # Verify status_options has exactly 5 entries with non-empty option IDs + local option_count + option_count=$(jq '.status_options | length' "$AOD_BOARD_CACHE" 2>/dev/null) + if [[ "$option_count" != "5" ]]; then + echo "[aod] Warning: Board cache has $option_count status options (expected 5). Clearing cache — run 'aod_gh_setup_board' to reconfigure." >&2 + rm -f "$AOD_BOARD_CACHE" + return 1 + fi + + # Check all option IDs are non-empty + local empty_options + empty_options=$(jq '[.status_options | to_entries[] | select(.value == "" or .value == null)] | length' "$AOD_BOARD_CACHE" 2>/dev/null) + if [[ "$empty_options" != "0" ]]; then + echo "[aod] Warning: Board cache contains empty option IDs. Clearing cache — run 'aod_gh_setup_board' to reconfigure." >&2 + rm -f "$AOD_BOARD_CACHE" + return 1 + fi + + # Verify project_id starts with PVT_ + local project_id + project_id=$(jq -r '.project_id' "$AOD_BOARD_CACHE" 2>/dev/null) + if [[ "$project_id" != PVT_* ]]; then + echo "[aod] Warning: Board cache has invalid project_id format. Clearing cache — run 'aod_gh_setup_board' to reconfigure." >&2 + rm -f "$AOD_BOARD_CACHE" + return 1 + fi + + # Verify status_field_id starts with PVTSSF_ + local status_field_id + status_field_id=$(jq -r '.status_field_id' "$AOD_BOARD_CACHE" 2>/dev/null) + if [[ "$status_field_id" != PVTSSF_* ]]; then + echo "[aod] Warning: Board cache has invalid status_field_id format. Clearing cache — run 'aod_gh_setup_board' to reconfigure." >&2 + rm -f "$AOD_BOARD_CACHE" + return 1 + fi + + # Compare owner against current repo owner + local cached_owner current_owner + cached_owner=$(jq -r '.owner' "$AOD_BOARD_CACHE" 2>/dev/null) + current_owner=$(gh repo view --json owner --jq '.owner.login' 2>/dev/null) || { + echo "[aod] Warning: Could not verify repo owner. Board cache kept but may be stale." >&2 + return 0 + } + + if [[ "$cached_owner" != "$current_owner" ]]; then + echo "[aod] Warning: Repository owner changed (fork?). Cached owner '$cached_owner' does not match current owner '$current_owner'. Board cache cleared — run 'aod_gh_setup_board' to reconfigure." >&2 + rm -f "$AOD_BOARD_CACHE" + return 1 + fi + + return 0 +} + +# Session guard — set to 1 after first successful board check +_AOD_BOARD_CHECKED="${_AOD_BOARD_CHECKED:-0}" + +# Check board availability: prereqs + cache validation + first-run hint +# Returns: 0 if board available, 1 if not +aod_gh_check_board() { + # Return early if already validated this session + if [[ "$_AOD_BOARD_CHECKED" == "1" ]]; then + return 0 + fi + + # Check gh CLI is available first + if ! aod_gh_check_available; then + return 1 + fi + + # Check board-specific prerequisites (version + scope) + if ! aod_gh_check_board_prereqs; then + return 1 + fi + + # Validate cache + if ! aod_gh_validate_cache; then + # No valid cache — show first-run hint if marker doesn't exist + if [[ ! -f "$AOD_HINT_MARKER" ]]; then + echo "[aod] Tip: Run 'aod_gh_setup_board' to create a visual lifecycle board on GitHub Projects." >&2 + mkdir -p "$(dirname "$AOD_HINT_MARKER")" + touch "$AOD_HINT_MARKER" + fi + return 1 + fi + + # All checks passed — mark as checked for this session + _AOD_BOARD_CHECKED=1 + return 0 +} + +# One-time board setup: create GitHub Projects board, configure Status field, cache IDs +# Returns: 0 always (graceful degradation), JSON cache on stdout on success +aod_gh_setup_board() { + # --- Section 1: Prerequisite checks and owner detection --- + + # Check gh CLI is available + if ! aod_gh_check_available; then + echo "[aod] Warning: Board setup requires gh CLI. Skipping." >&2 + return 0 + fi + + # Check board-specific prerequisites (version + scope) + if ! aod_gh_check_board_prereqs; then + echo "[aod] Warning: Board prerequisites not met. Skipping setup." >&2 + return 0 + fi + + # Auto-detect repo owner + local owner + owner=$(gh repo view --json owner --jq '.owner.login' 2>/dev/null) || { + echo "[aod] Warning: Could not detect repository owner. Board setup skipped." >&2 + return 0 + } + + if [[ -z "$owner" ]]; then + echo "[aod] Warning: Repository owner is empty. Board setup skipped." >&2 + return 0 + fi + + # Detect owner type (User vs Organization) + local owner_type + owner_type=$(gh api "users/$owner" --jq '.type' 2>/dev/null) || { + echo "[aod] Warning: Could not detect owner type for '$owner'. Board setup skipped." >&2 + return 0 + } + + echo "[aod] Board setup: owner=$owner (type=$owner_type)" >&2 + + # --- Section 2: Board creation (idempotent) --- + + local project_number="" + local project_id="" + + # Check for existing board by title + local existing_board + existing_board=$(gh project list --owner "$owner" --format json 2>/dev/null) || { + echo "[aod] Warning: Could not list projects for '$owner'. Board setup skipped." >&2 + return 0 + } + + project_number=$(echo "$existing_board" | jq -r '.projects[] | select(.title == "AOD Backlog") | .number' 2>/dev/null | head -1) + + if [[ -n "$project_number" && "$project_number" != "null" ]]; then + # Reuse existing board + echo "[aod] Found existing 'AOD Backlog' board (project #$project_number). Reusing." >&2 + project_id=$(gh project view "$project_number" --owner "$owner" --format json --jq '.id' 2>/dev/null) || { + echo "[aod] Warning: Could not get project ID for board #$project_number. Board setup skipped." >&2 + return 0 + } + else + # Create new board + echo "[aod] Creating 'AOD Backlog' board..." >&2 + local create_result + create_result=$(gh project create --owner "$owner" --title "AOD Backlog" --format json 2>/dev/null) || { + echo "[aod] Warning: Failed to create Projects board. Board setup skipped." >&2 + return 0 + } + + project_number=$(echo "$create_result" | jq -r '.number' 2>/dev/null) + project_id=$(echo "$create_result" | jq -r '.id' 2>/dev/null) + + if [[ -z "$project_number" || "$project_number" == "null" ]]; then + echo "[aod] Warning: Could not parse project number from create response. Board setup skipped." >&2 + return 0 + fi + + echo "[aod] Created board #$project_number." >&2 + fi + + if [[ -z "$project_id" || "$project_id" == "null" ]]; then + echo "[aod] Warning: Could not resolve project ID. Board setup skipped." >&2 + return 0 + fi + + # --- Section 3: Status field configuration --- + + # Get Status field ID + local fields_json + fields_json=$(gh project field-list "$project_number" --owner "$owner" --format json 2>/dev/null) || { + echo "[aod] Warning: Could not list project fields. Board setup skipped." >&2 + return 0 + } + + local status_field_id="" + local status_field_name="Status" + + # Find the built-in Status field (type: ProjectV2SingleSelectField, name: Status) + status_field_id=$(echo "$fields_json" | jq -r '.fields[] | select(.name == "Status" and .type == "ProjectV2SingleSelectField") | .id' 2>/dev/null | head -1) + + if [[ -z "$status_field_id" || "$status_field_id" == "null" ]]; then + echo "[aod] Warning: Could not find Status field. Board setup skipped." >&2 + return 0 + fi + + echo "[aod] Configuring Status field ($status_field_id) with AOD lifecycle stages..." >&2 + + # Update Status field options via GraphQL mutation + local mutation_result + mutation_result=$(gh api graphql -f query=' +mutation($fieldId: ID!) { + updateProjectV2Field(input: { + fieldId: $fieldId, + singleSelectOptions: [ + {name: "Discover", color: BLUE, description: ""}, + {name: "Define", color: PURPLE, description: ""}, + {name: "Plan", color: YELLOW, description: ""}, + {name: "Build", color: ORANGE, description: ""}, + {name: "Deliver", color: GREEN, description: ""} + ] + }) { + projectV2Field { + ... on ProjectV2SingleSelectField { + id + name + options { id name } + } + } + } +}' -f fieldId="$status_field_id" 2>/dev/null) || { + # Fallback: create custom "AOD Stage" field if built-in Status mutation fails + echo "[aod] Warning: Could not update built-in Status field. Attempting custom 'AOD Stage' field..." >&2 + status_field_name="AOD Stage" + + local fallback_result + fallback_result=$(gh project field-create "$project_number" --owner "$owner" \ + --name "AOD Stage" --data-type "SINGLE_SELECT" \ + --single-select-options "Discover,Define,Plan,Build,Deliver" --format json 2>/dev/null) || { + echo "[aod] Warning: Failed to create custom 'AOD Stage' field. Board setup skipped." >&2 + return 0 + } + + # Re-read fields to get the new field ID and options + fields_json=$(gh project field-list "$project_number" --owner "$owner" --format json 2>/dev/null) || { + echo "[aod] Warning: Could not re-read fields after creating custom field. Board setup skipped." >&2 + return 0 + } + + status_field_id=$(echo "$fields_json" | jq -r '.fields[] | select(.name == "AOD Stage" and .type == "ProjectV2SingleSelectField") | .id' 2>/dev/null | head -1) + + if [[ -z "$status_field_id" || "$status_field_id" == "null" ]]; then + echo "[aod] Warning: Could not find newly created 'AOD Stage' field. Board setup skipped." >&2 + return 0 + fi + + # Build mutation_result-compatible JSON from field-list for option parsing + mutation_result=$(echo "$fields_json" | jq '{data: {updateProjectV2Field: {projectV2Field: (.fields[] | select(.name == "AOD Stage"))}}}' 2>/dev/null) + } + + # Parse option IDs from mutation response + local discover_id define_id plan_id build_id deliver_id + + discover_id=$(echo "$mutation_result" | jq -r '.data.updateProjectV2Field.projectV2Field.options[] | select(.name == "Discover") | .id' 2>/dev/null) + define_id=$(echo "$mutation_result" | jq -r '.data.updateProjectV2Field.projectV2Field.options[] | select(.name == "Define") | .id' 2>/dev/null) + plan_id=$(echo "$mutation_result" | jq -r '.data.updateProjectV2Field.projectV2Field.options[] | select(.name == "Plan") | .id' 2>/dev/null) + build_id=$(echo "$mutation_result" | jq -r '.data.updateProjectV2Field.projectV2Field.options[] | select(.name == "Build") | .id' 2>/dev/null) + deliver_id=$(echo "$mutation_result" | jq -r '.data.updateProjectV2Field.projectV2Field.options[] | select(.name == "Deliver") | .id' 2>/dev/null) + + # Validate all option IDs are non-empty + if [[ -z "$discover_id" || -z "$define_id" || -z "$plan_id" || -z "$build_id" || -z "$deliver_id" ]]; then + echo "[aod] Warning: Could not parse all 5 option IDs from Status field configuration. Board setup skipped." >&2 + return 0 + fi + + echo "[aod] Status field configured with 5 AOD stages." >&2 + + # --- Section 4: Cache writing and cleanup --- + + # Write cache JSON to .aod/memory/github-project.json + local cache_json + cache_json=$(jq -n \ + --argjson project_number "$project_number" \ + --arg project_id "$project_id" \ + --arg owner "$owner" \ + --arg owner_type "$owner_type" \ + --arg status_field_id "$status_field_id" \ + --arg status_field_name "$status_field_name" \ + --arg discover_id "$discover_id" \ + --arg define_id "$define_id" \ + --arg plan_id "$plan_id" \ + --arg build_id "$build_id" \ + --arg deliver_id "$deliver_id" \ + --arg created_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + '{ + project_number: $project_number, + project_id: $project_id, + owner: $owner, + owner_type: $owner_type, + status_field_id: $status_field_id, + status_field_name: $status_field_name, + status_options: { + Discover: $discover_id, + Define: $define_id, + Plan: $plan_id, + Build: $build_id, + Deliver: $deliver_id + }, + created_at: $created_at + }') + + mkdir -p "$(dirname "$AOD_BOARD_CACHE")" + echo "$cache_json" > "$AOD_BOARD_CACHE" + + # Remove hint marker on successful setup + rm -f "$AOD_HINT_MARKER" + + # Clear version/scope warning markers (setup success proves they're no longer relevant) + rm -f "$AOD_GH_VERSION_WARNED" + rm -f "$AOD_GH_SCOPE_WARNED" + + # Reset session guard so next check uses fresh cache + _AOD_BOARD_CHECKED=0 + + echo "[aod] Board setup complete. Cache written to $AOD_BOARD_CACHE" >&2 + echo "$cache_json" + + return 0 +} + +# Add an issue to the GitHub Projects board and set its Status column +# Args: +# $1 = issue_url (required, full GitHub issue URL) +# $2 = stage (required, one of: discover, define, plan, build, deliver) +# Returns: 0 always (graceful degradation), item ID on stdout on success +# Stderr: warnings on any failure +aod_gh_add_to_board() { + local issue_url="${1:-}" + local stage="${2:-}" + + if [[ -z "$issue_url" || -z "$stage" ]]; then + echo "[aod] Warning: Missing issue_url or stage for board add. Skipping." >&2 + return 0 + fi + + # Check board availability (prereqs + cache); skip silently if unavailable + if ! aod_gh_check_board; then + return 0 + fi + + # --- Read cache values --- + + local project_number project_id owner status_field_id + + project_number=$(jq -r '.project_number' "$AOD_BOARD_CACHE" 2>/dev/null) || { + echo "[aod] Warning: Could not read project_number from board cache. Board add skipped." >&2 + return 0 + } + + project_id=$(jq -r '.project_id' "$AOD_BOARD_CACHE" 2>/dev/null) || { + echo "[aod] Warning: Could not read project_id from board cache. Board add skipped." >&2 + return 0 + } + + owner=$(jq -r '.owner' "$AOD_BOARD_CACHE" 2>/dev/null) || { + echo "[aod] Warning: Could not read owner from board cache. Board add skipped." >&2 + return 0 + } + + status_field_id=$(jq -r '.status_field_id' "$AOD_BOARD_CACHE" 2>/dev/null) || { + echo "[aod] Warning: Could not read status_field_id from board cache. Board add skipped." >&2 + return 0 + } + + # Defense-in-depth: verify cache values are non-empty before API calls + if [[ -z "$project_number" || "$project_number" == "null" || -z "$project_id" || "$project_id" == "null" || -z "$owner" || "$owner" == "null" || -z "$status_field_id" || "$status_field_id" == "null" ]]; then + echo "[aod] Warning: Board cache contains empty values. Board add skipped — run 'aod_gh_setup_board' to reconfigure." >&2 + return 0 + fi + + # --- Map stage to option ID --- + + local column_name="${AOD_STAGE_TO_COLUMN[$stage]:-}" + + if [[ -z "$column_name" ]]; then + echo "[aod] Warning: Unknown stage '$stage'. Valid stages: discover, define, plan, build, deliver. Board add skipped." >&2 + return 0 + fi + + local option_id + option_id=$(jq -r ".status_options.\"$column_name\"" "$AOD_BOARD_CACHE" 2>/dev/null) || { + echo "[aod] Warning: Could not read option ID for column '$column_name' from board cache. Board add skipped." >&2 + return 0 + } + + if [[ -z "$option_id" || "$option_id" == "null" ]]; then + echo "[aod] Warning: No option ID found for stage '$stage' (column '$column_name'). Board add skipped." >&2 + return 0 + fi + + # --- Add issue to board --- + + local add_result item_add_stderr + item_add_stderr=$(mktemp 2>/dev/null || echo "/tmp/aod-add-stderr-$$") + add_result=$(gh project item-add "$project_number" --owner "$owner" --url "$issue_url" --format json 2>"$item_add_stderr") || { + local add_err + add_err=$(cat "$item_add_stderr" 2>/dev/null) + rm -f "$item_add_stderr" + if echo "$add_err" | grep -qiE 'rate.limit|abuse|secondary|retry.after|HTTP 403|API rate'; then + echo "[aod] Warning: GitHub API rate limit hit. Board add skipped — retry in a few minutes." >&2 + elif echo "$add_err" | grep -qiE 'Could not resolve|not found|404|project.*not.*found'; then + echo "[aod] Warning: Projects board not found (deleted?). Board cache cleared — run 'aod_gh_setup_board' to reconfigure." >&2 + rm -f "$AOD_BOARD_CACHE" + _AOD_BOARD_CHECKED=0 + else + echo "[aod] Warning: Failed to add issue to Projects board. Board add skipped." >&2 + fi + return 0 + } + rm -f "$item_add_stderr" + + local item_id + item_id=$(echo "$add_result" | jq -r '.id' 2>/dev/null) + + if [[ -z "$item_id" || "$item_id" == "null" ]]; then + echo "[aod] Warning: Could not parse item ID from board add response. Board status update skipped." >&2 + return 0 + fi + + # --- Set Status column --- + + local edit_stderr + edit_stderr=$(mktemp 2>/dev/null || echo "/tmp/aod-edit-stderr-$$") + gh project item-edit \ + --project-id "$project_id" \ + --id "$item_id" \ + --field-id "$status_field_id" \ + --single-select-option-id "$option_id" 2>"$edit_stderr" || { + local edit_err + edit_err=$(cat "$edit_stderr" 2>/dev/null) + rm -f "$edit_stderr" + if echo "$edit_err" | grep -qiE 'rate.limit|abuse|secondary|retry.after|HTTP 403|API rate'; then + echo "[aod] Warning: GitHub API rate limit hit. Board status update skipped — retry in a few minutes." >&2 + else + echo "[aod] Warning: Added issue to board but failed to set Status to '$column_name'. Continuing." >&2 + fi + echo "$item_id" + return 0 + } + rm -f "$edit_stderr" + + echo "[aod] Added issue to board and set Status to '$column_name'." >&2 + echo "$item_id" + + return 0 +} + +# Move an issue to a new Status column on the GitHub Projects board +# If the issue is not on the board, auto-adds it via aod_gh_add_to_board. +# Optimization: gh project item-add is idempotent — returns existing item +# without duplicating — so we skip the expensive item-list search. +# Args: +# $1 = issue_url (required, full GitHub issue URL) +# $2 = new_stage (required, one of: discover, define, plan, build, deliver) +# Returns: 0 always (graceful degradation) +# Stderr: warnings on any failure +aod_gh_move_on_board() { + local issue_url="${1:-}" + local new_stage="${2:-}" + + if [[ -z "$issue_url" || -z "$new_stage" ]]; then + echo "[aod] Warning: Missing issue_url or new_stage for board move. Skipping." >&2 + return 0 + fi + + # Check board availability (prereqs + cache); skip silently if unavailable + if ! aod_gh_check_board; then + return 0 + fi + + # --- Read cache values --- + + local project_number project_id owner status_field_id + + project_number=$(jq -r '.project_number' "$AOD_BOARD_CACHE" 2>/dev/null) || { + echo "[aod] Warning: Could not read project_number from board cache. Board move skipped." >&2 + return 0 + } + + project_id=$(jq -r '.project_id' "$AOD_BOARD_CACHE" 2>/dev/null) || { + echo "[aod] Warning: Could not read project_id from board cache. Board move skipped." >&2 + return 0 + } + + owner=$(jq -r '.owner' "$AOD_BOARD_CACHE" 2>/dev/null) || { + echo "[aod] Warning: Could not read owner from board cache. Board move skipped." >&2 + return 0 + } + + status_field_id=$(jq -r '.status_field_id' "$AOD_BOARD_CACHE" 2>/dev/null) || { + echo "[aod] Warning: Could not read status_field_id from board cache. Board move skipped." >&2 + return 0 + } + + # Defense-in-depth: verify cache values are non-empty before API calls + if [[ -z "$project_number" || "$project_number" == "null" || -z "$project_id" || "$project_id" == "null" || -z "$owner" || "$owner" == "null" || -z "$status_field_id" || "$status_field_id" == "null" ]]; then + echo "[aod] Warning: Board cache contains empty values. Board move skipped — run 'aod_gh_setup_board' to reconfigure." >&2 + return 0 + fi + + # --- Map new_stage to option ID --- + + local column_name="${AOD_STAGE_TO_COLUMN[$new_stage]:-}" + + if [[ -z "$column_name" ]]; then + echo "[aod] Warning: Unknown stage '$new_stage'. Valid stages: discover, define, plan, build, deliver. Board move skipped." >&2 + return 0 + fi + + local option_id + option_id=$(jq -r ".status_options.\"$column_name\"" "$AOD_BOARD_CACHE" 2>/dev/null) || { + echo "[aod] Warning: Could not read option ID for column '$column_name' from board cache. Board move skipped." >&2 + return 0 + } + + if [[ -z "$option_id" || "$option_id" == "null" ]]; then + echo "[aod] Warning: No option ID found for stage '$new_stage' (column '$column_name'). Board move skipped." >&2 + return 0 + fi + + # --- Add-or-find item on board (idempotent) --- + # gh project item-add is idempotent: if the issue is already on the board, + # it returns the existing item without creating a duplicate. This saves + # the expensive item-list search. + + local add_result move_add_stderr + move_add_stderr=$(mktemp 2>/dev/null || echo "/tmp/aod-move-stderr-$$") + add_result=$(gh project item-add "$project_number" --owner "$owner" --url "$issue_url" --format json 2>"$move_add_stderr") || { + local move_err + move_err=$(cat "$move_add_stderr" 2>/dev/null) + rm -f "$move_add_stderr" + if echo "$move_err" | grep -qiE 'rate.limit|abuse|secondary|retry.after|HTTP 403|API rate'; then + echo "[aod] Warning: GitHub API rate limit hit. Board move skipped — retry in a few minutes." >&2 + elif echo "$move_err" | grep -qiE 'Could not resolve|not found|404|project.*not.*found'; then + echo "[aod] Warning: Projects board not found (deleted?). Board cache cleared — run 'aod_gh_setup_board' to reconfigure." >&2 + rm -f "$AOD_BOARD_CACHE" + _AOD_BOARD_CHECKED=0 + else + echo "[aod] Warning: Failed to add/find issue on Projects board. Board move skipped." >&2 + fi + return 0 + } + rm -f "$move_add_stderr" + + local item_id + item_id=$(echo "$add_result" | jq -r '.id' 2>/dev/null) + + if [[ -z "$item_id" || "$item_id" == "null" ]]; then + echo "[aod] Warning: Could not parse item ID from board response. Board move skipped." >&2 + return 0 + fi + + # --- Update Status column --- + + local move_edit_stderr + move_edit_stderr=$(mktemp 2>/dev/null || echo "/tmp/aod-move-edit-stderr-$$") + gh project item-edit \ + --project-id "$project_id" \ + --id "$item_id" \ + --field-id "$status_field_id" \ + --single-select-option-id "$option_id" 2>"$move_edit_stderr" || { + local move_edit_err + move_edit_err=$(cat "$move_edit_stderr" 2>/dev/null) + rm -f "$move_edit_stderr" + if echo "$move_edit_err" | grep -qiE 'rate.limit|abuse|secondary|retry.after|HTTP 403|API rate'; then + echo "[aod] Warning: GitHub API rate limit hit. Board status update skipped — retry in a few minutes." >&2 + else + echo "[aod] Warning: Found issue on board but failed to update Status to '$column_name'. Continuing." >&2 + fi + return 0 + } + rm -f "$move_edit_stderr" + + echo "[aod] Moved issue to '$column_name' on board." >&2 + + return 0 +} + +# Check if gh CLI is available and authenticated with a remote +# Returns: 0 if available, 1 if not (with warning on stderr) +aod_gh_check_available() { + if ! command -v gh &>/dev/null; then + echo "[aod] Warning: gh CLI not found. GitHub operations skipped." >&2 + return 1 + fi + + if ! gh auth status &>/dev/null; then + echo "[aod] Warning: gh CLI not authenticated. Run 'gh auth login'. GitHub operations skipped." >&2 + return 1 + fi + + # Check if we have a remote configured + if ! git remote get-url origin &>/dev/null; then + echo "[aod] Warning: No git remote 'origin' configured. GitHub operations skipped." >&2 + return 1 + fi + + return 0 +} + +# Find an existing GitHub Issue by title match or [IDEA-NNN] tag +# Args: $1 = search query (title or IDEA-NNN tag) +# Returns: issue number on stdout, or empty string if not found +aod_gh_find_issue() { + local search_query="${1:-}" + + if [[ -z "$search_query" ]]; then + return 0 + fi + + # Search by exact title or IDEA tag in issue title + local result + result=$(gh issue list --search "\"$search_query\" in:title" --json number --limit 1 2>/dev/null) || return 0 + + # Extract issue number from JSON + local issue_number + issue_number=$(echo "$result" | grep -o '"number":[0-9]*' | head -1 | cut -d: -f2) + + if [[ -n "$issue_number" && "$issue_number" != "null" ]]; then + echo "$issue_number" + fi +} + +# Create a GitHub Issue with a stage:* label, or update if duplicate found +# Args: +# $1 = title (required) +# $2 = body (required, markdown) +# $3 = stage (required, one of: discover, define, plan, build, deliver) +# $4 = idea_id (optional, e.g., "IDEA-003" for duplicate detection) +# Returns: 0 always (graceful degradation), issue number on stdout if created +aod_gh_create_issue() { + local title="${1:-}" + local body="${2:-}" + local stage="${3:-discover}" + local idea_id="${4:-}" + + if [[ -z "$title" ]]; then + echo "[aod] Warning: No title provided for GitHub Issue. Skipping." >&2 + return 0 + fi + + if ! aod_gh_check_available; then + return 0 + fi + + local label="stage:${stage}" + + # Duplicate detection: check by IDEA-NNN tag first, then by title + local existing_number="" + if [[ -n "$idea_id" ]]; then + existing_number=$(aod_gh_find_issue "[$idea_id]") + fi + if [[ -z "$existing_number" ]]; then + existing_number=$(aod_gh_find_issue "$title") + fi + + if [[ -n "$existing_number" ]]; then + # Update existing issue instead of creating duplicate + echo "[aod] Found existing Issue #${existing_number} — updating instead of creating duplicate." >&2 + gh issue edit "$existing_number" --body "$body" --add-label "$label" 2>/dev/null || { + echo "[aod] Warning: Failed to update Issue #${existing_number}. Continuing." >&2 + } + # Remove old stage labels + for old_label in "${AOD_STAGE_LABELS[@]}"; do + if [[ "$old_label" != "$label" ]]; then + gh issue edit "$existing_number" --remove-label "$old_label" 2>/dev/null || true + fi + done + + # Sync to Projects board (non-blocking) + local existing_url + existing_url=$(gh issue view "$existing_number" --json url --jq '.url' 2>/dev/null) || true + if [[ -n "$existing_url" ]]; then + aod_gh_add_to_board "$existing_url" "$stage" >/dev/null 2>&1 || true + fi + + echo "$existing_number" + return 0 + fi + + # Create new issue + local issue_number + issue_number=$(gh issue create --title "$title" --body "$body" --label "$label" 2>/dev/null | grep -o '[0-9]*$') || { + echo "[aod] Warning: Failed to create GitHub Issue. Continuing without tracking." >&2 + return 0 + } + + if [[ -n "$issue_number" ]]; then + echo "[aod] Created Issue #${issue_number} with label ${label}." >&2 + + # Sync to Projects board (non-blocking) + local issue_url + issue_url=$(gh issue view "$issue_number" --json url --jq '.url' 2>/dev/null) || true + if [[ -n "$issue_url" ]]; then + aod_gh_add_to_board "$issue_url" "$stage" >/dev/null 2>&1 || true + fi + + echo "$issue_number" + fi + + return 0 +} + +# Update a GitHub Issue's stage label (remove old stage:* labels, add new one) +# Args: +# $1 = issue number (required) +# $2 = new stage (required, one of: discover, define, plan, build, deliver) +# Returns: 0 always (graceful degradation) +aod_gh_update_stage() { + local issue_number="${1:-}" + local new_stage="${2:-}" + + if [[ -z "$issue_number" || -z "$new_stage" ]]; then + echo "[aod] Warning: Missing issue number or stage for label update. Skipping." >&2 + return 0 + fi + + if ! aod_gh_check_available; then + return 0 + fi + + local new_label="stage:${new_stage}" + + # Remove all existing stage:* labels, then add the new one + for old_label in "${AOD_STAGE_LABELS[@]}"; do + if [[ "$old_label" != "$new_label" ]]; then + gh issue edit "$issue_number" --remove-label "$old_label" 2>/dev/null || true + fi + done + + gh issue edit "$issue_number" --add-label "$new_label" 2>/dev/null || { + echo "[aod] Warning: Failed to update stage label on Issue #${issue_number}. Continuing." >&2 + } + + # Sync to Projects board (non-blocking) + local issue_url + issue_url=$(gh issue view "$issue_number" --json url --jq '.url' 2>/dev/null) || true + if [[ -n "$issue_url" ]]; then + aod_gh_move_on_board "$issue_url" "$new_stage" >/dev/null 2>&1 || true + fi + + return 0 +} diff --git a/.aod/scripts/bash/migrate-backlog.sh b/.aod/scripts/bash/migrate-backlog.sh new file mode 100755 index 0000000..d4cc8cd --- /dev/null +++ b/.aod/scripts/bash/migrate-backlog.sh @@ -0,0 +1,155 @@ +#!/usr/bin/env bash + +# Migrate existing backlog items from 01_IDEAS.md and 02_USER_STORIES.md +# to GitHub Issues with appropriate stage:* labels. +# +# Usage: ./migrate-backlog.sh [--dry-run] +# +# Options: +# --dry-run Show what would be created without actually creating Issues +# +# Migration logic: +# - Delivered items → stage:deliver +# - "In PRD" items → stage:define +# - "Validated" / "Ready for PRD" items → stage:discover +# - "Scoring" / "Deferred" items → stage:discover +# +# After migration, archives old files to docs/product/_backlog/archive/ + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/common.sh" +source "$SCRIPT_DIR/github-lifecycle.sh" + +DRY_RUN=false +for arg in "$@"; do + case "$arg" in + --dry-run) DRY_RUN=true ;; + esac +done + +REPO_ROOT=$(get_repo_root) +IDEAS_FILE="$REPO_ROOT/docs/product/_backlog/01_IDEAS.md" +STORIES_FILE="$REPO_ROOT/docs/product/_backlog/02_USER_STORIES.md" +ARCHIVE_DIR="$REPO_ROOT/docs/product/_backlog/archive" + +# Check prerequisites +if ! aod_gh_check_available; then + echo "[aod] Cannot migrate backlog without GitHub access." >&2 + exit 1 +fi + +if [[ ! -f "$IDEAS_FILE" ]]; then + echo "[aod] No 01_IDEAS.md found — nothing to migrate." >&2 + exit 0 +fi + +# Ensure archive directory exists +mkdir -p "$ARCHIVE_DIR" + +echo "[aod] Starting backlog migration..." +echo "" + +# Parse IDEAS table and create GitHub Issues +# Skip header rows (lines starting with | ID or |---|) +MIGRATED=0 +SKIPPED=0 + +while IFS='|' read -r _ id idea source date status ice_score _; do + # Trim whitespace + id=$(echo "$id" | xargs) + idea=$(echo "$idea" | xargs) + source=$(echo "$source" | xargs) + date=$(echo "$date" | xargs) + status=$(echo "$status" | xargs) + ice_score=$(echo "$ice_score" | xargs) + + # Skip non-data rows + if [[ -z "$id" || "$id" == "ID" || "$id" == "----" || "$id" =~ ^-+$ ]]; then + continue + fi + + # Determine stage from status + local_stage="discover" + case "$status" in + Delivered|delivered) + local_stage="deliver" + ;; + "In PRD"|"in prd"|"In Define") + local_stage="define" + ;; + "In Plan"|"Planning") + local_stage="plan" + ;; + "In Build"|"Building"|"In Progress") + local_stage="build" + ;; + *) + local_stage="discover" + ;; + esac + + # Build issue body + body="# [$id] $idea + +## ICE Score +$ice_score + +## Evidence +Migrated from legacy backlog — no evidence captured at original time. + +## Metadata +- Source: $source +- Date: $date +- Original Status: $status +- Migrated: $(date +%Y-%m-%d)" + + title="[$id] $idea" + # Truncate title to 256 chars (GitHub limit) + if [[ ${#title} -gt 256 ]]; then + title="${title:0:253}..." + fi + + if $DRY_RUN; then + echo "[dry-run] Would create Issue: $id → stage:$local_stage" + echo " Title: ${title:0:80}..." + else + result=$(aod_gh_create_issue "$title" "$body" "$local_stage" "$id") + if [[ -n "$result" ]]; then + echo "[aod] Migrated $id → Issue #$result (stage:$local_stage)" + ((MIGRATED++)) + else + echo "[aod] Warning: Failed to migrate $id" + ((SKIPPED++)) + fi + fi +done < <(tail -n +3 "$IDEAS_FILE") # Skip header and separator rows + +echo "" +echo "[aod] Migration complete: $MIGRATED migrated, $SKIPPED skipped" + +# Archive old files (T065) +if ! $DRY_RUN && [[ $MIGRATED -gt 0 ]]; then + echo "" + echo "[aod] Archiving old backlog files..." + + if [[ -f "$IDEAS_FILE" ]]; then + cp "$IDEAS_FILE" "$ARCHIVE_DIR/01_IDEAS.md" + echo "[aod] Archived 01_IDEAS.md → archive/01_IDEAS.md" + fi + + if [[ -f "$STORIES_FILE" ]]; then + cp "$STORIES_FILE" "$ARCHIVE_DIR/02_USER_STORIES.md" + echo "[aod] Archived 02_USER_STORIES.md → archive/02_USER_STORIES.md" + fi + + echo "[aod] Note: Original files preserved. Use 'git mv' to move them if desired." +fi + +# Regenerate BACKLOG.md +if ! $DRY_RUN; then + echo "" + echo "[aod] Regenerating BACKLOG.md..." + "$SCRIPT_DIR/backlog-regenerate.sh" || echo "[aod] Warning: BACKLOG.md regeneration failed." +fi diff --git a/.aod/templates/checklist-template.md b/.aod/templates/checklist-template.md index 3563e74..d7f70b4 100644 --- a/.aod/templates/checklist-template.md +++ b/.aod/templates/checklist-template.md @@ -4,13 +4,13 @@ **Created**: [DATE] **Feature**: [Link to spec.md or relevant documentation] -**Note**: This checklist is generated by the `/triad.checklist` command based on feature context and requirements. +**Note**: This checklist is generated by the `/aod.checklist` command based on feature context and requirements. must exist 5. If validation fails: Show error with required workflow order and exit +6. Detect resume state: Scan tasks.md for `[X]` marked tasks. Count completed vs total tasks per wave from agent-assignments.md. + - If resuming (some waves complete): Display "RESUMING: Waves 1-N complete, starting at Wave {N+1}" + - If fresh start: Display "Starting implementation from Wave 1" +7. **GitHub Lifecycle Update (early)**: If a GitHub Issue exists for this feature, update its stage label to `stage:build` using `aod_gh_update_stage` from `.aod/scripts/bash/github-lifecycle.sh`. This moves the issue to the Build column on the Projects board at the *start* of implementation, reflecting current work status. Run `.aod/scripts/bash/backlog-regenerate.sh` to refresh BACKLOG.md. If `gh` is unavailable, skip silently (graceful degradation). ## Step 2: Check Checklists and Load Context @@ -124,6 +128,27 @@ For each wave: - If BLOCKED on blocking checkpoint: spawn debugger, retry, or exit - If CHANGES_REQUESTED: spawn appropriate agent to fix, retry review +6. **STOP after wave** (MANDATORY — context overflow prevention): + - Run `/continue` to generate a NEXT-SESSION.md handoff file + - Display wave completion summary: + ``` + WAVE {N}/{total} COMPLETE + + Tasks completed this wave: {count} + Total progress: {completed}/{total} tasks ({percentage}%) + + Next: Wave {N+1} — {brief description from agent-assignments.md} + + To continue: Start a new conversation and run `/aod.build` + The command will automatically resume from Wave {N+1}. + + Resume prompt: + claude "Resume {feature} implementation (branch: {branch}). Waves 1-{N} complete. Run /aod.build to continue with Wave {N+1}." + ``` + - **STOP EXECUTION. Do not proceed to the next wave.** + - This is MANDATORY — never continue to the next wave in the same conversation. + - Exception: If this is the LAST wave, proceed to Step 5 (Final Validation) instead of stopping. + ### Implementation Execution Rules During wave execution, agents must follow these rules: @@ -145,7 +170,9 @@ During wave execution, agents must follow these rules: - Suggest next steps if implementation cannot proceed - **IMPORTANT**: For completed tasks, mark the task as `[X]` in tasks.md -## Step 5: Final Validation +## Step 5: Final Validation (Last Wave Only) + +This step runs ONLY after the LAST wave completes (i.e., all tasks in all waves are marked `[X]`). For non-final waves, Step 4.6 stops execution instead. After all waves complete: @@ -199,6 +226,7 @@ Next: Create PR, deploy to staging, run acceptance tests - [ ] Project setup verified (ignore files for detected technologies) - [ ] Agent-assignments.md parsed for task->agent mapping - [ ] Waves executed with parallel agent spawning +- [ ] Execution stopped after each wave with resume instructions (context overflow prevention) - [ ] TDD approach followed (tests before implementation) - [ ] Architect checkpoint reviews at P0, P1, P2 boundaries - [ ] Blocking checkpoint issues resolved before proceeding @@ -206,4 +234,4 @@ Next: Create PR, deploy to staging, run acceptance tests - [ ] All tasks marked [X] in tasks.md - [ ] Implementation summary displayed -Note: This command requires a complete task breakdown in tasks.md with Triad sign-offs. If tasks are incomplete or missing, run `/triad.tasks` first to generate the task list with governance approval. +Note: This command requires a complete task breakdown in tasks.md with Triad sign-offs. If tasks are incomplete or missing, run `/aod.tasks` first to generate the task list with governance approval. diff --git a/.claude/commands/triad.checklist.md b/.claude/commands/aod.checklist.md similarity index 98% rename from .claude/commands/triad.checklist.md rename to .claude/commands/aod.checklist.md index 135ed40..fb87f44 100644 --- a/.claude/commands/triad.checklist.md +++ b/.claude/commands/aod.checklist.md @@ -91,7 +91,7 @@ You **MUST** consider the user input before proceeding (if not empty). - Format: `[domain].md` - If file exists, append to existing file - Number items sequentially starting from CHK001 - - Each `/triad.checklist` run creates a NEW file (never overwrites existing checklists) + - Each `/aod.checklist` run creates a NEW file (never overwrites existing checklists) **CORE PRINCIPLE - Test the Requirements, Not the Implementation**: Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for: @@ -209,7 +209,7 @@ You **MUST** consider the user input before proceeding (if not empty). - Actor/timing - Any explicit user-specified must-have items incorporated -**Important**: Each `/triad.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows: +**Important**: Each `/aod.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows: - Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`) - Simple, memorable filenames that indicate checklist purpose diff --git a/.claude/commands/triad.clarify.md b/.claude/commands/aod.clarify.md similarity index 96% rename from .claude/commands/triad.clarify.md rename to .claude/commands/aod.clarify.md index ba095c8..5942a2a 100644 --- a/.claude/commands/triad.clarify.md +++ b/.claude/commands/aod.clarify.md @@ -14,7 +14,7 @@ You **MUST** consider the user input before proceeding (if not empty). Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file. -Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/triad.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. +Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/aod.project-plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. Execution steps: @@ -22,7 +22,7 @@ Execution steps: - `FEATURE_DIR` - `FEATURE_SPEC` - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) - - If JSON parsing fails, abort and instruct user to re-run `/triad.specify` or verify feature branch environment. + - If JSON parsing fails, abort and instruct user to re-run `/aod.spec` or verify feature branch environment. - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). 2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked). @@ -161,12 +161,12 @@ Execution steps: - Path to updated spec. - Sections touched (list names). - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact). - - If any Outstanding or Deferred remain, recommend whether to proceed to `/triad.plan` or run `/triad.clarify` again later post-plan. + - If any Outstanding or Deferred remain, recommend whether to proceed to `/aod.project-plan` or run `/aod.clarify` again later post-plan. - Suggested next command. Behavior rules: - If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding. -- If spec file missing, instruct user to run `/triad.specify` first (do not create a new spec here). +- If spec file missing, instruct user to run `/aod.spec` first (do not create a new spec here). - Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions). - Avoid speculative tech stack questions unless the absence blocks functional clarity. - Respect user early termination signals ("stop", "done", "proceed"). diff --git a/.claude/commands/triad.constitution.md b/.claude/commands/aod.constitution.md similarity index 100% rename from .claude/commands/triad.constitution.md rename to .claude/commands/aod.constitution.md diff --git a/.claude/commands/triad.prd.md b/.claude/commands/aod.define.md similarity index 88% rename from .claude/commands/triad.prd.md rename to .claude/commands/aod.define.md index 99731d0..cd89e27 100644 --- a/.claude/commands/triad.prd.md +++ b/.claude/commands/aod.define.md @@ -12,7 +12,7 @@ Consider user input before proceeding (if not empty). ## Overview -Wraps prd-create skill with automatic Triad triple sign-off. +Wraps aod-define skill with automatic Triad triple sign-off. **Flow**: Check vision docs → Validate topic → Classify type → Draft PRD → Reviews → Handle blockers → Inject frontmatter → Update INDEX @@ -52,9 +52,10 @@ Q3: What are the 2-3 core features? ## Step 1: Validate Topic 1. Parse topic from `$ARGUMENTS` (kebab-case format) -2. If empty: Error "Usage: /triad.prd " and exit +2. If empty: Error "Usage: /aod.define " and exit 3. Check `docs/product/02_PRD/` for existing PRD with same topic 4. If exists: Use AskUserQuestion with options: View existing, Create with suffix (v2), Abort +5. **GitHub Lifecycle Update (early)**: If the idea originated from a GitHub Issue (check `02_USER_STORIES.md` for IDEA-NNN source), update the Issue's stage label to `stage:define` using `aod_gh_update_stage` from `.aod/scripts/bash/github-lifecycle.sh`. This moves the issue to the Define column on the Projects board at the *start* of PRD creation. Run `.aod/scripts/bash/backlog-regenerate.sh` to refresh BACKLOG.md. If `gh` is unavailable, skip silently (graceful degradation). ## Step 2: Classify PRD Type @@ -69,12 +70,12 @@ Use AskUserQuestion to determine workflow type: **Infrastructure workflow**: 1. Launch architect agent for baseline technical assessment -2. Invoke prd-create skill with architect baseline context +2. Invoke aod-define skill with architect baseline context 3. Launch team-lead agent for timeline/feasibility review 4. Launch architect agent for final technical review **Feature workflow**: -1. Invoke prd-create skill directly +1. Invoke aod-define skill directly 2. Launch **two Task agents in parallel** (single message, two Task tool calls): | Agent | subagent_type | Focus | Key Criteria | @@ -174,14 +175,14 @@ Triple Sign-offs: - Architect: {architect_status} - Team-Lead: {techlead_status} -Next: /triad.specify +Next: /aod.spec ``` -## Quality Checklist +## Step 10: Quality Checklist - [ ] Topic validated (no duplicates or user-approved suffix) - [ ] Workflow type classified (infrastructure or feature) -- [ ] PRD drafted via prd-create skill +- [ ] PRD drafted via aod-define skill - [ ] Reviews executed (sequential for infra, parallel for feature) - [ ] Blockers handled (resolved, overridden, or aborted) - [ ] PRD number assigned sequentially diff --git a/.claude/commands/triad.close-feature.md b/.claude/commands/aod.deliver.md similarity index 78% rename from .claude/commands/triad.close-feature.md rename to .claude/commands/aod.deliver.md index 86d4aaf..514a2be 100644 --- a/.claude/commands/triad.close-feature.md +++ b/.claude/commands/aod.deliver.md @@ -62,17 +62,27 @@ Output: List files updated with brief summary. | Scenario | Action | |----------|--------| -| All succeed | Proceed to Step 5 | +| All succeed | Proceed to Step 5 (Retrospective) | | Partial failure | Prompt: (A) Retry failed, (B) Proceed anyway, (C) Abort | | All fail | Abort and report errors | -## Step 5: Cleanup Tasks +## Step 5: Structured Retrospective + +Run the `aod-deliver` skill's retrospective flow (Steps 2-8 from `.claude/skills/aod-deliver/SKILL.md`): + +1. **Delivery Metrics**: Capture estimated vs. actual duration (actual computed from branch creation date) +2. **Surprise Log**: Prompt for "what surprised us" (1 sentence minimum, required) +3. **Feedback Loop**: Prompt for new ideas — each creates a GitHub Issue with `stage:discover` label and source "Retrospective" +4. **Lessons Learned**: Capture key lesson with category, append KB entry to `docs/INSTITUTIONAL_KNOWLEDGE.md` +5. **GitHub Update**: Post delivery metrics as comment on feature's GitHub Issue, transition to `stage:deliver` +6. **BACKLOG.md**: Regenerate via `.aod/scripts/bash/backlog-regenerate.sh` + +## Step 6: Cleanup Tasks 1. **Delete feature branch** (local and remote, ignore if already deleted) -2. **Prompt for learnings**: Ask if any insights for INSTITUTIONAL_KNOWLEDGE.md (allow "skip") -3. **Validate**: Check `git status`, search for TBD/TODO in docs/ +2. **Validate**: Check `git status`, search for TBD/TODO in docs/ -## Step 6: Upstream Sync to AOD-kit +## Step 7: Upstream Sync to AOD-kit Prompt the user to sync deliverable files to the published template repo (`agentic-oriented-development-kit`). @@ -85,7 +95,7 @@ Prompt the user to sync deliverable files to the published template repo (`agent **Sync direction is always**: `product-led-spec-kit → agentic-oriented-development-kit` -## Step 7: Commit and Push +## Step 8: Commit and Push Stage `docs/`, `deployment/`, `CLAUDE.md` and commit: @@ -102,7 +112,7 @@ Co-Authored-By: Claude Then `git push origin main`. -## Step 8: Generate Closure Report +## Step 9: Generate Closure Report ```markdown ## ✅ Feature {NUMBER} Closure Complete @@ -119,6 +129,13 @@ Then `git push origin main`. | Architecture | architect | {n} | ✅ | | DevOps | devops | {n} | ✅ | +### Retrospective +- Estimated: {estimated_duration} +- Actual: {actual_duration} +- Surprise: {surprise_log} +- Lessons: Entry {N} in INSTITUTIONAL_KNOWLEDGE.md +- New Ideas: {count or "None"} + ### Cleanup - [x] Feature branch deleted - [x] All tasks complete diff --git a/.claude/commands/pdl.idea.md b/.claude/commands/aod.discover.md similarity index 93% rename from .claude/commands/pdl.idea.md rename to .claude/commands/aod.discover.md index aa22fb1..4930968 100644 --- a/.claude/commands/pdl.idea.md +++ b/.claude/commands/aod.discover.md @@ -23,7 +23,7 @@ Captures a raw feature idea, scores it with ICE (Impact, Confidence, Effort), an ## Step 2: Execute Idea Capture -Follow the workflow defined in the pdl-idea skill (`.claude/skills/pdl-idea/SKILL.md`): +Follow the workflow defined in the aod-discover skill (`.claude/skills/aod-discover/SKILL.md`): 1. Auto-create backlog files if missing (FR-7) 2. Generate IDEA-NNN ID (read table, find highest, increment) diff --git a/.claude/commands/aod.plan.md b/.claude/commands/aod.plan.md new file mode 100644 index 0000000..bc2f645 --- /dev/null +++ b/.claude/commands/aod.plan.md @@ -0,0 +1,27 @@ +--- +description: Auto-detect Plan stage progress and route to the correct sub-step (spec → project-plan → tasks) +--- + +## User Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Overview + +Routes to the correct Plan sub-step by reading artifact frontmatter. No governance gates on the router itself — governance is handled by the sub-commands it invokes. + +**Flow**: Detect branch → Read artifact states → Apply decision table → Invoke sub-command or report completion + +## Execution + +Invoke the `aod-plan` skill to perform routing logic. Pass any user arguments through to the selected sub-command. + +The skill will: +1. Determine the current feature from the git branch +2. Check spec.md, plan.md, and tasks.md for existence and approval status +3. Route to `/aod.spec`, `/aod.project-plan`, or `/aod.tasks` as appropriate +4. Report "Plan stage complete" if all artifacts are approved diff --git a/.claude/commands/triad.plan.md b/.claude/commands/aod.project-plan.md similarity index 94% rename from .claude/commands/triad.plan.md rename to .claude/commands/aod.project-plan.md index f5564ff..05524de 100644 --- a/.claude/commands/triad.plan.md +++ b/.claude/commands/aod.project-plan.md @@ -150,11 +150,18 @@ triad: date: {YYYY-MM-DD} status: {architect_status} notes: "{architect_notes}" - techlead_signoff: null # Added by /triad.tasks + techlead_signoff: null # Added by /aod.tasks --- ``` -## Step 6: Report Completion +## Step 6: GitHub Lifecycle Update + +After plan creation, regenerate BACKLOG.md to reflect current state: + +1. Run `.aod/scripts/bash/backlog-regenerate.sh` to refresh BACKLOG.md +2. If `gh` is unavailable, skip silently (graceful degradation) + +## Step 7: Report Completion Display summary including branch, IMPL_PLAN path, and generated artifacts: ``` @@ -169,7 +176,7 @@ Dual Sign-offs: - PM: {pm_status} - Architect: {architect_status} -Next: /triad.tasks +Next: /aod.tasks ``` ## Key Rules diff --git a/.claude/commands/pdl.score.md b/.claude/commands/aod.score.md similarity index 90% rename from .claude/commands/pdl.score.md rename to .claude/commands/aod.score.md index 9f6a7b3..90fb98f 100644 --- a/.claude/commands/pdl.score.md +++ b/.claude/commands/aod.score.md @@ -20,11 +20,11 @@ Updates an existing idea's ICE score in the Ideas Backlog when circumstances cha 1. Parse IDEA-NNN identifier from `$ARGUMENTS` 2. Validate format: Must match `IDEA-` followed by a 3-digit number (e.g., `IDEA-001`) -3. If invalid or missing: Display usage `Usage: /pdl.score IDEA-NNN` +3. If invalid or missing: Display usage `Usage: /aod.score IDEA-NNN` ## Step 2: Execute Re-Scoring -Follow the workflow defined in the pdl-score skill (`.claude/skills/pdl-score/SKILL.md`): +Follow the workflow defined in the aod-score skill (`.claude/skills/aod-score/SKILL.md`): 1. Auto-create backlog files if missing (FR-7) 2. Read `docs/product/_backlog/01_IDEAS.md` and find the matching row diff --git a/.claude/commands/triad.specify.md b/.claude/commands/aod.spec.md similarity index 92% rename from .claude/commands/triad.specify.md rename to .claude/commands/aod.spec.md index 79bd245..c405f68 100644 --- a/.claude/commands/triad.specify.md +++ b/.claude/commands/aod.spec.md @@ -22,6 +22,7 @@ Creates a feature specification with automatic PM sign-off (Constitution Princip 2. Find PRD: `docs/product/02_PRD/{NNN}-*.md` → must exist 3. Parse frontmatter: Verify all Triad sign-offs are APPROVED (or APPROVED_WITH_CONCERNS/BLOCKED_OVERRIDDEN) 4. If validation fails: Show error with required workflow order and exit +5. **GitHub Lifecycle Update (early)**: If a GitHub Issue exists for this feature, update its stage label to `stage:plan` using `aod_gh_update_stage` from `.aod/scripts/bash/github-lifecycle.sh`. This moves the issue to the Plan column on the Projects board at the *start* of specification work. Run `.aod/scripts/bash/backlog-regenerate.sh` to refresh BACKLOG.md. If `gh` is unavailable, skip silently (graceful degradation). ## Step 2: Research Phase @@ -102,7 +103,7 @@ The text the user typed after the command **is** the feature description. Do not ``` ⚠️ Warning: No approved PRD found for this feature. Per Constitution v1.4.0: "No spec.md without an approved PRD" - Recommended: Create PRD first with /triad.prd + Recommended: Create PRD first with /aod.define Continue without PRD? (y/n) ``` @@ -177,7 +178,7 @@ a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/ - [ ] No implementation details leak into specification ## Notes - - Items marked incomplete require spec updates before `/triad.clarify` or `/triad.plan` + - Items marked incomplete require spec updates before `/aod.clarify` or `/aod.project-plan` ``` b. **Run Validation Check**: Review the spec against each checklist item @@ -236,13 +237,13 @@ NOTES: [Your detailed feedback] **CHANGES_REQUESTED**: 1. Display PM feedback -2. Notify: "Update spec.md and re-run /triad.specify" +2. Notify: "Update spec.md and re-run /aod.spec" 3. Still inject frontmatter with CHANGES_REQUESTED status **BLOCKED**: 1. Display blocker with veto domain (PM=product scope) 2. Use AskUserQuestion with options: - - **Resolve**: Address issues and re-run /triad.specify + - **Resolve**: Address issues and re-run /aod.spec - **Override**: Provide justification (min 20 chars), mark as BLOCKED_OVERRIDDEN - **Abort**: Exit workflow @@ -259,8 +260,8 @@ triad: date: {YYYY-MM-DD} status: {pm_status} notes: "{pm_notes}" - architect_signoff: null # Added by /triad.plan - techlead_signoff: null # Added by /triad.tasks + architect_signoff: null # Added by /aod.project-plan + techlead_signoff: null # Added by /aod.tasks --- ``` @@ -268,7 +269,7 @@ triad: Display summary: ``` -✅ SPECIFICATION CREATION COMPLETE +SPECIFICATION CREATION COMPLETE Feature: {feature_number} PRD: {prd_path} @@ -276,7 +277,7 @@ Spec: {spec_path} PM Sign-off: {pm_status} -Next: /triad.plan +Next: /aod.project-plan ``` ## Quality Checklist diff --git a/.claude/commands/aod.status.md b/.claude/commands/aod.status.md new file mode 100644 index 0000000..010a4af --- /dev/null +++ b/.claude/commands/aod.status.md @@ -0,0 +1,25 @@ +--- +description: View lifecycle stage summary and regenerate BACKLOG.md from GitHub Issues +--- + +## Overview + +On-demand backlog snapshot and lifecycle stage summary. Regenerates BACKLOG.md from GitHub Issues and displays item counts per lifecycle stage. + +**No governance gates** — this is a read-only utility command. + +## Execute + +Follow the workflow defined in the aod-status skill (`.claude/skills/aod-status/SKILL.md`): + +1. Run `.aod/scripts/bash/backlog-regenerate.sh --json` to regenerate BACKLOG.md +2. Parse output to count items per stage (Discover, Define, Plan, Build, Deliver, Untracked) +3. Display formatted stage summary table with totals +4. If on a feature branch, show active feature artifact approval status + +## Quality Checklist + +- [ ] BACKLOG.md regenerated (or fallback used if gh unavailable) +- [ ] Stage counts displayed in table format +- [ ] Total count matches sum of stages +- [ ] Active feature context shown if on feature branch diff --git a/.claude/commands/triad.tasks.md b/.claude/commands/aod.tasks.md similarity index 99% rename from .claude/commands/triad.tasks.md rename to .claude/commands/aod.tasks.md index 2f08d34..f39a1ca 100644 --- a/.claude/commands/triad.tasks.md +++ b/.claude/commands/aod.tasks.md @@ -248,7 +248,7 @@ Triple Sign-offs: - Architect: {architect_status} - Team-Lead: {techlead_status} -Next: /triad.implement +Next: /aod.build ``` ## Quality Checklist diff --git a/.claude/commands/continue.md b/.claude/commands/continue.md index 5918ada..cf07384 100644 --- a/.claude/commands/continue.md +++ b/.claude/commands/continue.md @@ -29,9 +29,9 @@ If on feature branch, also check: | Files Present | Phase | Next Action | |---------------|-------|-------------| -| No spec.md | specify | Run /triad.specify | -| No plan.md | plan | Run /triad.plan | -| No tasks.md | tasks | Run /triad.tasks | +| No spec.md | specify | Run /aod.spec | +| No plan.md | plan | Run /aod.project-plan | +| No tasks.md | tasks | Run /aod.tasks | | All present | implement | Next pending task from tasks.md | ## Output Template diff --git a/.claude/commands/execute.md b/.claude/commands/execute.md index aeca02e..4963bf1 100644 --- a/.claude/commands/execute.md +++ b/.claude/commands/execute.md @@ -88,6 +88,6 @@ Report completed tasks, files modified, wave timings, and any issues. ## Notes - Use `/execute` for quick, ad-hoc work (< 1 day effort) -- Use `/triad.*` workflow for larger features requiring governance +- Use `/aod.*` workflow for larger features requiring governance - Architect review is automatic for any code changes - Failed tasks don't halt execution - summary reports all outcomes diff --git a/.claude/commands/pdl.run.md b/.claude/commands/pdl.run.md deleted file mode 100644 index 31cd6f3..0000000 --- a/.claude/commands/pdl.run.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -description: "Full product discovery flow: capture, score, validate, and add to backlog in one step" ---- - -## User Input - -```text -$ARGUMENTS -``` - -Consider user input before proceeding (if not empty). - -## Overview - -Executes the complete Product Discovery Lifecycle in a single flow: captures an idea, scores it with ICE, validates with PM, and adds a user story to the product backlog. - -**Flow**: Parse idea → Auto-create backlog files → Capture + Score → Auto-defer gate → PM validation → User story generation → Report - -## Step 1: Validate Input - -1. Parse idea description from `$ARGUMENTS` -2. If empty: Ask the user to describe their idea before proceeding - -## Step 2: Execute Full Discovery Flow - -Follow the workflow defined in the pdl-run skill (`.claude/skills/pdl-run/SKILL.md`): - -1. Auto-create backlog files if missing (FR-7) -2. **Capture**: Generate IDEA-NNN ID, capture source, run ICE scoring (all inline) -3. **Auto-Defer Gate**: If score < 12, set status to "Deferred", report result, and **STOP**. Guide user to `/pdl.validate IDEA-NNN` for PM override. -4. **PM Validation**: If score >= 12, launch PM review via Task tool with product-manager subagent (inline) -5. **If Rejected**: Update status to "Rejected", report result, and stop -6. **If Approved**: - a. Generate user story, present for confirmation - b. Generate US-NNN ID, determine priority - c. Append to `docs/product/_backlog/02_USER_STORIES.md` - d. Update idea status to "Validated" in 01_IDEAS.md -7. Report complete flow summary: IDEA-NNN, ICE score, PM result, US-NNN (if approved), next step `/triad.prd` - -## Quality Checklist - -- [ ] Idea description captured from user -- [ ] IDEA-NNN ID generated and source captured -- [ ] ICE score computed and auto-defer gate applied -- [ ] Auto-deferred ideas stop flow with guidance -- [ ] PM validation invoked for qualifying ideas -- [ ] User story generated and confirmed (if approved) -- [ ] Both backlog files updated correctly -- [ ] Complete flow summary displayed diff --git a/.claude/commands/pdl.validate.md b/.claude/commands/pdl.validate.md deleted file mode 100644 index 4be4acb..0000000 --- a/.claude/commands/pdl.validate.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -description: PM validation gate for ideas with user story generation ---- - -## User Input - -```text -$ARGUMENTS -``` - -Consider user input before proceeding (if not empty). - -## Overview - -Submits an idea to the Product Manager agent for validation. On approval, generates a user story and adds it to the product backlog. On rejection, updates the idea status. - -**Flow**: Parse IDEA-NNN → Find idea → Launch PM review → Handle result → Generate user story (if approved) → Update backlogs → Report - -## Step 1: Validate Input - -1. Parse IDEA-NNN identifier from `$ARGUMENTS` -2. Validate format: Must match `IDEA-` followed by a 3-digit number (e.g., `IDEA-001`) -3. If invalid or missing: Display usage `Usage: /pdl.validate IDEA-NNN` - -## Step 2: Execute Validation - -Follow the workflow defined in the pdl-validate skill (`.claude/skills/pdl-validate/SKILL.md`): - -1. Auto-create backlog files if missing (FR-7) -2. Read `docs/product/_backlog/01_IDEAS.md` and find the matching row -3. Verify idea is eligible (not already Rejected or Validated) -4. Launch PM validation via Task tool with product-manager subagent -5. **If Rejected**: Update status to "Rejected" in 01_IDEAS.md, display rationale -6. **If Approved**: - a. Generate user story in "As a [persona], I want [action], so that [benefit]" format - b. Present for user confirmation (accept or edit) - c. Generate US-NNN ID and determine priority - d. Append to `docs/product/_backlog/02_USER_STORIES.md` - e. Update idea status to "Validated" in 01_IDEAS.md - f. Document PM override rationale if idea was auto-deferred -7. Report result with next step guidance (`/triad.prd`) - -## Quality Checklist - -- [ ] IDEA-NNN format validated -- [ ] Idea found and eligible for validation -- [ ] PM agent invoked with idea details -- [ ] Rejection or approval handled correctly -- [ ] User story generated and confirmed (if approved) -- [ ] Both backlog files updated correctly -- [ ] Result reported with next step diff --git a/.claude/rules/commands.md b/.claude/rules/commands.md index 7364739..b3be444 100644 --- a/.claude/rules/commands.md +++ b/.claude/rules/commands.md @@ -16,21 +16,21 @@ Use Triad commands for governance, quality gates, and multi-agent collaboration. ### SDLC Workflow Commands ```bash -/triad.prd # Create PRD with Triad validation (includes optional vision workshop) -/triad.specify # Create spec.md with auto PM sign-off -/triad.plan # Create plan.md with auto PM + Architect sign-off -/triad.tasks # Create tasks.md with auto triple sign-off -/triad.implement # Execute with auto architect checkpoints -/triad.close-feature {NNN} # Close feature with parallel doc updates +/aod.define # Create PRD with Triad validation (includes optional vision workshop) +/aod.spec # Create spec.md with auto PM sign-off +/aod.project-plan # Create plan.md with auto PM + Architect sign-off +/aod.tasks # Create tasks.md with auto triple sign-off +/aod.build # Execute with auto architect checkpoints +/aod.deliver {NNN} # Close feature with parallel doc updates ``` ### Utility Commands ```bash -/triad.clarify # Ask clarification questions about current feature -/triad.analyze # Verify spec/plan/task consistency -/triad.checklist # Run Definition of Done checklist -/triad.constitution # View or update governance constitution +/aod.clarify # Ask clarification questions about current feature +/aod.analyze # Verify spec/plan/task consistency +/aod.checklist # Run Definition of Done checklist +/aod.constitution # View or update governance constitution ``` **When to Use**: @@ -44,13 +44,13 @@ Use Triad commands for governance, quality gates, and multi-agent collaboration. ## PDL Commands (Optional Discovery) -Use PDL commands for lightweight product discovery before the Triad workflow. PDL is optional — you can start directly at `/triad.prd` if you prefer. +Use PDL commands for lightweight product discovery before the Triad workflow. PDL is optional — you can start directly at `/aod.define` if you prefer. ```bash -/pdl.run # Full discovery flow: capture → score → validate → backlog -/pdl.idea # Capture idea + ICE scoring -/pdl.score IDEA-NNN # Re-score an existing idea -/pdl.validate IDEA-NNN # PM validation gate + user story generation +/aod.discover # Full discovery flow: capture → score → validate → backlog +/aod.discover # Capture idea + ICE scoring +/aod.score IDEA-NNN # Re-score an existing idea +/aod.validate IDEA-NNN # PM validation gate + user story generation ``` **When to Use**: diff --git a/.claude/rules/governance.md b/.claude/rules/governance.md index 186d1d2..3a3923c 100644 --- a/.claude/rules/governance.md +++ b/.claude/rules/governance.md @@ -19,7 +19,7 @@ This file defines mandatory governance workflows for Agentic Oriented Developmen | plan.md | PM + Architect | product-manager, architect | | tasks.md | PM + Architect + Team-Lead | product-manager, architect, team-lead | -### Before `/triad.specify` (Research Phase): +### Before `/aod.spec` (Research Phase): A **mandatory research phase** runs before spec generation: @@ -32,20 +32,20 @@ A **mandatory research phase** runs before spec generation: **Purpose**: Ground specifications in codebase reality and industry best practices, avoiding reinvention and ensuring alignment with existing patterns. -### After `/triad.specify` Completes: +### After `/aod.spec` Completes: 1. **Automatically** invoke product-manager agent for PM review using Task tool 2. Present review results (APPROVED or CHANGES REQUESTED) 3. If CHANGES REQUESTED: Address issues, re-submit for review 4. Do NOT declare "ready for planning" until PM sign-off: APPROVED -### After `/triad.plan` Completes: +### After `/aod.project-plan` Completes: 1. Invoke product-manager for PM review 2. Invoke architect for technical review 3. Require **both approvals** before declaring ready **Parallel Review (Claude Code v2.1.16+)**: If context forking is available, PM and Architect reviews run simultaneously in isolated contexts. Use a single message with two Task calls for parallel execution. -### After `/triad.tasks` Completes: +### After `/aod.tasks` Completes: 1. Invoke product-manager, architect, and team-lead 2. Team-lead generates `agent-assignments.md` with parallel execution waves 3. Require **all three approvals** before implementation diff --git a/.claude/skills/implementation-checkpoint/README.md b/.claude/skills/aod-build/README.md similarity index 97% rename from .claude/skills/implementation-checkpoint/README.md rename to .claude/skills/aod-build/README.md index 193d33e..613ac88 100644 --- a/.claude/skills/implementation-checkpoint/README.md +++ b/.claude/skills/aod-build/README.md @@ -31,13 +31,13 @@ This skill automates the entire checkpoint creation workflow: The skill is already installed at: ``` -.claude/skills/implementation-checkpoint/ +.claude/skills/aod-build/ ``` ### Basic Usage ```bash -cd .claude/skills/implementation-checkpoint +cd .claude/skills/aod-build python scripts/generate_checkpoint.py \ --tasks-file ../../specs/{feature-id}/tasks.md \ @@ -93,13 +93,13 @@ Generating checkpoint report... Updating CHECKPOINTS_README.md... ✓ Updated: CHECKPOINTS_README.md -Next: Resume with /triad.implement --resume +Next: Resume with /aod.build --resume ``` ## Directory Structure ``` -.claude/skills/implementation-checkpoint/ +.claude/skills/aod-build/ ├── SKILL.md # Main skill documentation ├── README.md # This file ├── scripts/ @@ -230,7 +230,7 @@ Documents all metric calculations: ```bash # Test analyze script -cd .claude/skills/implementation-checkpoint +cd .claude/skills/aod-build python scripts/analyze_tasks.py ../../specs/001-{{PROJECT_NAME}}/tasks.md # Should output JSON with 120 tasks, 8 phases diff --git a/.claude/skills/implementation-checkpoint/SKILL.md b/.claude/skills/aod-build/SKILL.md similarity index 98% rename from .claude/skills/implementation-checkpoint/SKILL.md rename to .claude/skills/aod-build/SKILL.md index 07ce215..2b2b8b9 100644 --- a/.claude/skills/implementation-checkpoint/SKILL.md +++ b/.claude/skills/aod-build/SKILL.md @@ -1,5 +1,5 @@ --- -name: implementation-checkpoint +name: aod-build description: Generate standardized checkpoint reports for multi-phase implementation projects. Use this skill when pausing implementation at strategic milestones (phase completion, user story completion, critical features) to create comprehensive progress reports with task breakdowns, metrics, knowledge base entries, and resume instructions. --- @@ -25,7 +25,7 @@ Create a checkpoint at: ```bash # Navigate to skill directory -cd .claude/skills/implementation-checkpoint +cd .claude/skills/aod-build # Generate checkpoint (interactive prompts will follow) python scripts/generate_checkpoint.py \ @@ -150,7 +150,7 @@ The checkpoint report includes auto-generated resume commands: ```bash # For team-lead orchestration -/triad.implement --resume +/aod.build --resume # For direct continuation # Continue from task {NEXT_TASK} @@ -268,7 +268,7 @@ Knowledge base entries: 5 ✓ Generated: CHECKPOINT-01_Phase1-2-Complete_T001-T030.md ✓ Updated: CHECKPOINTS_README.md -Next: Resume with /triad.implement --resume +Next: Resume with /aod.build --resume ``` ### Example 2: After Completing User Story 1 diff --git a/.claude/skills/implementation-checkpoint/USAGE.md b/.claude/skills/aod-build/USAGE.md similarity index 96% rename from .claude/skills/implementation-checkpoint/USAGE.md rename to .claude/skills/aod-build/USAGE.md index f78be4b..2a5ff64 100644 --- a/.claude/skills/implementation-checkpoint/USAGE.md +++ b/.claude/skills/aod-build/USAGE.md @@ -3,7 +3,7 @@ ## TL;DR ```bash -cd .claude/skills/implementation-checkpoint +cd .claude/skills/aod-build python scripts/generate_checkpoint.py \ --tasks-file ../../specs/001-{{PROJECT_NAME}}/tasks.md \ @@ -29,7 +29,7 @@ Create a checkpoint when you've reached a strategic milestone: ### Step 2: Navigate to Skill Directory ```bash -cd .claude/skills/implementation-checkpoint +cd .claude/skills/aod-build ``` ### Step 3: Run Generate Script @@ -123,7 +123,7 @@ The script will output: ✓ Location: specs/001-{{PROJECT_NAME}}/CHECKPOINT-01_Phase1-2-Complete_T001-T030.md ✓ Updated: CHECKPOINTS_README.md -Next: Resume with /triad.implement --resume +Next: Resume with /aod.build --resume ``` ### Step 6: Fill in TODO Sections @@ -277,7 +277,7 @@ mkdir -p specs/002-new-feature **Solution**: Verify skill installation ```bash -ls .claude/skills/implementation-checkpoint/references/checkpoint_template.md +ls .claude/skills/aod-build/references/checkpoint_template.md ``` ### Checkpoint number wrong @@ -328,11 +328,11 @@ cp assets/CHECKPOINTS_README_template.md ../../specs/001-{{PROJECT_NAME}}/CHECKP ### Standard Implementation Flow -1. **Start implementation**: `/triad.implement` +1. **Start implementation**: `/aod.build` 2. **Complete milestone**: Mark tasks [X] in tasks.md 3. **Create checkpoint**: Run this skill 4. **Review**: Architect/PM review checkpoint -5. **Resume**: `/triad.implement --resume` +5. **Resume**: `/aod.build --resume` ### Checkpoint Frequency diff --git a/.claude/skills/implementation-checkpoint/assets/CHECKPOINTS_README_template.md b/.claude/skills/aod-build/assets/CHECKPOINTS_README_template.md similarity index 100% rename from .claude/skills/implementation-checkpoint/assets/CHECKPOINTS_README_template.md rename to .claude/skills/aod-build/assets/CHECKPOINTS_README_template.md diff --git a/.claude/skills/implementation-checkpoint/references/checkpoint_template.md b/.claude/skills/aod-build/references/checkpoint_template.md similarity index 100% rename from .claude/skills/implementation-checkpoint/references/checkpoint_template.md rename to .claude/skills/aod-build/references/checkpoint_template.md diff --git a/.claude/skills/implementation-checkpoint/references/metrics_formulas.md b/.claude/skills/aod-build/references/metrics_formulas.md similarity index 100% rename from .claude/skills/implementation-checkpoint/references/metrics_formulas.md rename to .claude/skills/aod-build/references/metrics_formulas.md diff --git a/.claude/skills/implementation-checkpoint/references/naming_conventions.md b/.claude/skills/aod-build/references/naming_conventions.md similarity index 100% rename from .claude/skills/implementation-checkpoint/references/naming_conventions.md rename to .claude/skills/aod-build/references/naming_conventions.md diff --git a/.claude/skills/implementation-checkpoint/scripts/analyze_tasks.py b/.claude/skills/aod-build/scripts/analyze_tasks.py similarity index 100% rename from .claude/skills/implementation-checkpoint/scripts/analyze_tasks.py rename to .claude/skills/aod-build/scripts/analyze_tasks.py diff --git a/.claude/skills/implementation-checkpoint/scripts/generate_checkpoint.py b/.claude/skills/aod-build/scripts/generate_checkpoint.py similarity index 99% rename from .claude/skills/implementation-checkpoint/scripts/generate_checkpoint.py rename to .claude/skills/aod-build/scripts/generate_checkpoint.py index 2d2e825..6f40a34 100755 --- a/.claude/skills/implementation-checkpoint/scripts/generate_checkpoint.py +++ b/.claude/skills/aod-build/scripts/generate_checkpoint.py @@ -211,7 +211,7 @@ def generate_checkpoint( # Generate resume command feature_id = analysis['feature_id'] - resume_command = f"/triad.implement --resume" + resume_command = f"/aod.build --resume" # Current date date = datetime.now().strftime("%Y-%m-%d") @@ -345,7 +345,7 @@ def main(): else: print("⚠️ CHECKPOINTS_README.md not found - skipping index update") - print(f"\nNext: Resume with /triad.implement --resume") + print(f"\nNext: Resume with /aod.build --resume") if __name__ == "__main__": diff --git a/.claude/skills/implementation-checkpoint/scripts/update_index.py b/.claude/skills/aod-build/scripts/update_index.py similarity index 100% rename from .claude/skills/implementation-checkpoint/scripts/update_index.py rename to .claude/skills/aod-build/scripts/update_index.py diff --git a/.claude/skills/prd-create/skill.md b/.claude/skills/aod-define/skill.md similarity index 97% rename from .claude/skills/prd-create/skill.md rename to .claude/skills/aod-define/skill.md index f289257..4f18dff 100644 --- a/.claude/skills/prd-create/skill.md +++ b/.claude/skills/aod-define/skill.md @@ -1,6 +1,6 @@ --- -name: prd-create -description: "Internal skill invoked by /triad.prd to generate industry-standard PRD content using proven frameworks from Google, Amazon, and Intercom. Do NOT invoke directly — use /triad.prd instead, which wraps this skill with Triad governance and sign-offs." +name: aod-define +description: "Internal skill invoked by /aod.define to generate industry-standard PRD content using proven frameworks from Google, Amazon, and Intercom. Do NOT invoke directly — use /aod.define instead, which wraps this skill with Triad governance and sign-offs." --- # PRD Creation Skill @@ -700,7 +700,7 @@ Use this checklist: Once PRD is approved: -1. **Create spec.md** using `/triad.specify` +1. **Create spec.md** using `/aod.spec` 2. **Provide PRD as input**: Reference PRD location in spec creation 3. **Validate alignment**: Ensure spec.md reflects PRD requirements 4. **Sign-off on spec**: Product Manager approves spec.md before implementation @@ -861,7 +861,7 @@ You've used this skill successfully when: 2. **PRD is Clear**: Non-technical stakeholders understand the problem and value 3. **PRD is Aligned**: References product vision, OKRs, roadmap, user stories 4. **PRD is Feasible**: Technical team confirms it's buildable in timeline -5. **PRD Enables Great Specs**: `/triad.specify` produces superior spec.md from this PRD +5. **PRD Enables Great Specs**: `/aod.spec` produces superior spec.md from this PRD 6. **PRD Gets Approved**: Stakeholders sign off without major revisions --- @@ -870,13 +870,13 @@ You've used this skill successfully when: ```bash # Create a new PRD (invokes this skill automatically) -/triad.prd +/aod.define # Create spec from PRD -/triad.specify +/aod.spec # Validate PRD-spec alignment -/triad.analyze +/aod.analyze ``` --- @@ -885,7 +885,7 @@ You've used this skill successfully when: - **kb-query**: Search knowledge base for similar features or patterns - **root-cause-analyzer**: Dig into complex requirement ambiguities -- **spec-validator**: Validate consistency between PRD and spec +- **aod-spec**: Validate consistency between PRD and spec --- diff --git a/.claude/skills/aod-deliver/SKILL.md b/.claude/skills/aod-deliver/SKILL.md new file mode 100644 index 0000000..f256a30 --- /dev/null +++ b/.claude/skills/aod-deliver/SKILL.md @@ -0,0 +1,318 @@ +--- +name: aod-deliver +description: "Structured delivery retrospective for the AOD Lifecycle's Deliver stage. Validates Definition of Done, captures delivery metrics (estimated vs. actual duration), logs surprises, feeds new ideas back into discovery via GitHub Issues, and creates Institutional Knowledge entries. Use this skill when you need to close a feature, run a delivery retrospective, capture lessons learned, or complete the AOD lifecycle." +--- + +# AOD Deliver Skill + +## Purpose + +Close a completed feature with a structured retrospective that captures delivery metrics, surprises, and lessons learned. New ideas from the retrospective feed back into the Discover stage, completing the AOD Lifecycle loop. + +**Entry point**: `/aod.deliver` + +## Prerequisites + +- A feature branch exists with completed work +- `.aod/spec.md` exists with the feature specification +- `.aod/tasks.md` exists with task definitions +- `.aod/scripts/bash/github-lifecycle.sh` is available for GitHub operations + +--- + +## Step 1: Validate Definition of Done + +**GitHub Lifecycle Update (early)**: If a GitHub Issue exists for this feature, update its stage label to `stage:deliver` using `aod_gh_update_stage` from `.aod/scripts/bash/github-lifecycle.sh`. This moves the issue to the Deliver column on the Projects board at the *start* of the delivery retrospective. If `gh` is unavailable, skip silently (graceful degradation). + +Check that the feature meets the Definition of Done criteria: + +1. **Read `.aod/tasks.md`** and count incomplete tasks (lines matching `- [ ]`). +2. **Read `.aod/spec.md`** to extract the feature name and scope. +3. **Check for open blockers**: Search tasks.md for any items marked `BLOCKED`. + +### Validation Results + +**If incomplete tasks exist**: Display count and list them: + +``` +DEFINITION OF DONE — INCOMPLETE + +Feature: {feature_name} +Incomplete Tasks: {count} + +{list of incomplete task descriptions} + +Options: + (A) Mark remaining tasks as complete and proceed + (B) Abort delivery — finish tasks first +``` + +Use AskUserQuestion to let the user choose. + +**If all tasks complete**: Proceed to Step 2. + +``` +DEFINITION OF DONE — PASSED + +Feature: {feature_name} +Tasks: {total} complete, 0 remaining +``` + +--- + +## Step 2: Capture Delivery Metrics + +### Estimated Duration + +Use AskUserQuestion: + +``` +Question: "How long did you originally estimate this feature would take?" +Header: "Estimate" +Options: + - "1-2 days": "A quick feature or fix" + - "3-5 days": "About a week of work" + - "1-2 weeks": "A moderate feature spanning multiple days" + - "3+ weeks": "A large feature requiring significant effort" +``` + +Allow "Other" for custom estimates (e.g., "4 sprints", "3 months"). + +### Actual Duration + +Compute automatically from the feature branch creation date: + +```bash +# Get the date of the first commit on this branch (not on main) +git log main..HEAD --reverse --format="%ai" | head -1 +``` + +If the branch has no commits diverged from main, use the earliest commit date on the current branch. + +Calculate the difference between the branch start date and today's date. Express as: +- "N days" if < 14 days +- "N weeks" if >= 14 days and < 60 days +- "N months" if >= 60 days + +Store both `estimated_duration` and `actual_duration`. + +--- + +## Step 3: Capture Surprise Log + +Use AskUserQuestion: + +``` +Question: "What surprised you most during this feature? (One sentence minimum)" +Header: "Surprises" +Options: + - "Scope was larger than expected": "The feature required more work than initially scoped" + - "Dependencies were complex": "Integrations or dependencies added unexpected complexity" + - "Smooth sailing": "Everything went roughly as planned — no major surprises" +``` + +Allow "Other" for custom surprise statements (required — must be at least 1 sentence). + +**Validation**: If the user provides empty or very short text (<10 chars), re-prompt: "Please provide at least one sentence describing what surprised you." + +Store as `surprise_log`. + +--- + +## Step 4: Capture Next Ideas (Optional Feedback Loop) + +Use AskUserQuestion: + +``` +Question: "Did this feature reveal any new ideas or follow-up work? (Optional — select 'None' to skip)" +Header: "Next ideas" +Options: + - "Yes — let me describe": "I have one or more ideas for follow-up features or improvements" + - "None": "No new ideas emerged from this feature" +``` + +**If "Yes"**: Ask the user to describe each idea. For each idea provided: + +1. Create a GitHub Issue with `stage:discover` label using `aod_gh_create_issue` from `.aod/scripts/bash/github-lifecycle.sh`: + - Title: `[RETRO] {idea_description}` + - Body: + ```markdown + # [RETRO] {idea_description} + + ## ICE Score + Impact: —, Confidence: —, Effort: — = **Not yet scored** + + ## Evidence + Retrospective: Emerged during delivery of {feature_name} + + ## Metadata + - Source: Retrospective + - Priority: Not yet scored + - Date: {YYYY-MM-DD} + - Status: New (from retrospective) + - Origin Feature: {feature_name} + ``` + - Stage: `discover` + +2. If `gh` is unavailable, log the idea to stdout with guidance: + ``` + NEW IDEA FROM RETROSPECTIVE (GitHub unavailable — capture manually): + Idea: {idea_description} + Suggested next step: Run `/aod.idea {idea_description}` to formally capture and score. + ``` + +Store ideas as `next_ideas[]`. + +**If "None"**: Skip and proceed to Step 5. + +--- + +## Step 5: Capture Lessons Learned + +Use AskUserQuestion: + +``` +Question: "What is the key lesson learned from this feature that future developers should know?" +Header: "Lesson" +Options: + - "Technical pattern": "A reusable technical approach or architecture decision worth documenting" + - "Process improvement": "A workflow or process change that would help future features" + - "Tooling insight": "A tool, library, or configuration finding worth preserving" +``` + +Allow "Other" for custom lesson descriptions. + +After category selection, prompt for the full lesson text: +"Describe the lesson in 2-3 sentences. What was the problem, what did you learn, and how should it be applied?" + +**Validation**: Require at least 20 characters of lesson text. + +Store as `lesson_category` and `lesson_text`. + +--- + +## Step 6: Write Institutional Knowledge Entry + +Append a new entry to `docs/INSTITUTIONAL_KNOWLEDGE.md` in the `## Knowledge Entries` section. + +Determine the next entry number by scanning existing `### Entry N:` headers and incrementing. + +```markdown +### Entry {N}: {feature_name} — Delivery Retrospective + +## [{lesson_category}] - {one_line_summary} + +**Date**: {YYYY-MM-DD} +**Context**: Delivery retrospective for {feature_name}. Estimated: {estimated_duration}, Actual: {actual_duration}. + +**Problem**: +{lesson_text — first sentence or clause describing the challenge} + +**Solution**: +{lesson_text — remaining sentences describing the approach/learning} + +**Why This Matters**: +Captured during structured delivery retrospective. {surprise_log} + +**Tags**: #retrospective #delivery #{lesson_category_tag} + +### Related Files: +- `.aod/spec.md` — Feature specification +- `.aod/tasks.md` — Task breakdown + +--- +``` + +Map `lesson_category` to tags: +- "Technical pattern" → `#architecture #pattern` +- "Process improvement" → `#process #workflow` +- "Tooling insight" → `#tooling #configuration` +- Other → `#general` + +--- + +## Step 7: Post Delivery Metrics to GitHub Issue + +If a GitHub Issue exists for this feature (search by feature name or branch): + +1. Find the issue: `aod_gh_find_issue "{feature_name}"` or search by branch name +2. Add a comment with delivery metrics: + ```markdown + ## Delivery Metrics + + | Metric | Value | + |--------|-------| + | Delivery Date | {YYYY-MM-DD} | + | Estimated Duration | {estimated_duration} | + | Actual Duration | {actual_duration} | + | Surprise Log | {surprise_log} | + | Lessons Learned | {lesson_category}: {one_line_summary} | + | New Ideas | {count of next_ideas or "None"} | + ``` +3. Note: The issue was already transitioned to `stage:deliver` in Step 1. + +--- + +## Step 8: Regenerate BACKLOG.md + +Run `.aod/scripts/bash/backlog-regenerate.sh` to update the backlog snapshot with the newly delivered item. If `gh` is unavailable, skip silently. + +--- + +## Step 9: Display Retrospective Summary + +``` +AOD DELIVERY COMPLETE + +Feature: {feature_name} + +Delivery Metrics: + Estimated Duration: {estimated_duration} + Actual Duration: {actual_duration} + Variance: {over/under/on-target} + +Surprise Log: + {surprise_log} + +Lessons Learned: + Category: {lesson_category} + Summary: {one_line_summary} + KB Entry: Entry {N} in INSTITUTIONAL_KNOWLEDGE.md + +Feedback Loop: + New Ideas: {count or "None"} + {for each idea: " - [RETRO] {description} → Issue #{number}"} + +Next Steps: + - Review KB entry in docs/INSTITUTIONAL_KNOWLEDGE.md + - Run `/aod.discover` to score any new ideas from this retrospective + - Feature lifecycle is now COMPLETE +``` + +--- + +## Edge Cases + +- **No tasks.md**: Skip DoD validation, warn user +- **No spec.md**: Use branch name as feature name +- **Branch has no diverged commits**: Use today's date for actual duration calculation +- **gh CLI unavailable**: Skip all GitHub operations (issue creation, comments, label updates, backlog regeneration) — graceful degradation +- **Empty surprise log**: Re-prompt (required field) +- **Empty lesson text**: Re-prompt (required field) +- **INSTITUTIONAL_KNOWLEDGE.md missing**: Create it with standard header before appending +- **User selects "Mark remaining tasks as complete"**: Update tasks.md to mark all `- [ ]` as `- [x]` before proceeding +- **Multiple ideas from retrospective**: Create one GitHub Issue per idea + +## Quality Checklist + +- [ ] Definition of Done validated (all tasks complete or user override) +- [ ] Estimated duration captured from user +- [ ] Actual duration computed from branch creation date +- [ ] Surprise log captured (minimum 1 sentence) +- [ ] Next ideas prompted (optional; each creates GitHub Issue with `stage:discover`) +- [ ] Lessons learned captured with category and full description +- [ ] KB entry appended to INSTITUTIONAL_KNOWLEDGE.md with correct entry number +- [ ] Delivery metrics posted to GitHub Issue as comment +- [ ] Issue transitioned to `stage:deliver` label +- [ ] BACKLOG.md regenerated +- [ ] Retrospective summary displayed with all metrics diff --git a/.claude/skills/aod-discover/SKILL.md b/.claude/skills/aod-discover/SKILL.md new file mode 100644 index 0000000..e3fd17c --- /dev/null +++ b/.claude/skills/aod-discover/SKILL.md @@ -0,0 +1,477 @@ +--- +name: aod-discover +description: "Unified discovery skill with 3 entry points: /aod.discover (full flow: capture + score + validate), /aod.idea (capture + score only), /aod.validate (PM validation for existing idea). Use this skill when you need to capture ideas, run discovery, validate ideas with PM, generate user stories, log feature requests, or add items to the ideas backlog." +--- + +# AOD Discover Skill + +## Purpose + +Unified discovery skill for the AOD Lifecycle's **Discover** stage. Handles idea capture, ICE scoring, evidence gathering, and PM validation with 3 entry points: + +- **`/aod.discover`** — Full flow: capture idea + ICE score + evidence + PM validation + user story +- **`/aod.idea`** — Capture only: capture idea + ICE score + evidence (no PM validation) +- **`/aod.validate`** — Validate only: submit existing idea for PM review + user story generation + +## Entry Point Detection + +Determine the entry point from the invoking command: +- If invoked via `/aod.discover` → run **Full Flow** (Steps 1-8) +- If invoked via `/aod.idea` → run **Capture Only** (Steps 1-5) +- If invoked via `/aod.validate` → run **Validate Only** (Steps 6-8) + +--- + +## Shared: Backlog Initialization + +**Run at the start of every entry point.** + +Check if `docs/product/_backlog/01_IDEAS.md` exists. If not, create it: + +```markdown +# Ideas Backlog + +| ID | Idea | Source | Date | Status | ICE Score | +|----|------|--------|------|--------|-----------| +``` + +Check if `docs/product/_backlog/02_USER_STORIES.md` exists. If not, create it: + +```markdown +# Product Backlog - User Stories + +| Priority | Story ID | Story | ICE Score | Source | Status | +|----------|----------|-------|-----------|--------|--------| +``` + +--- + +## Step 1: Parse Input (Capture + Full Flow) + +Extract the idea description from user arguments. If no description is provided, ask the user to describe their idea. + +## Step 2: Generate IDEA-NNN ID + +1. Read `docs/product/_backlog/01_IDEAS.md` +2. Parse the table to find all existing IDEA-NNN identifiers +3. Find the highest NNN value +4. Increment by 1, zero-pad to 3 digits +5. If no existing entries, start at IDEA-001 + +## Step 3: Capture Source and ICE Score + +### Source + +Use AskUserQuestion to determine the idea source: + +``` +Question: "Where did this idea come from?" +Options: + - Brainstorm: "Generated during a brainstorming or planning session" + - Customer Feedback: "Reported by a customer or based on user research" + - Team Idea: "Suggested by a team member during development" + - User Request: "Directly requested by a user or stakeholder" +``` + +### ICE Scoring + +Present each ICE dimension using AskUserQuestion: + +#### Impact — "How much value does this deliver to users?" + +``` +Options: + - High (9): "Transformative — significant user value" + - Medium (6): "Solid improvement — meaningful but incremental" + - Low (3): "Minor enhancement — small quality-of-life fix" +``` + +Allow "Other" for custom numeric values (1-10). + +#### Confidence — "How sure are we this will succeed?" + +``` +Options: + - High (9): "Proven pattern — strong evidence it will work" + - Medium (6): "Some unknowns — reasonable confidence with gaps" + - Low (3): "Speculative — significant uncertainty" +``` + +Allow "Other" for custom numeric values (1-10). + +#### Effort (Ease of Implementation) — "How easy is this to build?" + +``` +Options: + - High (9): "Days of work — straightforward implementation" + - Medium (6): "Weeks of work — moderate complexity" + - Low (3): "Months of work — significant engineering effort" +``` + +Allow "Other" for custom numeric values (1-10). + +**Compute**: ICE Total = Impact + Confidence + Effort (range 3-30) + +## Step 4: Evidence Prompt (Capture + Full Flow) + +After ICE scoring, prompt the user for evidence supporting this idea. + +Use AskUserQuestion: + +``` +Question: "Who has this problem, and how do you know?" +Header: "Evidence" +Options: + - Customer Feedback: "Based on direct customer reports, support tickets, or user research" + - Team Observation: "Noticed by the team during development, testing, or internal usage" + - Analytics Data: "Supported by usage metrics, error rates, or behavioral analytics" + - User Request: "Explicitly requested by a user, stakeholder, or partner" +``` + +Allow "Other" for free-text evidence statements. + +**Store the response** as the `evidence` field. This value is used in: +- Step 5b: GitHub Issue body (`## Evidence` section) +- Step 6: PM validation (evidence quality evaluation) +- BACKLOG.md Discover section (Evidence column) + +**If the user selects a predefined category**: Store as `"{Category}: {any additional detail}"` if they provide detail, or just `"{Category}"` if not. + +**If the user provides free text via "Other"**: Store the full text as-is. + +## Step 5: Apply Auto-Defer Gate + +Determine status based on ICE total: + +- **Total < 12**: Set status to **"Deferred"** (auto-deferred) +- **Total >= 12**: Set status to **"Scoring"** + +Append a new row to `docs/product/_backlog/01_IDEAS.md`: + +``` +| IDEA-{NNN} | {idea_description} | {source} | {YYYY-MM-DD} | {status} | {total} (I:{impact} C:{confidence} E:{effort}) | +``` + +**If auto-deferred AND entry point is Full Flow (`/aod.discover`)**: +- Flow **STOPS** here. Do not proceed to PM validation. +- Display result with guidance: + +``` +IDEA CAPTURED — AUTO-DEFERRED + +ID: IDEA-{NNN} +Idea: {description} +Source: {source} +Evidence: {evidence} +ICE Score: {total} (I:{impact} C:{confidence} E:{effort}) +Priority Tier: Deferred +Status: Deferred + +This idea was auto-deferred (score < 12). +To request PM override: `/aod.validate IDEA-{NNN}` +To re-score with new information: `/aod.score IDEA-{NNN}` +``` + +**If auto-deferred AND entry point is Capture Only (`/aod.idea`)**: Display same result, exit. + +**If NOT auto-deferred AND entry point is Capture Only (`/aod.idea`)**: Display result and exit: + +``` +IDEA CAPTURED + +ID: IDEA-{NNN} +Idea: {description} +Source: {source} +Evidence: {evidence} +Date: {YYYY-MM-DD} +ICE Score: {total} (I:{impact} C:{confidence} E:{effort}) +Priority Tier: {tier} +Status: Scoring + +Next: Run `/aod.validate IDEA-{NNN}` to submit for PM review, or continue capturing ideas with `/aod.idea`. +``` + +**If NOT auto-deferred AND entry point is Full Flow (`/aod.discover`)**: Continue to Step 5a. + +## Step 5a: GitHub Issue Creation (All Entry Points) + +After capturing the idea to `01_IDEAS.md`, create a GitHub Issue for lifecycle tracking: + +1. Build the issue body using the structured format from `github-lifecycle.sh`: + ```markdown + # [IDEA-{NNN}] {idea_description} + + ## ICE Score + Impact: {impact}, Confidence: {confidence}, Effort: {effort} = **{total}** + + ## Evidence + {evidence} + + ## Metadata + - Source: {source} + - Priority: {priority_tier} + - Date: {YYYY-MM-DD} + - Status: {status} + ``` + +2. Call `aod_gh_create_issue` (from `.aod/scripts/bash/github-lifecycle.sh`): + - Title: `[IDEA-{NNN}] {idea_description}` + - Body: structured markdown above + - Stage: `discover` + - Idea ID: `IDEA-{NNN}` (for duplicate detection) + +3. If `gh` is unavailable, skip silently (graceful degradation). + +## Step 5b: Regenerate BACKLOG.md + +After GitHub Issue creation, run `.aod/scripts/bash/backlog-regenerate.sh` to update the backlog snapshot. If `gh` is unavailable, skip silently. + +## Step 5c: Check Governance Tier (Full Flow only) + +Before proceeding to PM validation in the Full Flow (`/aod.discover`), check the governance tier: + +1. Read `.aod/memory/constitution.md` +2. Find the governance tier configuration (`governance:` → `tier:` value) +3. Valid values: `light`, `standard`, `full`. Default: `standard` + +**If tier is `light`**: +- PM validation is **optional** — skip Steps 6-7 in the Full Flow +- Display note: "Note: Light governance tier — PM validation skipped. Run `/aod.validate IDEA-{NNN}` to manually request PM review." +- Proceed directly to Step 8 (Write entries) with status remaining "Scoring" (not "Validated") +- The user can still manually invoke `/aod.validate IDEA-{NNN}` at any time + +**If tier is `standard` or `full`**: Continue to Step 6 as normal. + +**Note**: The `/aod.validate` entry point always runs PM validation regardless of tier — it is an explicit user request for PM review. + +## Step 6: PM Validation (Validate + Full Flow) + +### For `/aod.validate` entry point: Parse and find idea + +Extract the IDEA-NNN identifier from user arguments. Validate format matches `IDEA-` followed by a 3-digit number. If invalid or missing, display: `Usage: /aod.validate IDEA-NNN` + +Read `docs/product/_backlog/01_IDEAS.md` and find the matching row. + +**Error conditions**: +- Idea not found: `"Error: IDEA-{NNN} not found in 01_IDEAS.md"` +- Status is "Rejected": `"Error: IDEA-{NNN} has already been rejected by PM. Re-score with /aod.score first."` +- Status is "Validated": `"Error: IDEA-{NNN} has already been validated — see 02_USER_STORIES.md"` + +Display idea for review: + +``` +IDEA FOR PM VALIDATION + +ID: IDEA-{NNN} +Idea: {description} +Source: {source} +Evidence: {evidence} +Date: {date} +Status: {status} +ICE Score: {total} (I:{impact} C:{confidence} E:{effort}) +Priority Tier: {tier} +Auto-Deferred: {Yes if status is Deferred, otherwise No} +``` + +### Launch PM Review + +Use the Task tool with `product-manager` subagent_type: + +``` +Review this idea for product backlog inclusion: + +Idea: {idea_description} +ICE Score: {total} (I:{impact} C:{confidence} E:{effort}) +Priority Tier: {tier} +Current Status: {status} +Auto-Deferred: {yes/no} +Evidence: {evidence} + +Evaluate: +1. Does this idea align with the product vision and roadmap? +2. Is the ICE scoring reasonable given the idea description? +3. Does this idea deliver meaningful user value? +4. Should this idea enter the product backlog as a user story? +5. Is the evidence sufficient to justify pursuing this idea? Evaluate the quality and + specificity of the evidence provided. + +If evidence is empty or "No evidence provided", flag this: +"No evidence provided — recommend gathering evidence before proceeding." +You may still approve if the idea has strong merit despite missing evidence, but note +the evidence gap in your rationale. + +If auto-deferred (score < 12), provide additional justification for why this idea +should or should not override the auto-defer gate. + +Respond with: +STATUS: [APPROVED | REJECTED] +EVIDENCE_QUALITY: [Strong | Adequate | Weak | Missing] +RATIONALE: [Your detailed reasoning — 2-4 sentences] +``` + +### Handle Rejection + +If PM returns **REJECTED**: +1. Update idea status to **"Rejected"** in `01_IDEAS.md` using Edit tool +2. Display rejection and exit: + +``` +PM VALIDATION: REJECTED + +ID: IDEA-{NNN} +Idea: {description} +PM Rationale: {rationale} + +The idea has been marked as Rejected in 01_IDEAS.md. +To re-submit: re-score with `/aod.score IDEA-{NNN}`, then run `/aod.validate IDEA-{NNN}` again. +``` + +### Handle Approval + +If PM returns **APPROVED**: Continue to Step 7. + +## Step 7: User Story Generation + +1. **Generate user story**: Transform idea into "As a [persona], I want [action], so that [benefit]" format. + - Default persona: "Template Adopter" if not evident from idea. +2. **Present for confirmation**: Use AskUserQuestion: + ``` + Options: + - Accept: "Save this user story as-is" + - Edit: "Let me modify the user story text" + ``` +3. **Generate US-NNN ID**: Read `02_USER_STORIES.md`, find highest US-NNN, increment by 1 (pad to 3 digits). Start at US-001 if empty. +4. **Determine priority**: Map ICE score to priority rank: + - P0 (25-30): Priority = 1 + - P1 (18-24): Priority = 2 + - P2 (12-17): Priority = 3 + - Deferred (<12, PM override): Priority = 4 + +## Step 8: Write Backlog Entries and Report + +### Write entries + +1. Append row to `docs/product/_backlog/02_USER_STORIES.md`: + ``` + | {priority} | US-{NNN} | {user_story_text} | {ice_total} | IDEA-{NNN} | Ready for PRD | + ``` +2. Update idea status to **"Validated"** in `01_IDEAS.md`. +3. If idea was auto-deferred (status was "Deferred") and PM approved, append PM override note after the user stories table: + ```markdown + + > **PM Override — US-{NNN}**: IDEA-{NNN} was auto-deferred (ICE score {total} < 12) but approved by PM. Rationale: {pm_rationale} + ``` + +### Report result + +**For `/aod.validate` entry point**: +``` +PM VALIDATION: APPROVED + +ID: IDEA-{NNN} +Idea: {description} +Evidence Quality: {evidence_quality} +PM Rationale: {rationale} + +User Story Created: + ID: US-{NNN} + Story: "{user_story_text}" + Priority: {priority} + Status: Ready for PRD + +Idea status updated to "Validated" in 01_IDEAS.md. +User story added to 02_USER_STORIES.md. + +Next: Run `/aod.define {topic}` to create a PRD from this user story. +``` + +**For `/aod.discover` entry point (full flow)**: +``` +AOD DISCOVERY COMPLETE + +Idea Captured: + ID: IDEA-{NNN} + Description: {description} + Source: {source} + Evidence: {evidence} + +ICE Scoring: + Score: {total} (I:{impact} C:{confidence} E:{effort}) + Priority Tier: {tier} + +PM Validation: APPROVED + Evidence Quality: {evidence_quality} + Rationale: {rationale} + +User Story Created: + ID: US-{NNN} + Story: "{user_story_text}" + Priority: {priority} + Status: Ready for PRD + +Next: Run `/aod.define {topic}` to create a PRD from this user story. +``` + +--- + +## ICE Scoring Reference + +### Quick-Assessment Anchors + +| Dimension | High (9) | Medium (6) | Low (3) | +|-----------|----------|------------|---------| +| **Impact** | Transformative | Solid improvement | Minor enhancement | +| **Confidence** | Proven pattern | Some unknowns | Speculative | +| **Effort (Ease)** | Days of work | Weeks of work | Months of work | + +### Priority Tiers + +| Score Range | Priority | Action | +|-------------|----------|--------| +| 25-30 | P0 (Critical) | Fast-track to development | +| 18-24 | P1 (High) | Queue for next sprint | +| 12-17 | P2 (Medium) | Consider when capacity allows | +| < 12 | Deferred | Auto-defer; requires PM override via `/aod.validate` | + +### Auto-Defer Gate + +Ideas scoring below 12 are automatically deferred. In the full flow (`/aod.discover`), the flow stops and no PM validation occurs. Use `/aod.validate IDEA-NNN` to request PM override for deferred ideas. + +--- + +## Edge Cases + +- **Empty table**: Start ID at IDEA-001 +- **No description provided**: Prompt user for idea description +- **Custom ICE score outside 1-10**: Clamp to valid range (1 minimum, 10 maximum) +- **Backlog files missing**: Auto-create with headers (Backlog Initialization) +- **Duplicate idea text**: Allow it — the IDEA-NNN ID is the unique identifier +- **IDEA-NNN not found** (validate): Display error with the ID that was searched for +- **Already Rejected** (validate): Cannot re-validate directly — user must re-score first with `/aod.score` +- **Already Validated** (validate): Cannot re-validate — user story already exists +- **PM timeout or error**: Report the error and suggest retrying +- **User edits story to empty string**: Re-prompt for user story text +- **PM approves auto-deferred idea**: Document override rationale in backlog +- **Auto-deferred in full flow**: Flow stops — no PM validation, no user story + +## Quality Checklist + +- [ ] Backlog files auto-created if missing +- [ ] Entry point correctly detected (discover/idea/validate) +- [ ] IDEA-NNN ID generated correctly (sequential, zero-padded) +- [ ] Source captured from user selection +- [ ] Evidence prompted after ICE scoring (predefined categories + free text) +- [ ] Evidence included in GitHub Issue body and display outputs +- [ ] ICE score computed correctly (additive I+C+E) +- [ ] Auto-defer gate applied (< 12 = Deferred, flow stops in full flow) +- [ ] Governance tier read from constitution (light/standard/full, default: standard) +- [ ] Light tier: PM validation skipped in full flow, with note to user +- [ ] PM validation includes evidence quality evaluation (Strong/Adequate/Weak/Missing) +- [ ] PM validation invoked via Task tool (product-manager subagent) +- [ ] Rejection: Status updated, flow exits +- [ ] Approval: User story generated in proper format +- [ ] User story presented for confirmation +- [ ] US-NNN ID generated and row appended to 02_USER_STORIES.md +- [ ] Idea status updated to Validated on approval +- [ ] PM override documented if idea was auto-deferred +- [ ] Result reported with next step guidance diff --git a/.claude/skills/thinking-lens/SKILL.md b/.claude/skills/aod-lens/SKILL.md similarity index 99% rename from .claude/skills/thinking-lens/SKILL.md rename to .claude/skills/aod-lens/SKILL.md index 3154724..d528c49 100644 --- a/.claude/skills/thinking-lens/SKILL.md +++ b/.claude/skills/aod-lens/SKILL.md @@ -1,5 +1,5 @@ --- -name: thinking-lens +name: aod-lens description: Routes to 14 structured thinking methodologies (lenses) for systematic analysis. Use this skill when you need to think through problems, apply thinking lenses, reason through decisions, or perform systematic analysis. Auto-selects appropriate lens based on context - 5 Whys for failures, Pre-Mortem for risks, First Principles for assumptions, Systems Thinking for architecture, Four Causes for understanding, Cargo Cult Detection for validation, Golden Mean for calibration. --- diff --git a/.claude/skills/aod-plan/SKILL.md b/.claude/skills/aod-plan/SKILL.md new file mode 100644 index 0000000..685a79a --- /dev/null +++ b/.claude/skills/aod-plan/SKILL.md @@ -0,0 +1,138 @@ +--- +name: aod-plan +description: Plan stage router that auto-detects artifact state and delegates to the correct sub-step (/aod.spec, /aod.project-plan, or /aod.tasks) without the user needing to remember the sequence. Use this skill when you need to navigate the Plan stage, auto-route plan commands, or determine which planning sub-step comes next. +--- + +# Plan Stage Router Skill + +## Purpose + +Stateless router that reads frontmatter from spec.md, plan.md, and tasks.md to determine which Plan sub-step to invoke next. Reduces cognitive load by auto-detecting progress through the Plan stage's 3 sub-steps. + +## How It Works + +### Step 1: Determine Feature Context + +1. Get branch: `git branch --show-current` → extract NNN prefix +2. Derive specs directory: `specs/{NNN}-*/` +3. If no specs directory found, check `.aod/spec.md` as fallback +4. If no feature context found: warn and suggest `/aod.define` first + +### Step 2: Read Artifact States + +For each artifact (spec.md, plan.md, tasks.md), determine its approval status: + +1. **Check file existence** — if file cannot be read (missing, permissions, encoding), treat as "does not exist" +2. **Parse YAML frontmatter** — extract the `triad:` block between `---` delimiters +3. **Extract sign-off status** — read `triad.{role}_signoff.status` for the required reviewers + +### Step 3: Evaluate Frontmatter (with error handling) + +For each artifact file, apply these rules in order: + +1. **File does not exist** → status = `missing` +2. **File exists but has no `---` frontmatter delimiters** → status = `not_approved`, emit: "Note: {file} has no frontmatter. Running {sub-step} for review." +3. **File has frontmatter but no `triad:` key** → status = `not_approved`, emit: "Note: {file} frontmatter missing triad block. Running {sub-step} for review." +4. **`triad:` exists but required sign-off field is null or missing** → status = `not_approved` +5. **Sign-off status is not a recognized value** → status = `not_approved`, emit: "Warning: Unexpected status '{value}' in {file}. Re-running {sub-step}." +6. **YAML parse error** → status = `not_approved`, emit: "Warning: Could not parse frontmatter in {file}. Re-running {sub-step}." + +**Recognized approved statuses**: `APPROVED`, `APPROVED_WITH_CONCERNS`, `BLOCKED_OVERRIDDEN` + +### Step 3b: Read Governance Tier + +Read `.aod/memory/constitution.md` and extract the governance tier: + +1. Look for the `## Governance Tiers` section +2. Find the configuration block: `governance:` → `tier:` value +3. Valid values: `light`, `standard`, `full` +4. If not found or invalid: default to `standard` + +**Tier affects Step 4 decision table** — specifically the spec PM sign-off check. + +### Step 4: Apply Decision Table + +**Standard and Full tiers** (default behavior): + +| spec.md exists? | spec PM approved? | plan.md exists? | plan dual-approved? | tasks.md exists? | tasks triple-approved? | Action | +|-----------------|-------------------|-----------------|---------------------|------------------|------------------------|--------| +| No | — | — | — | — | — | Invoke `/aod.spec` | +| Yes | No | — | — | — | — | Invoke `/aod.spec` (needs PM sign-off) | +| Yes | Yes | No | — | — | — | Invoke `/aod.project-plan` | +| Yes | Yes | Yes | No | — | — | Invoke `/aod.project-plan` (needs dual sign-off) | +| Yes | Yes | Yes | Yes | No | — | Invoke `/aod.tasks` | +| Yes | Yes | Yes | Yes | Yes | No | Invoke `/aod.tasks` (needs triple sign-off) | +| Yes | Yes | Yes | Yes | Yes | Yes | Report "Plan stage complete" | + +**Light tier** (reduced gates): + +| spec.md exists? | plan.md exists? | plan dual-approved? | tasks.md exists? | tasks triple-approved? | Action | +|-----------------|-----------------|---------------------|------------------|------------------------|--------| +| No | — | — | — | — | Invoke `/aod.spec` | +| Yes | No | — | — | — | Invoke `/aod.project-plan` (skip PM spec sign-off) | +| Yes | Yes | No | — | — | Invoke `/aod.project-plan` (needs dual sign-off) | +| Yes | Yes | Yes | No | — | Invoke `/aod.tasks` | +| Yes | Yes | Yes | Yes | No | Invoke `/aod.tasks` (needs triple sign-off) | +| Yes | Yes | Yes | Yes | Yes | Report "Plan stage complete" | + +In Light tier, when spec.md exists but has no PM sign-off, the router **skips** the PM spec sign-off check and proceeds directly to `/aod.project-plan`. Emit: "Note: Light governance tier — PM spec sign-off skipped." + +**Full tier** uses the same table as Standard. The difference between Standard and Full is that Full requires a **separate** PM spec sign-off step (the PM reviews spec.md independently before plan creation). This distinction is enforced within `/aod.spec` itself, not in the router. + +**Approval checks per artifact**: +- **spec.md** (Standard/Full): `triad.pm_signoff.status` is approved +- **spec.md** (Light): existence is sufficient — PM sign-off not required +- **plan.md**: `triad.pm_signoff.status` AND `triad.architect_signoff.status` are both approved +- **tasks.md**: `triad.pm_signoff.status` AND `triad.architect_signoff.status` AND `triad.techlead_signoff.status` are all approved + +**Invariant**: Triple sign-off on tasks.md is the governance floor for ALL tiers, including Light. + +### Step 5: Execute or Report + +Based on decision table result: + +- **Invoke sub-command**: Use the Skill tool to invoke the appropriate skill (`aod.spec`, `aod.project-plan`, or `aod.tasks`) +- **Plan stage complete**: Display completion message: + ``` + Plan stage complete. + + All artifacts approved: + - spec.md: PM sign-off ✓ + - plan.md: PM + Architect sign-off ✓ + - tasks.md: PM + Architect + Team-Lead sign-off ✓ + + Next: Run /aod.build to start implementation. + ``` + +## Edge Cases + +### No PRD exists +If the user runs `/aod.plan` but there is no approved PRD for the current feature (no `docs/product/02_PRD/{NNN}-*.md`), warn: +``` +No approved PRD found for this feature. + +The Plan stage requires a PRD as input. Run /aod.define first to create one, +then return to /aod.plan. +``` + +### Direct sub-command invocation +The router does NOT block direct invocation of `/aod.spec`, `/aod.project-plan`, or `/aod.tasks`. Those commands work independently — the router is a convenience layer, not a gatekeeper. + +### Re-run after rejection +If a governance gate rejects (e.g., PM requests changes to spec.md), the user fixes issues and re-runs `/aod.plan`. The router detects the missing/rejected sign-off and re-invokes the correct sub-step. + +## Integration + +### Reads +- `specs/{NNN}-*/spec.md` — check existence and PM sign-off +- `specs/{NNN}-*/plan.md` — check existence and dual sign-off +- `specs/{NNN}-*/tasks.md` — check existence and triple sign-off +- `docs/product/02_PRD/{NNN}-*.md` — check PRD existence (edge case) + +### Invokes +- `/aod.spec` — when spec needs creation or PM approval +- `/aod.project-plan` — when plan needs creation or dual approval +- `/aod.tasks` — when tasks need creation or triple approval + +### Updates +- None (stateless router — reads only) diff --git a/.claude/skills/architecture-validator/SKILL.md b/.claude/skills/aod-project-plan/SKILL.md similarity index 98% rename from .claude/skills/architecture-validator/SKILL.md rename to .claude/skills/aod-project-plan/SKILL.md index 5d5447c..67fc78c 100644 --- a/.claude/skills/architecture-validator/SKILL.md +++ b/.claude/skills/aod-project-plan/SKILL.md @@ -1,5 +1,5 @@ --- -name: architecture-validator +name: aod-project-plan description: Validates architecture documentation completeness by checking for technology stack, API specifications, database schema, security architecture, and alignment with feature specification. Use this skill when you need to check if plan.md is complete before implementation, validate architecture documentation, or review technical plans for completeness. --- @@ -129,7 +129,7 @@ Constitution check: 7/7 passed ✓ Design artifacts present ✓ Spec alignment validated ✓ -Your architecture is ready for /triad.tasks! +Your architecture is ready for /aod.tasks! Highlights: - Comprehensive data model (5 entities) diff --git a/.claude/skills/pdl-score/SKILL.md b/.claude/skills/aod-score/SKILL.md similarity index 94% rename from .claude/skills/pdl-score/SKILL.md rename to .claude/skills/aod-score/SKILL.md index 0ca50a4..c4be597 100644 --- a/.claude/skills/pdl-score/SKILL.md +++ b/.claude/skills/aod-score/SKILL.md @@ -1,5 +1,5 @@ --- -name: pdl-score +name: aod-score description: "Re-score an existing idea's ICE rating when circumstances change. Use this skill when you need to re-evaluate ideas, update ICE scores, change idea priority, or re-assess deferred ideas." --- @@ -37,7 +37,7 @@ Check if `docs/product/_backlog/02_USER_STORIES.md` exists. If not, create it wi ### Step 2: Parse Input -Extract the IDEA-NNN identifier from user arguments. Validate the format matches `IDEA-` followed by a 3-digit number. If invalid or missing, display usage: `Usage: /pdl.score IDEA-NNN` +Extract the IDEA-NNN identifier from user arguments. Validate the format matches `IDEA-` followed by a 3-digit number. If invalid or missing, display usage: `Usage: /aod.score IDEA-NNN` ### Step 3: Read Ideas Backlog @@ -115,10 +115,10 @@ Apply status transitions based on threshold crossings: - If current status is **"Deferred"** and new score >= 12: Set status to **"Scoring"** - If current status is **"Scoring"** and new score < 12: Set status to **"Deferred"** - If current status is **"Validated"**: **Preserve** status (already PM-approved, do not downgrade) -- If current status is **"Rejected"** and new score >= 12: Set status to **"Scoring"** (re-opens for re-validation via `/pdl.validate`) +- If current status is **"Rejected"** and new score >= 12: Set status to **"Scoring"** (re-opens for re-validation via `/aod.validate`) - If current status is **"Rejected"** and new score < 12: Set status to **"Deferred"** -**Note**: Re-scoring a Rejected idea resets it for a fresh PM review. The PM previously rejected the idea, but re-scoring indicates changed circumstances that warrant re-evaluation. The user must still run `/pdl.validate` to get PM approval. +**Note**: Re-scoring a Rejected idea resets it for a fresh PM review. The PM previously rejected the idea, but re-scoring indicates changed circumstances that warrant re-evaluation. The user must still run `/aod.validate` to get PM approval. ### Step 8: Update Row In Place @@ -167,18 +167,18 @@ Date updated: {YYYY-MM-DD} | 25-30 | P0 (Critical) | Fast-track to development | | 18-24 | P1 (High) | Queue for next sprint | | 12-17 | P2 (Medium) | Consider when capacity allows | -| < 12 | Deferred | Auto-defer; requires PM override via `/pdl.validate` | +| < 12 | Deferred | Auto-defer; requires PM override via `/aod.validate` | ### Auto-Defer Gate -Ideas scoring below 12 are automatically deferred. The PM can override this gate using `/pdl.validate IDEA-NNN`. +Ideas scoring below 12 are automatically deferred. The PM can override this gate using `/aod.validate IDEA-NNN`. ## Edge Cases - **IDEA-NNN not found**: Display error with the ID that was searched for - **Invalid ID format**: Display usage guidance - **Validated status**: Preserve — PM has already approved, re-scoring only updates the numeric score -- **Rejected status**: Re-opens to Scoring (>= 12) or Deferred (< 12) — allows re-submission to PM via `/pdl.validate` +- **Rejected status**: Re-opens to Scoring (>= 12) or Deferred (< 12) — allows re-submission to PM via `/aod.validate` - **Custom ICE score outside 1-10**: Clamp to valid range (1 minimum, 10 maximum) - **Score doesn't change**: Still update the date to record that a re-evaluation occurred diff --git a/.claude/skills/spec-validator/SKILL.md b/.claude/skills/aod-spec/SKILL.md similarity index 95% rename from .claude/skills/spec-validator/SKILL.md rename to .claude/skills/aod-spec/SKILL.md index c2c8b67..9c4e3f8 100644 --- a/.claude/skills/spec-validator/SKILL.md +++ b/.claude/skills/aod-spec/SKILL.md @@ -1,5 +1,5 @@ --- -name: spec-validator +name: aod-spec description: Validates specification completeness and quality by checking for mandatory sections, [NEEDS CLARIFICATION] markers, testable criteria, and clear scope boundaries. Use this skill when you need to check if spec is complete, validate specifications, review spec.md, or check specification quality. Ensures specifications are ready for architecture and implementation phases. --- @@ -113,7 +113,7 @@ No clarification markers found ✓ All requirements testable ✓ Scope clearly bounded ✓ -Your specification is ready for /triad.plan! +Your specification is ready for /aod.project-plan! ``` ### Example 2: Incomplete Specification @@ -142,10 +142,10 @@ Issues Found: Recommendations: 1. Add Success Criteria section with measurable outcomes -2. Resolve all [NEEDS CLARIFICATION] markers using /triad.clarify +2. Resolve all [NEEDS CLARIFICATION] markers using /aod.clarify 3. Add specific validation criteria to FR-003 and FR-007 -Run /triad.clarify to resolve clarification markers. +Run /aod.clarify to resolve clarification markers. ``` ## Integration @@ -163,7 +163,7 @@ Run /triad.clarify to resolve clarification markers. ### Invokes -- Can suggest using /triad.clarify command if clarifications needed +- Can suggest using /aod.clarify command if clarifications needed ## Validation Logic diff --git a/.claude/skills/aod-status/SKILL.md b/.claude/skills/aod-status/SKILL.md new file mode 100644 index 0000000..dded3ee --- /dev/null +++ b/.claude/skills/aod-status/SKILL.md @@ -0,0 +1,89 @@ +--- +name: aod-status +description: "On-demand backlog snapshot and lifecycle stage summary. Regenerates BACKLOG.md from GitHub Issues and displays item counts per stage. Use this skill when you need to check backlog status, view stage counts, regenerate BACKLOG.md, or get a lifecycle overview." +--- + +# AOD Status Skill + +## Purpose + +Utility skill for the AOD Lifecycle. Provides an on-demand snapshot of the project backlog by regenerating BACKLOG.md from GitHub Issues and displaying a summary of items per lifecycle stage. + +No governance gates — this is a read-only utility command. + +## How It Works + +### Step 1: Regenerate BACKLOG.md + +Run the backlog regeneration script with JSON output mode: + +```bash +bash .aod/scripts/bash/backlog-regenerate.sh --json +``` + +**Parse the JSON output** to extract: +- `file`: path to regenerated BACKLOG.md +- `total`: total number of GitHub Issues +- `stages`: object with counts per stage (`discover`, `define`, `plan`, `build`, `deliver`, `untracked`) + +**If the script fails or `gh` is unavailable**: Display a warning and attempt to read the existing BACKLOG.md file instead. If no BACKLOG.md exists either, report that no backlog data is available. + +### Step 2: Display Stage Summary + +Present a formatted summary table: + +``` +AOD LIFECYCLE STATUS + +| Stage | Count | +|----------|-------| +| Discover | {n} | +| Define | {n} | +| Plan | {n} | +| Build | {n} | +| Deliver | {n} | +| Untracked| {n} | +|----------|-------| +| Total | {n} | + +BACKLOG.md regenerated at {file_path}. +``` + +### Step 3: Show Active Feature Context (Optional) + +If the current git branch matches a feature pattern (`NNN-*`), display the active feature context: + +1. Get branch: `git branch --show-current` +2. Extract NNN prefix +3. Check for `specs/{NNN}-*/` directory +4. If found, read spec.md/plan.md/tasks.md frontmatter to show approval status: + +``` +Active Feature: {NNN}-{name} + spec.md: {PM approved / not approved / missing} + plan.md: {dual approved / not approved / missing} + tasks.md: {triple approved / not approved / missing} +``` + +If not on a feature branch, skip this section. + +## Edge Cases + +- **`gh` CLI unavailable**: Warn and fall back to reading existing BACKLOG.md (may be stale) +- **No GitHub remote**: Same as above — graceful degradation +- **Empty backlog**: Display the table with all zeros +- **Script not found**: Warn: "backlog-regenerate.sh not found at expected path" +- **Not on a feature branch**: Skip active feature context section + +## Integration + +### Reads +- `.aod/scripts/bash/backlog-regenerate.sh` — regeneration script (JSON mode) +- `docs/product/_backlog/BACKLOG.md` — fallback if script fails +- `specs/{NNN}-*/spec.md`, `plan.md`, `tasks.md` — active feature context + +### Invokes +- None (utility — no sub-commands or governance gates) + +### Updates +- `docs/product/_backlog/BACKLOG.md` — regenerated from GitHub Issues diff --git a/.claude/skills/pdl-idea/SKILL.md b/.claude/skills/pdl-idea/SKILL.md deleted file mode 100644 index 08caa04..0000000 --- a/.claude/skills/pdl-idea/SKILL.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -name: pdl-idea -description: "Capture a raw feature idea with ICE scoring into the Ideas Backlog. Use this skill when you need to capture ideas, log feature requests, record brainstorm output, or add items to the ideas backlog with ICE prioritization scoring." ---- - -# PDL Idea Capture Skill - -## Purpose - -Capture a new feature idea with ICE (Impact, Confidence, Effort) scoring and append it to the Ideas Backlog at `docs/product/_backlog/01_IDEAS.md`. - -## Inputs - -- **Idea description**: Natural language description of the feature idea (from user arguments) - -## Workflow - -### Step 1: Auto-Create Backlog Files - -Check if `docs/product/_backlog/01_IDEAS.md` exists. If not, create it with the table header: - -```markdown -# Ideas Backlog - -| ID | Idea | Source | Date | Status | ICE Score | -|----|------|--------|------|--------|-----------| -``` - -Also check if `docs/product/_backlog/02_USER_STORIES.md` exists. If not, create it with: - -```markdown -# Product Backlog - User Stories - -| Priority | Story ID | Story | ICE Score | Source | Status | -|----------|----------|-------|-----------|--------|--------| -``` - -### Step 2: Parse Input - -Extract the idea description from user arguments. If no description is provided, ask the user to describe their idea. - -### Step 3: Generate IDEA-NNN ID - -1. Read `docs/product/_backlog/01_IDEAS.md` -2. Parse the table to find all existing IDEA-NNN identifiers -3. Find the highest NNN value -4. Increment by 1, zero-pad to 3 digits -5. If no existing entries, start at IDEA-001 - -### Step 4: Capture Source - -Use AskUserQuestion to determine the idea source: - -``` -Question: "Where did this idea come from?" -Options: - - Brainstorm: "Generated during a brainstorming or planning session" - - Customer Feedback: "Reported by a customer or based on user research" - - Team Idea: "Suggested by a team member during development" - - User Request: "Directly requested by a user or stakeholder" -``` - -### Step 5: ICE Scoring - -Present the ICE scoring quick-assessment table using AskUserQuestion. Ask each dimension separately: - -#### Impact — "How much value does this deliver to users?" - -``` -Options: - - High (9): "Transformative — significant user value" - - Medium (6): "Solid improvement — meaningful but incremental" - - Low (3): "Minor enhancement — small quality-of-life fix" -``` - -Allow the user to select "Other" to provide a custom numeric value (1-10). - -#### Confidence — "How sure are we this will succeed?" - -``` -Options: - - High (9): "Proven pattern — strong evidence it will work" - - Medium (6): "Some unknowns — reasonable confidence with gaps" - - Low (3): "Speculative — significant uncertainty" -``` - -Allow the user to select "Other" to provide a custom numeric value (1-10). - -#### Effort (Ease of Implementation) — "How easy is this to build?" - -``` -Options: - - High (9): "Days of work — straightforward implementation" - - Medium (6): "Weeks of work — moderate complexity" - - Low (3): "Months of work — significant engineering effort" -``` - -Allow the user to select "Other" to provide a custom numeric value (1-10). - -### Step 6: Compute ICE Total - -``` -ICE Total = Impact + Confidence + Effort -Range: 3-30 -``` - -### Step 7: Apply Auto-Defer Gate - -Determine the status based on the ICE total: - -- **Total < 12**: Set status to **"Deferred"** (auto-deferred — requires PM override via `/pdl.validate` to proceed) -- **Total >= 12**: Set status to **"Scoring"** - -### Step 8: Append to Ideas Backlog - -Append a new row to the table in `docs/product/_backlog/01_IDEAS.md`: - -``` -| IDEA-{NNN} | {idea_description} | {source} | {YYYY-MM-DD} | {status} | {total} (I:{impact} C:{confidence} E:{effort}) | -``` - -Use the Edit tool to append the row after the last existing table row (or after the header separator if the table is empty). - -### Step 9: Report Result - -Display the result to the user: - -``` -IDEA CAPTURED - -ID: IDEA-{NNN} -Idea: {description} -Source: {source} -Date: {YYYY-MM-DD} - -ICE Score: {total} (I:{impact} C:{confidence} E:{effort}) -Priority Tier: {tier} -Status: {status} - -{If Deferred: "This idea was auto-deferred (score < 12). Use `/pdl.validate IDEA-{NNN}` to request PM override."} -{If Scoring: "Next: Run `/pdl.validate IDEA-{NNN}` to submit for PM review, or continue capturing ideas with `/pdl.idea`."} -``` - -## ICE Scoring Reference - -### Quick-Assessment Anchors - -| Dimension | High (9) | Medium (6) | Low (3) | -|-----------|----------|------------|---------| -| **Impact** | Transformative | Solid improvement | Minor enhancement | -| **Confidence** | Proven pattern | Some unknowns | Speculative | -| **Effort (Ease)** | Days of work | Weeks of work | Months of work | - -### Priority Tiers - -| Score Range | Priority | Action | -|-------------|----------|--------| -| 25-30 | P0 (Critical) | Fast-track to development | -| 18-24 | P1 (High) | Queue for next sprint | -| 12-17 | P2 (Medium) | Consider when capacity allows | -| < 12 | Deferred | Auto-defer; requires PM override via `/pdl.validate` | - -### Auto-Defer Gate - -Ideas scoring below 12 are automatically deferred. This threshold catches ideas where all three dimensions score poorly (e.g., Low/Low/Low = 9). The PM can override this gate using `/pdl.validate IDEA-NNN`. - -## Edge Cases - -- **Empty table**: Start ID at IDEA-001 -- **No description provided**: Prompt user for idea description before proceeding -- **Custom ICE score outside 1-10**: Clamp to valid range (1 minimum, 10 maximum) -- **Backlog files missing**: Auto-create with headers (Step 1) -- **Duplicate idea text**: Allow it — different ideas may have similar descriptions; the ID is the unique identifier - -## Quality Checklist - -- [ ] Backlog files auto-created if missing -- [ ] IDEA-NNN ID generated correctly (sequential, zero-padded) -- [ ] Source captured from user selection -- [ ] ICE score computed correctly (additive I+C+E) -- [ ] Auto-defer gate applied (< 12 = Deferred) -- [ ] Row appended to 01_IDEAS.md with all fields -- [ ] Result reported with ICE breakdown and priority tier diff --git a/.claude/skills/pdl-run/SKILL.md b/.claude/skills/pdl-run/SKILL.md deleted file mode 100644 index 62d32aa..0000000 --- a/.claude/skills/pdl-run/SKILL.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -name: pdl-run -description: "Full product discovery flow in one command — captures idea, scores with ICE, validates with PM, and adds to product backlog. Use this skill when you need to run complete discovery, evaluate a new idea end-to-end, or go from raw idea to backlog-ready in one step." ---- - -# PDL Full Discovery Flow Skill - -## Purpose - -Execute the complete Product Discovery Lifecycle in a single flow: capture an idea, score it with ICE, validate with PM, and (on approval) add a user story to the product backlog. All logic is inlined — this skill does NOT invoke other skills via the Skill tool. - -## Inputs - -- **Idea description**: Natural language description of the feature idea (from user arguments) - -## Workflow - -### Step 1: Auto-Create Backlog Files - -Check if `docs/product/_backlog/01_IDEAS.md` exists. If not, create it with the table header: - -```markdown -# Ideas Backlog - -| ID | Idea | Source | Date | Status | ICE Score | -|----|------|--------|------|--------|-----------| -``` - -Check if `docs/product/_backlog/02_USER_STORIES.md` exists. If not, create it with: - -```markdown -# Product Backlog - User Stories - -| Priority | Story ID | Story | ICE Score | Source | Status | -|----------|----------|-------|-----------|--------|--------| -``` - -### Step 2: Capture Idea (Inlined from pdl-idea) - -1. **Parse input**: Extract idea description from user arguments. If empty, ask the user to describe their idea. -2. **Generate IDEA-NNN ID**: Read `01_IDEAS.md`, find highest IDEA-NNN, increment by 1 (pad to 3 digits). Start at IDEA-001 if empty. -3. **Capture source**: Use AskUserQuestion: - ``` - Question: "Where did this idea come from?" - Options: - - Brainstorm: "Generated during a brainstorming or planning session" - - Customer Feedback: "Reported by a customer or based on user research" - - Team Idea: "Suggested by a team member during development" - - User Request: "Directly requested by a user or stakeholder" - ``` - -### Step 3: ICE Scoring (Inlined from pdl-idea) - -Present each ICE dimension using AskUserQuestion: - -#### Impact — "How much value does this deliver to users?" - -``` -Options: - - High (9): "Transformative — significant user value" - - Medium (6): "Solid improvement — meaningful but incremental" - - Low (3): "Minor enhancement — small quality-of-life fix" -``` - -#### Confidence — "How sure are we this will succeed?" - -``` -Options: - - High (9): "Proven pattern — strong evidence it will work" - - Medium (6): "Some unknowns — reasonable confidence with gaps" - - Low (3): "Speculative — significant uncertainty" -``` - -#### Effort (Ease of Implementation) — "How easy is this to build?" - -``` -Options: - - High (9): "Days of work — straightforward implementation" - - Medium (6): "Weeks of work — moderate complexity" - - Low (3): "Months of work — significant engineering effort" -``` - -Allow "Other" for custom numeric values (1-10) on each dimension. - -Compute total: **ICE Total = Impact + Confidence + Effort** (range 3-30). - -### Step 4: Auto-Defer Gate - -Determine status and append to Ideas Backlog: - -- **If total < 12**: Set status to "Deferred", append row to `01_IDEAS.md`, then **STOP the flow**: - -``` -IDEA CAPTURED — AUTO-DEFERRED - -ID: IDEA-{NNN} -Idea: {description} -Source: {source} -ICE Score: {total} (I:{impact} C:{confidence} E:{effort}) -Priority Tier: Deferred -Status: Deferred - -This idea was auto-deferred (score < 12). -To request PM override: `/pdl.validate IDEA-{NNN}` -To re-score with new information: `/pdl.score IDEA-{NNN}` -``` - -**Do not proceed to PM validation.** Exit the flow here. - -- **If total >= 12**: Set status to "Scoring", append row to `01_IDEAS.md`, continue to Step 5. - -### Step 5: PM Validation (Inlined from pdl-validate) - -Launch PM review using the Task tool with `product-manager` subagent_type: - -``` -Review this idea for product backlog inclusion: - -Idea: {idea_description} -ICE Score: {total} (I:{impact} C:{confidence} E:{effort}) -Priority Tier: {tier} -Current Status: Scoring -Auto-Deferred: No - -Evaluate: -1. Does this idea align with the product vision and roadmap? -2. Is the ICE scoring reasonable given the idea description? -3. Does this idea deliver meaningful user value? -4. Should this idea enter the product backlog as a user story? - -Respond with: -STATUS: [APPROVED | REJECTED] -RATIONALE: [Your detailed reasoning — 2-4 sentences] -``` - -**If PM REJECTS**: -1. Update idea status to "Rejected" in `01_IDEAS.md` -2. Display rejection result and exit: - -``` -PM VALIDATION: REJECTED - -ID: IDEA-{NNN} -PM Rationale: {rationale} - -Idea status updated to "Rejected" in 01_IDEAS.md. -``` - -**If PM APPROVES**: Continue to Step 6. - -### Step 6: User Story Generation (Inlined from pdl-validate) - -1. **Generate user story**: Transform idea into "As a [persona], I want [action], so that [benefit]" format. - - Default persona: "Template Adopter" if not evident from idea. -2. **Present for confirmation**: Use AskUserQuestion: - ``` - Options: - - Accept: "Save this user story as-is" - - Edit: "Let me modify the user story text" - ``` -3. **Generate US-NNN ID**: Read `02_USER_STORIES.md`, find highest US-NNN, increment by 1 (pad to 3 digits). Start at US-001 if empty. -4. **Determine priority**: Map ICE score to priority rank (P0→1, P1→2, P2→3). -5. **Append to 02_USER_STORIES.md**: - ``` - | {priority} | US-{NNN} | {user_story_text} | {ice_total} | IDEA-{NNN} | Ready for PRD | - ``` -6. **Update idea status** to "Validated" in `01_IDEAS.md`. - -### Step 7: Report Complete Flow Summary - -``` -PDL DISCOVERY COMPLETE - -Idea Captured: - ID: IDEA-{NNN} - Description: {description} - Source: {source} - -ICE Scoring: - Score: {total} (I:{impact} C:{confidence} E:{effort}) - Priority Tier: {tier} - -PM Validation: APPROVED - Rationale: {rationale} - -User Story Created: - ID: US-{NNN} - Story: "{user_story_text}" - Priority: {priority} - Status: Ready for PRD - -Next: Run `/triad.prd {topic}` to create a PRD from this user story. -``` - -## ICE Scoring Reference - -### Quick-Assessment Anchors - -| Dimension | High (9) | Medium (6) | Low (3) | -|-----------|----------|------------|---------| -| **Impact** | Transformative | Solid improvement | Minor enhancement | -| **Confidence** | Proven pattern | Some unknowns | Speculative | -| **Effort (Ease)** | Days of work | Weeks of work | Months of work | - -### Priority Tiers - -| Score Range | Priority | Action | -|-------------|----------|--------| -| 25-30 | P0 (Critical) | Fast-track to development | -| 18-24 | P1 (High) | Queue for next sprint | -| 12-17 | P2 (Medium) | Consider when capacity allows | -| < 12 | Deferred | Auto-defer; requires PM override via `/pdl.validate` | - -### Auto-Defer Gate - -Ideas scoring below 12 are automatically deferred and the flow STOPS. The user must explicitly run `/pdl.validate IDEA-NNN` to request PM override. - -## Edge Cases - -- **Empty idea description**: Prompt user for description before proceeding -- **Auto-deferred**: Flow stops after Step 4 — no PM validation, no user story -- **PM rejects**: Flow stops after Step 5 — no user story created -- **User edits story to empty**: Re-prompt for user story text -- **Custom ICE score outside 1-10**: Clamp to valid range (1 minimum, 10 maximum) -- **Backlog files missing**: Auto-create with headers (Step 1) - -## Quality Checklist - -- [ ] Backlog files auto-created if missing -- [ ] Idea captured with IDEA-NNN ID, source, and ICE score -- [ ] Auto-defer gate stops flow for score < 12 with guidance -- [ ] PM validation invoked via Task tool (product-manager subagent) -- [ ] Rejection stops flow and updates idea status -- [ ] Approval generates user story in proper format -- [ ] User story presented for confirmation before saving -- [ ] US-NNN ID generated and row appended to 02_USER_STORIES.md -- [ ] Idea status updated to Validated on approval -- [ ] Complete flow summary displayed with next step diff --git a/.claude/skills/pdl-validate/SKILL.md b/.claude/skills/pdl-validate/SKILL.md deleted file mode 100644 index beaa505..0000000 --- a/.claude/skills/pdl-validate/SKILL.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -name: pdl-validate -description: "PM validation gate for ideas — approves or rejects ideas for the product backlog with user story generation. Use this skill when you need to validate ideas, promote to backlog, run PM review on ideas, generate user stories, or override auto-deferred ideas." ---- - -# PDL Validate Skill - -## Purpose - -Submit an idea from `docs/product/_backlog/01_IDEAS.md` to a Product Manager agent for validation. On approval, generate a user story and add it to `docs/product/_backlog/02_USER_STORIES.md`. On rejection, update the idea status accordingly. - -## Inputs - -- **IDEA-NNN**: The identifier of the idea to validate (from user arguments) - -## Workflow - -### Step 1: Auto-Create Backlog Files - -Check if `docs/product/_backlog/01_IDEAS.md` exists. If not, create it with the table header: - -```markdown -# Ideas Backlog - -| ID | Idea | Source | Date | Status | ICE Score | -|----|------|--------|------|--------|-----------| -``` - -Check if `docs/product/_backlog/02_USER_STORIES.md` exists. If not, create it with: - -```markdown -# Product Backlog - User Stories - -| Priority | Story ID | Story | ICE Score | Source | Status | -|----------|----------|-------|-----------|--------|--------| -``` - -### Step 2: Parse Input - -Extract the IDEA-NNN identifier from user arguments. Validate the format matches `IDEA-` followed by a 3-digit number. If invalid or missing, display usage: `Usage: /pdl.validate IDEA-NNN` - -### Step 3: Read and Find Idea - -Read `docs/product/_backlog/01_IDEAS.md` and find the row matching the given IDEA-NNN. - -**Error conditions** — display error and exit: -- Idea not found: `"Error: IDEA-{NNN} not found in 01_IDEAS.md"` -- Status is "Rejected": `"Error: IDEA-{NNN} has already been rejected by PM"` -- Status is "Validated": `"Error: IDEA-{NNN} has already been validated — see 02_USER_STORIES.md"` - -### Step 4: Display Idea for Review - -Show the idea details before launching PM review: - -``` -IDEA FOR PM VALIDATION - -ID: IDEA-{NNN} -Idea: {description} -Source: {source} -Date: {date} -Status: {status} -ICE Score: {total} (I:{impact} C:{confidence} E:{effort}) -Priority Tier: {tier} -Auto-Deferred: {Yes if status is Deferred, otherwise No} -``` - -### Step 5: Launch PM Validation - -Use the Task tool with `product-manager` subagent_type to perform the PM review: - -``` -Review this idea for product backlog inclusion: - -Idea: {idea_description} -ICE Score: {total} (I:{impact} C:{confidence} E:{effort}) -Priority Tier: {tier} -Current Status: {status} -Auto-Deferred: {yes/no} - -Evaluate: -1. Does this idea align with the product vision and roadmap? -2. Is the ICE scoring reasonable given the idea description? -3. Does this idea deliver meaningful user value? -4. Should this idea enter the product backlog as a user story? - -If auto-deferred (score < 12), provide additional justification for why this idea -should or should not override the auto-defer gate. - -Respond with: -STATUS: [APPROVED | REJECTED] -RATIONALE: [Your detailed reasoning — 2-4 sentences] -``` - -### Step 6: Handle Rejection - -If PM returns **REJECTED**: - -1. Update idea status to **"Rejected"** in `01_IDEAS.md` using Edit tool -2. Display the rejection: - -``` -PM VALIDATION: REJECTED - -ID: IDEA-{NNN} -Idea: {description} -PM Rationale: {rationale} - -The idea has been marked as Rejected in 01_IDEAS.md. -To re-submit: re-score with `/pdl.score IDEA-{NNN}` (this re-opens the idea), then run `/pdl.validate IDEA-{NNN}` again. -``` - -3. Exit the workflow. - -### Step 7: Handle Approval — Generate User Story - -If PM returns **APPROVED**: - -#### 7a. Generate User Story - -Transform the idea description into user story format: - -``` -"As a [persona], I want [action], so that [benefit]" -``` - -**Transformation rules**: -- **Persona**: Extract from the idea description if evident. Default to "Template Adopter" if no persona is specified or inferrable. -- **Action**: Extract the core action or capability from the idea description. -- **Benefit**: Infer the user benefit from the context and idea description. - -#### 7b. Present for User Confirmation - -Display the generated user story to the user and ask for confirmation: - -``` -GENERATED USER STORY - -"As a {persona}, I want {action}, so that {benefit}." - -Is this user story accurate? You can edit it before saving. -``` - -Use AskUserQuestion: -``` -Options: - - Accept: "Save this user story as-is" - - Edit: "Let me modify the user story text" -``` - -If the user selects "Edit", accept their modified version. If they provide it via "Other", use their text. - -#### 7c. Generate US-NNN ID - -1. Read `docs/product/_backlog/02_USER_STORIES.md` -2. Parse the table to find all existing US-NNN identifiers -3. Find the highest NNN value -4. Increment by 1, zero-pad to 3 digits -5. If no existing entries, start at US-001 - -#### 7d. Determine Priority - -Map ICE score to priority rank: -- P0 (25-30): Priority = 1 -- P1 (18-24): Priority = 2 -- P2 (12-17): Priority = 3 -- Deferred (<12, PM override): Priority = 4 - -If other entries exist, assign the next available rank at the appropriate tier level. - -### Step 8: Write Backlog Entries - -#### 8a. Append to User Stories - -Append a new row to `docs/product/_backlog/02_USER_STORIES.md`: - -``` -| {priority} | US-{NNN} | {user_story_text} | {ice_total} | IDEA-{NNN} | Ready for PRD | -``` - -#### 8b. Update Idea Status - -Update the idea status in `01_IDEAS.md` from current status to **"Validated"** using Edit tool. - -#### 8c. Document PM Override (if applicable) - -If the idea was previously "Deferred" (auto-deferred with score < 12) and PM approved it: - -After the user stories table in `02_USER_STORIES.md`, append a note: - -```markdown - -> **PM Override — US-{NNN}**: IDEA-{NNN} was auto-deferred (ICE score {total} < 12) but approved by PM. Rationale: {pm_rationale} -``` - -### Step 9: Report Result - -``` -PM VALIDATION: APPROVED - -ID: IDEA-{NNN} -Idea: {description} -PM Rationale: {rationale} - -User Story Created: - ID: US-{NNN} - Story: "{user_story_text}" - Priority: {priority} - Status: Ready for PRD - -Idea status updated to "Validated" in 01_IDEAS.md. -User story added to 02_USER_STORIES.md. - -Next: Run `/triad.prd {topic}` to create a PRD from this user story. -``` - -## ICE Scoring Reference - -### Priority Tiers - -| Score Range | Priority | Action | -|-------------|----------|--------| -| 25-30 | P0 (Critical) | Fast-track to development | -| 18-24 | P1 (High) | Queue for next sprint | -| 12-17 | P2 (Medium) | Consider when capacity allows | -| < 12 | Deferred | Auto-defer; requires PM override via `/pdl.validate` | - -### Auto-Defer Gate - -Ideas scoring below 12 are automatically deferred. This skill allows PM to override the auto-defer gate. When an override occurs, the PM rationale is documented alongside the user story. - -## Edge Cases - -- **IDEA-NNN not found**: Display error with the ID that was searched for -- **Already Rejected**: Cannot re-validate directly — user must re-score first with `/pdl.score` (which re-opens it), then run `/pdl.validate` again -- **Already Validated**: Cannot re-validate — user story already exists -- **PM timeout or error**: Report the error and suggest retrying -- **User edits story to empty string**: Re-prompt for user story text -- **Backlog files missing**: Auto-create with headers (Step 1) -- **PM approves auto-deferred idea**: Document override rationale in backlog - -## Quality Checklist - -- [ ] Backlog files auto-created if missing -- [ ] IDEA-NNN parsed, found, and eligible for validation -- [ ] PM agent invoked with idea details via Task tool -- [ ] Rejection: Status updated to Rejected in 01_IDEAS.md -- [ ] Approval: User story generated in proper format -- [ ] Approval: User story presented for user confirmation -- [ ] Approval: US-NNN ID generated correctly -- [ ] Approval: Row appended to 02_USER_STORIES.md -- [ ] Approval: Idea status updated to Validated in 01_IDEAS.md -- [ ] PM override documented if idea was auto-deferred -- [ ] Result reported with next step guidance diff --git a/.claude/skills/triad/architect-review.md b/.claude/skills/triad/architect-review.md index ebd41f4..fcccb0f 100644 --- a/.claude/skills/triad/architect-review.md +++ b/.claude/skills/triad/architect-review.md @@ -116,8 +116,8 @@ Provide your review in this exact format: ## Usage This skill is invoked during Triad governance workflows: -- `/triad.plan` - After plan creation (parallel with PM) -- `/triad.tasks` - After task generation (parallel with PM and Tech-Lead) -- `/triad.implement` - At checkpoint intervals +- `/aod.project-plan` - After plan creation (parallel with PM) +- `/aod.tasks` - After task generation (parallel with PM and Tech-Lead) +- `/aod.build` - At checkpoint intervals The skill runs in parallel with PM review when context forking is enabled. diff --git a/.claude/skills/triad/pm-review.md b/.claude/skills/triad/pm-review.md index 89233f4..57425e0 100644 --- a/.claude/skills/triad/pm-review.md +++ b/.claude/skills/triad/pm-review.md @@ -100,8 +100,8 @@ Provide your review in this exact format: ## Usage This skill is invoked during Triad governance workflows: -- `/triad.specify` - After spec creation -- `/triad.plan` - After plan creation -- `/triad.tasks` - After task generation +- `/aod.spec` - After spec creation +- `/aod.project-plan` - After plan creation +- `/aod.tasks` - After task generation The skill runs in parallel with Architect review when context forking is enabled. diff --git a/.claude/skills/triad/teamlead-review.md b/.claude/skills/triad/teamlead-review.md index a8a10c1..d4b6493 100644 --- a/.claude/skills/triad/teamlead-review.md +++ b/.claude/skills/triad/teamlead-review.md @@ -127,6 +127,6 @@ Provide your review in this exact format: ## Usage This skill is invoked during Triad governance workflows: -- `/triad.tasks` - After task generation (parallel with PM and Architect) +- `/aod.tasks` - After task generation (parallel with PM and Architect) The skill runs in parallel with PM and Architect reviews when context forking is enabled. diff --git a/.gitignore b/.gitignore index 159321d..8953b02 100644 --- a/.gitignore +++ b/.gitignore @@ -110,6 +110,7 @@ prisma/dev.db* # But ignore local customizations that shouldn't be in template .aod/local/ .aod/*.lock +.aod/memory/github-project.json # ============================================================================ # Product-led specific diff --git a/CHANGELOG.md b/CHANGELOG.md index 45d9aaf..3d5ba9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 --- +## [5.0.0] - 2026-02-09 + +### BREAKING CHANGES + +#### Unified `/aod.*` Command Namespace (Feature 010) + +All lifecycle commands unified under `/aod.*` namespace. The dual namespace (`/pdl.*` + `/triad.*`) has been replaced with a single, consistent command set aligned with the 5-stage AOD lifecycle: Discover → Define → Plan → Build → Deliver. + +**Command Namespace Migration:** + +| Former Command | New Command | Stage | Notes | +|----------------|-------------|-------|-------| +| `/pdl.idea` | `/aod.discover` | Discover | Unified capture + score + validate | +| `/pdl.run` | `/aod.discover` | Discover | Full discovery flow | +| `/pdl.score` | `/aod.score` | Discover | Re-score existing idea | +| `/pdl.validate` | *(removed)* | — | Integrated into `/aod.discover` | +| `/triad.prd` | `/aod.define` | Define | Create PRD with Triad sign-off | +| `/triad.specify` | `/aod.spec` | Plan | Create spec.md with PM sign-off | +| `/triad.plan` | `/aod.project-plan` | Plan | Create plan.md with PM+Architect sign-off | +| `/triad.tasks` | `/aod.tasks` | Plan | Create tasks.md with triple sign-off | +| `/triad.implement` | `/aod.build` | Build | Execute with Architect checkpoints | +| `/triad.close-feature` | `/aod.deliver` | Deliver | Close feature with retrospective | +| `/triad.clarify` | `/aod.clarify` | — | Resolve spec ambiguities | +| `/triad.analyze` | `/aod.analyze` | — | Cross-artifact consistency check | +| `/triad.checklist` | `/aod.checklist` | — | Quality checklist | +| `/triad.constitution` | `/aod.constitution` | — | Governance principles | + +**New Commands:** +- `/aod.plan` — Intelligent router that auto-detects which Plan sub-step (spec → project-plan → tasks) comes next +- `/aod.status` — Backlog snapshot and lifecycle stage summary + +**Migration**: Replace all `/pdl.*` and `/triad.*` commands with their `/aod.*` equivalents. See `docs/guides/AOD_MIGRATION.md` for detailed instructions. + +### Added — AOD Lifecycle Formalization (Feature 010) + +**Lifecycle Tracking:** +- GitHub Issues track feature lifecycle stage via `stage:*` labels +- `BACKLOG.md` auto-regenerated from GitHub Issues grouped by lifecycle stage +- All `/aod.*` commands auto-update Issue labels on stage transitions +- New scripts: `github-lifecycle.sh`, `backlog-regenerate.sh`, `migrate-backlog.sh` + +**Governance Tiers:** +- **Light** (2 gates): Prototype/exploration mode +- **Standard** (6 gates, default): Production features +- **Full** (all gates): Regulated environments + +**Documentation:** +- `docs/guides/AOD_LIFECYCLE.md` — Full lifecycle documentation +- `docs/guides/AOD_LIFECYCLE_GUIDE.md` — Practical usage guide +- `docs/guides/AOD_QUICKSTART.md` — Quick start for new adopters +- `docs/guides/AOD_MIGRATION.md` — Migration guide from old namespaces +- `docs/guides/AOD_INFOGRAPHIC.md` — Visual lifecycle diagram + +**Skill Consolidation:** +- 9 old skills (`pdl-*`, `prd-create`, `spec-validator`, `architecture-validator`, `implementation-checkpoint`, `thinking-lens`) replaced by 10 unified `aod-*` skills +- Skills are now self-contained with no cross-skill Skill tool coupling + +### Added — GitHub Projects Lifecycle Board (Feature 011) + +Visual kanban board integration via GitHub Projects (v2) with 5 columns matching AOD lifecycle stages. + +**Board Functions:** +- `aod_gh_setup_board` — One-time board creation with 5 Status columns +- `aod_gh_add_to_board` — Auto-add issues to board on creation +- `aod_gh_move_on_board` — Auto-move issues between columns on stage transitions +- `aod_gh_check_board` — Board availability check with session-scoped caching + +**Integration:** +- `/aod.discover` auto-adds issue to "Discover" column +- `/aod.define`, `/aod.spec`, `/aod.build`, `/aod.deliver` auto-move issues to matching columns +- 7-level graceful degradation — board failures never block core workflow + +**Prerequisites:** +- GitHub CLI (`gh`) v2.40+ +- OAuth scope: `project` (add via `gh auth refresh -s project`) + +### Removed +- All 14 `/pdl.*` and `/triad.*` command files +- 9 old skill directories (`pdl-*`, `prd-create`, `spec-validator`, etc.) +- 3 old guide files (`PDL_TRIAD_INFOGRAPHIC.md`, `PDL_TRIAD_LIFECYCLE.md`, `PDL_TRIAD_QUICKSTART.md`) + +--- + ## [4.0.0] - 2026-02-08 ### BREAKING CHANGES @@ -220,23 +303,25 @@ See [MIGRATION.md](MIGRATION.md) for detailed upgrade instructions from v1.x to ## Version Comparison -| Feature | v1.0.0 | v1.1.0 | v2.0.0 | v2.1.0 | v3.0.0 | v4.0.0 | -|---------|--------|--------|--------|--------|--------|--------| -| Command Set | Triad + Vanilla | Triad + Vanilla | Triad + Vanilla | Triad + Vanilla | Triad only (10 commands) | Triad only (10 commands) | -| Triad Governance | Sequential | Sequential | Parallel | Parallel | Parallel | Parallel | -| CLAUDE.md Size | 192 lines | 70 lines | 70 lines | 70 lines | ~80 lines | ~80 lines | -| Context Loading | Manual | @-references | @-references | @-references | @-references | @-references | -| Version Detection | - | - | Automatic | Automatic | Automatic | Automatic | -| Feature Flags | - | - | Supported | Supported | Supported | Supported | -| Degradation | - | - | Graceful | Graceful | Graceful | Graceful | -| Agent Count | 13 | 13 | 13 | 13 (refactored) | 13 | 13 | -| Agent Line Reduction | - | - | - | 58% | 58% | 58% | -| Skill Tool Coupling | - | - | 3 cross-calls | 3 cross-calls | 0 (self-contained) | 0 (self-contained) | -| Branding | Spec Kit | Spec Kit | Spec Kit | Spec Kit | Spec Kit | AOD Kit | -| Thinking Lenses | 5 | 5 | 5 | 5 | 5 | 8 | +| Feature | v1.0.0 | v1.1.0 | v2.0.0 | v2.1.0 | v3.0.0 | v4.0.0 | **v5.0.0** | +|---------|--------|--------|--------|--------|--------|--------|--------| +| Command Set | Triad + Vanilla | Triad + Vanilla | Triad + Vanilla | Triad + Vanilla | Triad only (10) | Triad only (10) | **AOD unified (16)** | +| Namespace | /speckit + /triad | /speckit + /triad | /speckit + /triad | /speckit + /triad | /triad + /pdl | /triad + /pdl | **/aod.*** | +| Triad Governance | Sequential | Sequential | Parallel | Parallel | Parallel | Parallel | Parallel | +| Governance Tiers | - | - | - | - | - | - | **Light/Standard/Full** | +| CLAUDE.md Size | 192 lines | 70 lines | 70 lines | 70 lines | ~80 lines | ~80 lines | ~80 lines | +| Context Loading | Manual | @-references | @-references | @-references | @-references | @-references | @-references | +| Version Detection | - | - | Automatic | Automatic | Automatic | Automatic | Automatic | +| Degradation | - | - | Graceful | Graceful | Graceful | Graceful | Graceful (7 levels) | +| Agent Count | 13 | 13 | 13 | 13 (refactored) | 13 | 13 | 13 | +| Skill Tool Coupling | - | - | 3 cross-calls | 3 cross-calls | 0 (self-contained) | 0 (self-contained) | 0 (self-contained) | +| Branding | Spec Kit | Spec Kit | Spec Kit | Spec Kit | Spec Kit | AOD Kit | AOD Kit | +| Thinking Lenses | 5 | 5 | 5 | 5 | 5 | 8 | 14 | +| Lifecycle Tracking | - | - | - | - | - | - | **GitHub Issues + Board** | --- +[5.0.0]: https://github.com/davidmatousek/agentic-oriented-development-kit/compare/v4.0.0...v5.0.0 [4.0.0]: https://github.com/davidmatousek/product-led-spec-kit/compare/v3.0.0...v4.0.0 [3.0.0]: https://github.com/davidmatousek/product-led-spec-kit/compare/v2.1.0...v3.0.0 [2.1.0]: https://github.com/davidmatousek/product-led-spec-kit/compare/v2.0.0...v2.1.0 diff --git a/CLAUDE.md b/CLAUDE.md index 3e4868e..d442a3a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,7 @@ ## Core Constraints - **Product-Led**: Start with product vision, PRDs, and user stories - **Source of Truth**: `.aod/spec.md` -- **Validation Required**: Run `/triad.analyze` before PRs +- **Validation Required**: Run `/aod.analyze` before PRs - **Local-First**: Always supports local `.aod/` file workflows ## Git Workflow @@ -36,17 +36,17 @@ agentic-oriented-development-kit/ ## Commands **PDL workflow** (optional, before Triad): -- `/pdl.run` → `/pdl.idea` → `/pdl.score` → `/pdl.validate` +- `/aod.discover` → `/aod.discover` → `/aod.score` → `/aod.validate` **Triad workflow**: -- `/triad.prd` → `/triad.specify` → `/triad.plan` → `/triad.tasks` → `/triad.implement` +- `/aod.define` → `/aod.spec` → `/aod.project-plan` → `/aod.tasks` → `/aod.build` **Supporting commands**: -- `/triad.clarify` — Resolve spec ambiguities -- `/triad.analyze` — Cross-artifact consistency check -- `/triad.checklist` — Generate quality checklist -- `/triad.constitution` — Manage governance principles -- `/triad.close-feature` — Close completed feature +- `/aod.clarify` — Resolve spec ambiguities +- `/aod.analyze` — Cross-artifact consistency check +- `/aod.checklist` — Generate quality checklist +- `/aod.constitution` — Manage governance principles +- `/aod.deliver` — Close completed feature ## SDLC Triad Governance | Role | Defines | Authority | @@ -64,7 +64,7 @@ agentic-oriented-development-kit/ All deployments must go through the devops agent. Never deploy without verification. ## Key Principles -- **Vision First**: `/triad.prd` (includes vision) → spec → plan → tasks +- **Vision First**: `/aod.define` (includes vision) → spec → plan → tasks - **Triple Sign-off**: PM + Architect + Team-Lead approval on tasks.md - **Definition of Done**: 3-step validation before marking complete diff --git a/MIGRATION.md b/MIGRATION.md index 179e5a5..d7153bc 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -203,7 +203,7 @@ Copy "Commands" section to `.claude/rules/commands.md`: ## Triad Commands (Automatic Governance - RECOMMENDED) ```bash -/triad.prd # Create PRD with Triad validation (includes optional vision workshop) +/aod.define # Create PRD with Triad validation (includes optional vision workshop) [... rest of commands ...] ``` @@ -369,7 +369,7 @@ The SDLC Triad ensures Product-Architecture-Engineering alignment: ## Core Constraints - Product-Led: Start with product vision, PRDs, and user stories - Source of Truth: `.aod/spec.md` -- Validation Required: Run `/triad.analyze` before PRs +- Validation Required: Run `/aod.analyze` before PRs - Local-First: Always supports local `.aod/` file workflows ## Git Workflow diff --git a/README.md b/README.md index 51da7fc..2ce260e 100644 --- a/README.md +++ b/README.md @@ -1,141 +1,311 @@ -# Agentic Oriented Development Kit (AOD Kit) +
-**SDLC Triad governance template for AI agent-assisted development.** +# Agentic Oriented Development Kit -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](CHANGELOG.md) +**A governance-first development template with SDLC Triad collaboration** + +[![Version](https://img.shields.io/badge/version-5.0.0-blue.svg)](CHANGELOG.md) +[![Claude Code](https://img.shields.io/badge/Claude_Code-v2.1.16+-purple.svg)](https://claude.ai/claude-code) +[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) + +[Getting Started](#-quick-start) • +[Commands](#-commands) • +[How It Works](#-how-it-works) • +[Documentation](#-documentation) • +[Contributing](#-contributing) + +
--- -## What is AOD Kit? +## Why Agentic Oriented Development Kit? -The Agentic Oriented Development Kit (AOD Kit) is a governance template that brings structured software development lifecycle (SDLC) practices to AI agent-assisted workflows. It uses the **AOD Triad** -- a three-role governance methodology involving a Product Manager, Architect, and Team Lead -- to enforce sign-offs and quality gates at every phase of development. AOD Kit works with any AI coding agent and provides the scaffolding for turning product ideas into well-governed implementations. Whether you are a solo developer or a team, the Triad ensures nothing ships without proper review. +Building software with AI agents? **Governance matters.** Agentic Oriented Development Kit ensures your AI-assisted development follows proper product management principles with clear sign-offs at every stage. -> **Naming Note**: "AOD Triad" refers to the governance methodology (the three-role sign-off process). "AOD Kit" refers to this template repository that implements the methodology. +| Challenge | Solution | +|-----------|----------| +| AI agents making unauthorized decisions | **Triple sign-off** gates (PM → Architect → Team-Lead) | +| Specs drifting from product vision | **PM approval** required before any implementation | +| Technical debt from ungoverned changes | **Architect checkpoints** at every milestone | +| Unclear ownership and accountability | **SDLC Triad** with defined veto authority | --- -## Quick Start +## ✨ Features + + + + + + + + + + +
+ +### 🎯 AOD Governance +- PM-driven product vision and alignment +- Dual sign-off (PM + Architect) before implementation +- Feature specs linked to PRDs and OKRs + + + +### 🔺 SDLC Triad Framework +- **PM**: Defines What & Why +- **Architect**: Defines How +- **Team-Lead**: Defines When & Who + +
+ +### ⚡ Parallel Reviews (v2.0) +- Context forking for simultaneous reviews +- Triple sign-off executes in parallel +- Automatic result merging by severity + + + +### 🛠️ Modular Rules System +- Concise CLAUDE.md (~80 lines) +- Topic-specific rule files in `.claude/rules/` +- Zero merge conflicts + +
+ +--- + +## 🚀 Quick Start + +### Installation ```bash -# 1. Clone the template -git clone https://github.com/your-org/agentic-oriented-development-kit.git my-project +# Clone the template +git clone https://github.com/davidmatousek/agentic-oriented-development-kit.git my-project cd my-project -# 2. Initialize your project +# Run interactive setup make init +``` + +The init script will prompt for your project details and configure everything automatically. + +
+📋 Manual Setup + +If you prefer manual configuration: + +```bash +# Clone repository +git clone https://github.com/davidmatousek/agentic-oriented-development-kit.git my-project +cd my-project + +# Edit constitution with your project details +# Replace all {{PLACEHOLDER}} variables in: +vim .aod/memory/constitution.md +``` + +**Required variables:** +| Variable | Example | +|----------|---------| +| `{{PROJECT_NAME}}` | my-saas-platform | +| `{{PROJECT_DESCRIPTION}}` | AI-powered analytics dashboard | +| `{{TECH_STACK_DATABASE}}` | PostgreSQL | +| `{{TECH_STACK_VECTOR}}` | pgvector | +| `{{TECH_STACK_AUTH}}` | JWT | +| `{{RATIFICATION_DATE}}` | 2026-01-31 | + +
-# 3. Verify the setup +### Verify Installation + +```bash make check +``` + +### Your First Feature -# 4. Start your first feature -/triad.prd my-first-feature +```bash +# 1. Create your first PRD (includes optional vision workshop) +/aod.define user-authentication + +# 2. Follow the AOD Kit workflow +/aod.spec # Define requirements → PM sign-off +/aod.project-plan # Technical design → PM + Architect sign-off +/aod.tasks # Task breakdown → Triple sign-off +/aod.build # Execute with checkpoints ``` -That's it. The Triad workflow will guide you through PRD creation, specification, planning, task breakdown, and implementation -- with governance at every step. +--- + +## 📖 Commands + +### Triad Commands (Recommended) + +Full governance with automatic sign-offs at each stage. + +| Command | Description | Sign-offs | +|---------|-------------|-----------| +| `/aod.define ` | Create PRD (includes optional vision workshop) | Triad review | +| `/aod.spec` | Create spec.md | PM | +| `/aod.project-plan` | Create plan.md | PM + Architect | +| `/aod.tasks` | Create tasks.md | PM + Architect + Team-Lead | +| `/aod.build` | Execute with checkpoints | Architect gates | +| `/aod.deliver` | Close with doc updates | — | --- -## Solo Developer Quick Start +## 🔄 How It Works -**The Triad roles are three hats you wear, not three people.** +```mermaid +flowchart LR + subgraph "Phase 0: PRD" + A["/aod.define"] --> B{Triad Review} + end -As a solo developer, you play all three roles. The governance framework still provides value by forcing you to think through product (Why?), architecture (How?), and execution (When?) before writing code. + subgraph "Phase 1: Specify" + B --> C["/aod.spec"] + C --> D{PM Sign-off} + end -**When to use the full workflow**: Features that touch multiple systems, require careful planning, or have non-obvious technical decisions. + subgraph "Phase 2: Plan" + D --> E["/aod.project-plan"] + E --> F{PM + Architect} + end -**When to use the light workflow**: Small fixes, documentation updates, or well-understood changes where a quick `/triad.prd` and `/triad.specify` are sufficient. + subgraph "Phase 3: Tasks" + F --> G["/aod.tasks"] + G --> H{Triple Sign-off} + end -```bash -# Full workflow (recommended for new features) -/triad.prd user-authentication # Wear the PM hat: define what and why -/triad.specify # Research and write the spec -/triad.plan # Wear the Architect hat: define how -/triad.tasks # Wear the Team-Lead hat: define when -/triad.implement # Execute with checkpoints - -# Light workflow (for smaller changes) -/triad.prd quick-bugfix # Brief PRD -/triad.specify # Spec + implement + subgraph "Phase 4: Implement" + H --> I["/aod.build"] + I --> J[Architect Checkpoints] + end + + J --> K["/aod.deliver"] ``` +### Sign-off Requirements + +| Artifact | Required Approvals | Purpose | +|----------|-------------------|---------| +| `spec.md` | PM | Product alignment | +| `plan.md` | PM + Architect | Technical soundness | +| `tasks.md` | PM + Architect + Team-Lead | Execution readiness | + +### Veto Authority + +| Scenario | Who Can Veto | Grounds | +|----------|-------------|---------| +| PRD infrastructure claims | Architect | Contradicts baseline | +| PRD technical approach | Architect | Technically infeasible | +| PRD timeline estimate | Team-Lead | Ignores capacity | +| spec.md alignment | PM | Misaligned with vision | +| plan.md architecture | Architect | Violates principles | +| tasks.md timeline | Team-Lead | Unrealistic breakdown | + --- -## What's Included +## 📁 Project Structure ``` agentic-oriented-development-kit/ -├── .claude/ # Agent definitions, skills, and commands -│ ├── agents/ # PM, Architect, Team-Lead, and specialist agents -│ ├── commands/ # Triad workflow commands (/triad.*) -│ ├── rules/ # Governance rules and context loading -│ └── skills/ # Reusable agent skills -├── .aod/ # Source of truth for current feature -│ ├── spec.md # Feature specification (created by /triad.specify) -│ ├── plan.md # Implementation plan (created by /triad.plan) -│ ├── tasks.md # Task breakdown (created by /triad.tasks) -│ ├── memory/ # Constitution and institutional knowledge -│ ├── scripts/ # Governance automation scripts -│ └── templates/ # Document templates -├── docs/ # Product, architecture, standards, and guides -│ ├── product/ # Product vision, PRDs, user stories -│ ├── architecture/ # System design and deployment docs -│ ├── standards/ # Definition of Done, naming, collaboration -│ ├── core_principles/ # Thinking lenses (5 Whys, Pre-Mortem, etc.) -│ └── guides/ # Workflow and onboarding guides -├── specs/ # Feature-specific specs, research, and artifacts -├── scripts/ # Setup and validation scripts (init.sh, check.sh) -├── CLAUDE.md # AI agent context and project instructions -├── Makefile # Common commands (init, check, review-spec, etc.) -└── README.md # This file +├── .claude/ +│ ├── agents/ # 13 specialized agents +│ ├── skills/ # Automation capabilities +│ ├── commands/ # Triad commands +│ └── rules/ # Modular governance rules +│ ├── governance.md +│ ├── git-workflow.md +│ ├── deployment.md +│ └── ... +├── .aod/ +│ ├── spec.md # Feature specification +│ ├── plan.md # Technical design +│ ├── tasks.md # Task breakdown +│ └── memory/ +│ └── constitution.md # ← CUSTOMIZE THIS +├── docs/ +│ ├── product/ # Vision, PRDs, roadmaps +│ ├── architecture/ # System design, ADRs +│ ├── devops/ # Deployment guides +│ └── core_principles/ # Methodologies +├── specs/ # Per-feature specifications +├── CLAUDE.md # AI agent context +└── CHANGELOG.md # Version history ``` --- -## The SDLC Triad +## 🏛️ Core Principles -The AOD Triad is a lightweight governance framework ensuring Product-Architecture-Engineering alignment. +
+View all 11 governance principles -| Role | Defines | Authority | Key Questions | -|------|---------|-----------|---------------| -| **PM (Product Manager)** | What & Why | Scope and requirements | What problem are we solving? Why now? | -| **Architect** | How | Technical decisions | How should this be built? What are the constraints? | -| **Team-Lead** | When & Who | Timeline and assignments | When can we deliver? Who works on what? | +1. **General-Purpose Architecture** — Domain-agnostic, works with any workflow +2. **API-First Design** — API contracts before UI/MCP implementation +3. **Backward Compatibility** — 100% local `.aod/` file support +4. **Concurrency & Data Integrity** — ACID guarantees, task locking +5. **Privacy & Data Isolation** — Per-user/org isolation, encryption at rest +6. **Testing Excellence** — Mandatory test coverage (80% minimum) +7. **Definition of Done** — 3-step validation (Deployed, Tested, User Validated) +8. **Observability & Root Cause Analysis** — Five Whys methodology +9. **Git Workflow** — Feature branches only, never commit to main +10. **Product-AOD Alignment** — PM + Architect dual sign-off +11. **SDLC Triad Collaboration** — PM + Architect + Tech-Lead workflow -### Sign-off Requirements +> **Note:** These principles are universal. Customize only the System Architecture Constraints section in the constitution. + +
-| Artifact | Required Sign-offs | -|----------|-------------------| -| `spec.md` | PM | -| `plan.md` | PM + Architect | -| `tasks.md` | PM + Architect + Team-Lead | +--- -No artifact proceeds to the next phase without the required approvals. +## 📚 Documentation + +| Document | Purpose | +|----------|---------| +| [Constitution](.aod/memory/constitution.md) | Governance principles (customize this) | +| [CHANGELOG](CHANGELOG.md) | Version history | +| [MIGRATION](MIGRATION.md) | Upgrade guide | +| [Triad Workflow](docs/AOD_TRIAD.md) | Collaboration guide | --- -## Using with Other AI Agents +## 🤝 Contributing + +```bash +# Fork and clone +git clone https://github.com/YOUR_USERNAME/agentic-oriented-development-kit.git +cd agentic-oriented-development-kit -AOD Kit is optimized for Claude Code but the AOD Triad methodology works with any AI coding agent. The governance principles -- product-led thinking, structured sign-offs, and quality gates -- are universal patterns that improve AI-assisted development regardless of the tool. +# Create feature branch +git checkout -b feature/your-improvement -For **Cursor**, **GitHub Copilot**, or **Windsurf**: The `.aod/` directory structure and governance documents serve as context that any agent can read. You can adapt the Triad workflow by providing the relevant spec, plan, or task files as context to your agent of choice. The key is maintaining the sign-off discipline, even if the automation looks different. +# Make changes and submit PR +``` -If you are migrating from another agent workflow, start by adopting the `.aod/` file structure and the three-role review process. The specific commands (`/triad.*`) are Claude Code integrations, but the underlying methodology -- define What/Why, then How, then When/Who -- works everywhere. See the `docs/guides/` directory for adaptation examples. +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. --- -## Template Variables Reference +## 📄 License -AOD Kit uses template variables that you customize during setup. See [`.claude/README.md`](.claude/README.md) for the complete list of variables and configuration options. +This project is licensed under the MIT License — see [LICENSE](LICENSE) for details. --- -## Contributing +## 💬 Support -We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on filing issues, submitting pull requests, and our code of conduct. +- **Issues**: [GitHub Issues](https://github.com/davidmatousek/agentic-oriented-development-kit/issues) +- **Discussions**: [GitHub Discussions](https://github.com/davidmatousek/agentic-oriented-development-kit/discussions) +- **Public Template**: [agentic-oriented-development-kit](https://github.com/davidmatousek/agentic-oriented-development-kit) --- -## License +
+ +**[⬆ Back to Top](#agentic-oriented-development-kit)** + +Made with the SDLC Triad: PM + Architect + Team-Lead -This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. +
diff --git a/docs/AOD_TRIAD.md b/docs/AOD_TRIAD.md index ada92d3..242b944 100644 --- a/docs/AOD_TRIAD.md +++ b/docs/AOD_TRIAD.md @@ -1,51 +1,83 @@ -# SDLC Triad - Quick Reference Guide +# AOD Triad Governance - Quick Reference Guide -**Version**: 2.0.0 (Constitution v1.4.0 Principle XI) +**Version**: 3.0.0 (AOD Lifecycle Formalization) **Status**: Template --- -## What is the SDLC Triad? +## What is the AOD Triad? -**The SDLC Triad** is a lightweight collaboration framework ensuring Product-Architecture-Engineering alignment for all PRDs and specs. +**The AOD Triad** is the governance layer of the AOD Lifecycle, ensuring Product-Architecture-Engineering alignment at every stage boundary. While the AOD Lifecycle defines five stages (Discover, Define, Plan, Build, Deliver), the Triad provides the approval gates that control progression between them. **The Three Roles**: 1. **PM (product-manager)**: Defines **What** & **Why** (user value, business goals) 2. **Architect**: Defines **How** (technical approach, infrastructure baseline) 3. **Tech-Lead (team-lead)**: Defines **When** & **Who** (timeline, agent assignments) -**Purpose**: Prevent PRD technical inaccuracies through structured review and validation gates +**Purpose**: Govern stage transitions through structured review and validation gates, preventing misalignment between product intent and technical execution --- -## Complete Triad Workflow (Simple) +## Lifecycle Context + +The **AOD Lifecycle** defines 5 stages that every feature progresses through: + +``` +Discover → Define → Plan → Build → Deliver +``` + +The **Triad** operates as a governance layer at stage boundaries (gates), not as stages themselves: ``` -┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ │ │ │ │ │ │ │ │ │ -│ /triad.prd │ --> │/triad.specify│ --> │ /triad.plan │ --> │ /triad.tasks │ --> │/triad. │ -│ │ │ │ │ │ │ │ │ implement │ -│ │ │ │ │ │ │ │ │ │ -└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ - ↓ ↓ ↓ ↓ ↓ - PM + Arch + Research + PM + Arch PM + Arch + Arch checkpoints - Tech-Lead PM sign-off sign-off Tech-Lead during execution - validation sign-off - -Creates PRD Research phase → Creates plan.md Creates tasks.md Executes tasks -with Triad Creates spec.md with architecture with breakdown with reviews + Discover │ G1 │ Define │ G2 │ Plan │ G3 │ Build │ G4 │ Deliver + │ │ │ │ │ │ │ │ + Ideas, │gate│ PRD, │gate│ spec.md, │gate│ Execute │gate│ Close, + scoring │ │ research │ │ plan.md, │ │ tasks, │ │ verify, + │ │ │ │ tasks.md │ │ review │ │ document ``` -**Each step auto-validates before proceeding** ✅ +**Governance Tiers** (configurable per project): + +| Tier | Gates | Best For | +|------|-------|----------| +| **Light** | G2 (spec sign-off) + G3 (tasks sign-off) | Small features, quick iterations | +| **Standard** | G1 + G2 + G3 + G4 (6 checkpoints) | Most production features | +| **Full** | All gates with extended reviews | Critical infrastructure, security changes | + +See `docs/guides/AOD_LIFECYCLE.md` for the full lifecycle reference. + +--- + +## Complete Lifecycle with Triad Governance (Simple) + +``` + DISCOVER │ DEFINE │ PLAN │ BUILD │ DELIVER + │ │ │ │ +┌──────────────┐ │ ┌──────────────┐ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ ┌──────────────┐ +│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ +│ /aod.define │ │ │ /aod.spec │ │ │/aod.project- │ │ /aod.tasks │ │ /aod.build │ │ │ /aod.close │ +│ (PRD) │ │ │ (spec.md) │ │ │ plan │ │ (tasks.md) │ │ (execute) │ │ │ (deliver) │ +│ │ │ │ │ │ │ (plan.md) │ │ │ │ │ │ │ │ +└──────────────┘ │ └──────────────┘ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └──────────────┘ + ↓ │ ↓ │ ↓ ↓ ↓ │ ↓ + PM + Arch + G1 Research + G2 PM + Arch PM + Arch + Arch checkpts G4 Verify + + Tech-Lead PM sign-off sign-off Tech-Lead during exec document + validation sign-off (G3) + +Creates PRD Research → Creates plan.md Creates tasks Executes tasks Close feature +with Triad Creates spec.md with architecture with breakdown with reviews with docs +``` + +**Governance gates (G1-G4) auto-validate before stage transitions** ✅ --- ## Quick Start -### Creating a PRD with Triad +### Creating a PRD with Triad Governance ```bash -/triad.prd +/aod.define ``` **Auto-detects workflow type**: @@ -53,7 +85,7 @@ with Triad Creates spec.md with architecture with breakdown - Feature keywords (UI, component, API, feature) → Parallel Triad **What happens automatically**: -1. PM drafts PRD (via `/triad.prd`) +1. PM drafts PRD (via `/aod.define`) 2. Architect creates baseline (if infrastructure) or reviews (if feature) 3. Tech-Lead performs feasibility check with timeline estimate 4. Architect performs technical review @@ -160,7 +192,7 @@ docs/agents/architect/ ## Research Phase (Before Specification) -`/triad.specify` includes a **mandatory research phase** before generating the specification. This ensures specs are grounded in reality rather than assumptions. +`/aod.spec` includes a **mandatory research phase** before generating the specification. This ensures specs are grounded in reality rather than assumptions. ### What Gets Researched (in parallel) @@ -186,7 +218,7 @@ Creates `specs/{NNN}-*/research.md` with: ## Triple Sign-Off Requirements -**After `/triad.prd` completes, you must have**: +**After `/aod.define` completes, you must have**: ### For PRDs - ✅ **Architect baseline** (if infrastructure) or **Architect review** (if feature) @@ -194,18 +226,18 @@ Creates `specs/{NNN}-*/research.md` with: - ✅ **Architect technical review** with APPROVED verdict - ✅ **PM approval** (marks PRD as "Approved") -### For Spec.md (after `/triad.specify`) +### For Spec.md (after `/aod.spec`) - ✅ **Research phase completed**: KB, codebase, architecture, web research - ✅ **research.md created**: Findings documented - ✅ **PM sign-off**: Product alignment validated - ✅ **PM approval**: Spec ready for planning -### For Plan.md (after `/triad.plan`) +### For Plan.md (after `/aod.project-plan`) - ✅ **PM sign-off**: Feasibility validated - ✅ **Architect sign-off**: Architecture decisions validated - ✅ **PM approval**: Plan ready for tasks -### For Tasks.md (after `/triad.tasks`) +### For Tasks.md (after `/aod.tasks`) - ✅ **PM sign-off**: Prioritization validated - ✅ **Architect sign-off**: Technical approach validated - ✅ **Team-Lead sign-off**: Agent assignments and parallel execution optimized @@ -215,25 +247,26 @@ Creates `specs/{NNN}-*/research.md` with: --- -## Triad Commands +## AOD Lifecycle Commands (with Triad Governance) -### Automatic Triad (Recommended) +### Automatic Governance (Recommended) -**Complete Production Workflow** (ALL `/triad.*`): +**Complete Production Workflow** (ALL `/aod.*`): ```bash -/triad.prd # Create PRD with auto-Triad validation -/triad.specify # Create spec.md with auto PM sign-off -/triad.plan # Create plan.md with auto PM + Architect sign-off -/triad.tasks # Create tasks.md with auto PM + Architect + Team-Lead sign-off -/triad.implement # Execute with auto architect checkpoints +/aod.define # Define stage: Create PRD with auto-Triad validation +/aod.spec # Plan stage: Create spec.md with auto PM sign-off +/aod.project-plan # Plan stage: Create plan.md with auto PM + Architect sign-off +/aod.tasks # Plan stage: Create tasks.md with auto PM + Architect + Team-Lead sign-off +/aod.build # Build stage: Execute with auto architect checkpoints ``` -**Benefits of `/triad.*` Commands**: +**Benefits of `/aod.*` Commands**: +- ✅ Lifecycle stages with built-in governance gates - ✅ Automatic agent sign-off validation (no manual invocation) - ✅ Frontmatter auto-updated with verdicts - ✅ Blocking on CHANGES_REQUESTED (prevents proceeding with issues) - ✅ Constitution compliance enforced automatically -- ✅ Upgrade-safe wrapper architecture (open source commands stay pristine) +- ✅ Configurable governance tiers (Light, Standard, Full) --- @@ -250,7 +283,7 @@ cat docs/product/02_PRD/INDEX.md | grep {NNN} ### Run Cross-Artifact Analysis ```bash -/triad.analyze # Validates PRD-spec-plan-tasks alignment + Triad completeness +/aod.analyze # Validates PRD-spec-plan-tasks alignment + Triad completeness ``` --- @@ -259,11 +292,11 @@ cat docs/product/02_PRD/INDEX.md | grep {NNN} ### "PRD has inaccuracies" - **Cause**: PM didn't read architect baseline before drafting -- **Fix**: Re-run `/triad.prd` which will auto-invoke baseline first +- **Fix**: Re-run `/aod.define` which will auto-invoke baseline first ### "Timeline estimate unrealistic" - **Cause**: Tech-Lead didn't account for dependencies -- **Fix**: Re-run `/triad.tasks` after clarifying scope +- **Fix**: Re-run `/aod.tasks` after clarifying scope ### "Architect blocked PRD" - **Cause**: Technical infeasibility or inaccuracies ≥3 @@ -271,7 +304,7 @@ cat docs/product/02_PRD/INDEX.md | grep {NNN} ### "Triad cycle too slow (>4 hours)" - **Cause**: Rework loops from inaccuracies or missing baseline -- **Prevention**: Always run `/triad.prd` (auto-Triad) instead of manual PM draft +- **Prevention**: Always run `/aod.define` (auto-Triad governance) instead of manual PM draft --- @@ -280,7 +313,7 @@ cat docs/product/02_PRD/INDEX.md | grep {NNN} ### Example 1: Infrastructure PRD ```bash # User request: "Create PRD for production deployment setup" -/triad.prd production-deployment-setup +/aod.define production-deployment-setup # Auto-detects "production" + "deployment" → Infrastructure PRD # Runs Sequential Triad: @@ -296,7 +329,7 @@ cat docs/product/02_PRD/INDEX.md | grep {NNN} ### Example 2: Feature PRD ```bash # User request: "Create PRD for user dashboard feature" -/triad.prd user-dashboard-feature +/aod.define user-dashboard-feature # Auto-detects "feature" (no infrastructure keywords) → Feature PRD # Runs Parallel Triad: @@ -313,7 +346,7 @@ cat docs/product/02_PRD/INDEX.md | grep {NNN} ## Best Practices ### DO ✅ -- Use `/triad.prd` for automatic Triad workflow (recommended) +- Use `/aod.define` for automatic Triad governance (recommended) - Create architect baseline BEFORE PM drafts (infrastructure PRDs) - Use Tech-Lead timeline estimate (not PM guess) - Cross-check all infrastructure claims against baseline @@ -331,7 +364,7 @@ cat docs/product/02_PRD/INDEX.md | grep {NNN} ## Related Documentation **Constitutional Authority**: -- [Constitution, Principle XI](.aod/memory/constitution.md) - SDLC Triad Collaboration +- [Constitution, Principle XI](.aod/memory/constitution.md) - AOD Triad Governance **Detailed Guides**: - [TRIAD_COLLABORATION.md](standards/TRIAD_COLLABORATION.md) - Comprehensive guide @@ -343,14 +376,17 @@ cat docs/product/02_PRD/INDEX.md | grep {NNN} - [team-lead agent](.claude/agents/team-lead.md) - Feasibility + execution **Command Reference**: -- [/triad.prd](.claude/commands/triad.prd.md) - Auto-Triad PRD creation -- [/triad.specify](.claude/commands/triad.specify.md) - Spec creation with auto PM sign-off -- [/triad.plan](.claude/commands/triad.plan.md) - Plan creation with auto dual sign-off -- [/triad.tasks](.claude/commands/triad.tasks.md) - Task creation with auto triple sign-off -- [/triad.implement](.claude/commands/triad.implement.md) - Implementation with auto checkpoints +- [/aod.define](.claude/commands/aod.define.md) - Define stage: PRD creation with Triad governance +- [/aod.spec](.claude/commands/aod.spec.md) - Plan stage: Spec creation with auto PM sign-off +- [/aod.project-plan](.claude/commands/aod.project-plan.md) - Plan stage: Plan creation with auto dual sign-off +- [/aod.tasks](.claude/commands/aod.tasks.md) - Plan stage: Task creation with auto triple sign-off +- [/aod.build](.claude/commands/aod.build.md) - Build stage: Implementation with auto checkpoints + +**Lifecycle Reference**: +- [AOD_LIFECYCLE.md](guides/AOD_LIFECYCLE.md) - Full lifecycle stage reference --- -**Last Updated**: 2026-01-31 +**Last Updated**: 2026-02-09 **Maintained By**: Team Lead (workflow orchestration) **Review Trigger**: After every 5 PRDs or major process change diff --git a/docs/ARTICLE_SERIES.md b/docs/ARTICLE_SERIES.md index ff37768..8a70f8b 100644 --- a/docs/ARTICLE_SERIES.md +++ b/docs/ARTICLE_SERIES.md @@ -49,7 +49,7 @@ This document maps an 8-chapter article series to the template files that implem **Key Template Files**: - `.aod/` -- spec.md, plan.md, tasks.md structure -- `.claude/commands/triad.specify.md` -- The specify command workflow +- `.claude/commands/aod.spec.md` -- The spec command workflow --- @@ -68,8 +68,8 @@ This document maps an 8-chapter article series to the template files that implem **Theme**: Parallel execution through wave-based task orchestration. **Key Template Files**: -- `.claude/commands/triad.implement.md` -- Implementation workflow with checkpoints -- `.claude/commands/triad.tasks.md` -- Task breakdown with execution waves +- `.claude/commands/aod.build.md` -- Implementation workflow with checkpoints +- `.claude/commands/aod.tasks.md` -- Task breakdown with execution waves --- diff --git a/docs/INSTITUTIONAL_KNOWLEDGE.md b/docs/INSTITUTIONAL_KNOWLEDGE.md index 1e7b955..73df813 100644 --- a/docs/INSTITUTIONAL_KNOWLEDGE.md +++ b/docs/INSTITUTIONAL_KNOWLEDGE.md @@ -5,7 +5,7 @@ **Created**: {{PROJECT_START_DATE}} **Last Updated**: {{CURRENT_DATE}} -**Entry Count**: 0 / 20 (KB System Upgrade triggers at 20) +**Entry Count**: 2 / 20 (KB System Upgrade triggers at 20) **Last Review**: {{CURRENT_DATE}} **Status**: ✅ Manual mode (file-based) @@ -222,6 +222,100 @@ Application crashed on startup in production but worked perfectly in staging. Er --- +### Entry 4: Feature 010 — AOD Lifecycle Formalization Retrospective + +## [Process] - Large-Scale Namespace Unification with AI-Assisted Development + +**Date**: 2026-02-09 +**Context**: Feature 010 formalized the AOD Lifecycle (5 stages, governance tiers, unified `/aod.*` namespace) across 86 tasks, 140+ files, and 1,196+ reference occurrences. + +**Problem**: +- Two separate command namespaces (`/pdl.*` + `/triad.*`) for a single unified lifecycle created a false mental model +- Discovery stage lacked evidence collection, making prioritization decisions indefensible +- No feedback loop from delivery back to discovery (open-loop system) +- Plan stage required users to remember 3 sequential commands across sessions + +**Solution**: +1. **Unified namespace**: All lifecycle commands under `/aod.*` via systematic find-and-replace in 4 sub-waves (longest patterns first to prevent partial matches) +2. **Plan stage router**: `/aod.plan` auto-detects artifact state and delegates to correct sub-step +3. **Evidence-enriched discovery**: `/aod.discover` prompts for evidence alongside ICE scoring +4. **Delivery retrospective**: `/aod.deliver` captures metrics, surprises, and feeds new ideas back to discovery +5. **GitHub-backed tracking**: GitHub Issues with `stage:*` labels + auto-regenerated BACKLOG.md + +**Delivery Metrics**: +- Estimated: 2-3 sprints (Team-Lead review, assuming human-paced development) +- Actual: ~2.5 hours (AI-assisted, 6 implementation waves) +- Tasks: 86/86 complete +- PR: #9 (merged 2026-02-09) + +**What Surprised Us**: +- GitHub integration scope was more involved than expected (shared bash utilities, duplicate detection, pagination warnings, defensive parsing) +- Skill merge (3 PDL skills → aod-discover, ~675 lines) was the highest-risk single task but completed cleanly +- The scale of the rename (140+ files) was manageable thanks to wave-based approach with verification between waves +- Overall, planning phase accurately predicted the work — no blocking surprises + +**Key Learning**: Wave-based find-and-replace with longest-patterns-first ordering prevents partial match corruption. Always verify with grep between sub-waves. + +**Why This Matters**: +- Validates that AI-assisted development can compress multi-sprint features into hours when planning is thorough +- Demonstrates that the AOD methodology (discover → define → plan → build → deliver) works end-to-end +- The 6-wave agent strategy (A-F) kept context manageable across the large task set + +**Tags**: #process #namespace-unification #ai-assisted #retrospective #feature-010 + +### Related Files: +- `specs/010-aod-lifecycle-formalization/` - Full spec, plan, and tasks +- `docs/product/02_PRD/010-pdlc-sdlc-formalization-2026-02-08.md` - PRD +- `docs/guides/AOD_LIFECYCLE.md` - Primary lifecycle reference (created in this feature) +- `docs/guides/AOD_MIGRATION.md` - Command migration reference (created in this feature) + +--- + +### Entry 5: Feature 011 — GitHub Projects Lifecycle Board Retrospective + +## [Process] - GitHub Projects v2 Integration with Graceful Degradation + +**Date**: 2026-02-09 +**Context**: Feature 011 added a visual kanban board (GitHub Projects v2) over the existing Issue+label lifecycle tracking system, with 5 columns matching AOD lifecycle stages. + +**Problem**: +- Teams using AOD had no visual board view for daily standups or sprint planning +- The only way to see lifecycle state was to read BACKLOG.md or query Issues with label filters +- Needed to integrate with GitHub Projects v2 API without breaking existing workflows + +**Solution**: +1. **6 new bash functions** in `github-lifecycle.sh` (879 lines) with session-scoped caching +2. **7-level graceful degradation hierarchy** — board failures never block core lifecycle +3. **Automatic board sync** wired into 4 lifecycle commands (`/aod.define`, `/aod.spec`, `/aod.build`, `/aod.deliver`) +4. **First-run detection** with one-time setup hint and marker file suppression + +**Delivery Metrics**: +- Estimated: 12-17 hours (Team-Lead: optimistic 12h, realistic 15h, pessimistic 20h) +- Actual: ~3-4 hours (AI-assisted, 2 main commits + 1 fix) +- Tasks: 22/22 complete (T003 removed during planning) +- PR: #12 + +**What Surprised Us**: +- Had to re-authenticate `gh` CLI and run a setup script to actually create the board — the `project` OAuth scope wasn't included by default +- The jq parse bug with control characters in issue body JSON was unexpected — `gh project item-add` output became unparseable when the issue body contained newlines + +**Key Learning**: When integrating with GitHub's Projects v2 API, always account for authentication scope requirements (`gh auth refresh -s project`) as a first-class setup step. Users will need explicit instructions. Also, always handle JSON output from `gh` commands defensively — issue bodies can contain arbitrary characters that break jq parsing. + +**Why This Matters**: +- Validates the "view layer, not load-bearing" architecture principle — board never blocks core workflow +- Demonstrates that graceful degradation with 7 explicit levels makes integrations resilient +- The re-authentication requirement highlights the importance of clear first-run setup docs for upstream users + +**Tags**: #process #github-projects #api-integration #graceful-degradation #retrospective #feature-011 + +### Related Files: +- `specs/011-github-projects-lifecycle/` — Full spec, plan, and tasks +- `docs/product/02_PRD/011-github-projects-lifecycle-board-2026-02-09.md` — PRD +- `.aod/scripts/bash/github-lifecycle.sh` — Implementation (board functions) +- `specs/011-github-projects-lifecycle/quickstart.md` — User-facing setup guide + +--- + ## Entry Templates by Category ### [Architecture] Template diff --git a/docs/guides/PDL_TRIAD_INFOGRAPHIC.md b/docs/guides/AOD_INFOGRAPHIC.md similarity index 54% rename from docs/guides/PDL_TRIAD_INFOGRAPHIC.md rename to docs/guides/AOD_INFOGRAPHIC.md index 3d804ef..9ba971e 100644 --- a/docs/guides/PDL_TRIAD_INFOGRAPHIC.md +++ b/docs/guides/AOD_INFOGRAPHIC.md @@ -1,21 +1,21 @@ -# PDL + Triad Infographic +# AOD Lifecycle Infographic -**Version**: 1.0.0 +**Version**: 2.0.0 **Related**: -- [PDL + Triad Quickstart](PDL_TRIAD_QUICKSTART.md) -- Full onboarding guide -- [PDL + Triad Lifecycle](PDL_TRIAD_LIFECYCLE.md) -- Stage-by-stage deep reference -- [SDLC Triad Reference](../AOD_TRIAD.md) -- Comprehensive Triad documentation +- [AOD Quickstart](AOD_QUICKSTART.md) -- Quick onboarding guide +- [AOD Lifecycle Guide](AOD_LIFECYCLE_GUIDE.md) -- Stage-by-stage deep reference +- [SDLC Triad Reference](../AOD_TRIAD.md) -- Governance layer documentation --- ``` +==============================================================================================+ -|| PDL + TRIAD: SPEC-DRIVEN DEVELOPMENT WITH GOVERNANCE || -|| End-to-End Feature Lifecycle || +|| AOD: AGENTIC ORIENTED DEVELOPMENT LIFECYCLE || +|| End-to-End Feature Lifecycle || +==============================================================================================+ - TRIAD ROLES + TRIAD GOVERNANCE LAYER (configurable — Light / Standard / Full) +---------------------------------------------------------------------------+ | [PM] What & Why: Scope & requirements | | [Architect] How: Technical decisions | @@ -23,73 +23,82 @@ +---------------------------------------------------------------------------+ ================================================================================================ - PRODUCT DISCOVERY LIFECYCLE (PDL) Commands: /pdl.run /pdl.idea + STAGE 1: DISCOVER Command: /aod.discover ================================================================================================ - /pdl.run + /aod.discover | v +-----------+ +--------------+ +------------------+ +------------------+ - | Capture | ---> | Score (ICE) | ---> | Validate | ---> | Product Backlog | - | Idea | | | | (PM Gate) | | | + | Capture | ---> | Score (ICE) | ---> | Evidence | ---> | PM Validation | + | Idea | | | | Prompt | | (tier-dependent) | +-----------+ +--------------+ +------------------+ +------------------+ | | | | v v v v - 01_IDEAS.md ICE Dimensions PM Decision 02_USER_STORIES.md - +-----------+ +-----------------+ - | Impact 1-10 | | Score < 12 |---> Auto-deferred - | Confidence 1-10 | | Score >= 12 |---> Proceed to Triad - | Effort 1-10 | | Score 25+ |---> P0 Fast-track - +-----------+ +-----------------+ + GitHub Issue ICE Dimensions Evidence Capture PM Decision + stage:discover +-----------+ +-----------------+ + | Impact 1-10 | | Score < 12 |---> Auto-deferred + | Confidence 1-10 | | Score >= 12 |---> Proceed + | Effort 1-10 | | Score 25+ |---> P0 Fast-track + +-----------+ +-----------------+ ================================================================================================ - ========================= HANDOFF: Ready for PRD ============================= + STAGE 2: DEFINE Command: /aod.define ================================================================================================ - TRIAD GOVERNANCE WORKFLOW Commands: /triad.* -================================================================================================ - - PHASE 1: PRD /triad.prd + /aod.define +-----------------------------------------------------------------------+ - | PM drafts --> Architect + Team-Lead review --> PM finalizes | + | PM drafts PRD --> Architect + Team-Lead review --> PM finalizes | | Output: docs/product/02_PRD/{NNN}-{topic}-{date}.md | +-----------------------------------------------------------------------+ +-----------------------------------------------------------------+ - | Sign-off: [PM] [Architect] [Team-Lead] TRIPLE SIGN-OFF | + | Gate: [PM] [Architect] [Team-Lead] TRIPLE SIGN-OFF | +-----------------------------------------------------------------+ | v - PHASE 2: Specify /triad.specify + +================================================================================================ + STAGE 3: PLAN Command: /aod.plan +================================================================================================ + + /aod.plan (router — auto-detects sub-step) + + SUB-STEP 1: Specification /aod.spec (via /aod.plan) +-----------------------------------------------------------------------+ | Research (KB + Codebase + Architecture + Web) --> Generate spec | - | Output: specs/{NNN}-feature/spec.md | + | Output: .aod/spec.md | +-----------------------------------------------------------------------+ +-----------------------------------------------------------------+ - | Sign-off: [PM] PM SIGN-OFF | + | Gate: [PM] PM SIGN-OFF | +-----------------------------------------------------------------+ | v - PHASE 3: Plan /triad.plan + SUB-STEP 2: Architecture Plan /aod.project-plan (via /aod.plan) +-----------------------------------------------------------------------+ | Architecture decisions, API contracts, data models | - | Output: specs/{NNN}-feature/plan.md | + | Output: .aod/plan.md | +-----------------------------------------------------------------------+ +-----------------------------------------------------------------+ - | Sign-off: [PM] [Architect] DUAL SIGN-OFF | + | Gate: [PM] [Architect] DUAL SIGN-OFF | +-----------------------------------------------------------------+ | v - PHASE 4: Tasks /triad.tasks + SUB-STEP 3: Task Breakdown /aod.tasks (via /aod.plan) +-----------------------------------------------------------------------+ | Task breakdown, agent assignments, parallel execution waves | - | Output: specs/{NNN}-feature/tasks.md + agent-assignments.md | + | Output: .aod/tasks.md + agent-assignments.md | +-----------------------------------------------------------------------+ +-----------------------------------------------------------------+ - | Sign-off: [PM] [Architect] [Team-Lead] TRIPLE SIGN-OFF | + | Gate: [PM] [Architect] [Team-Lead] TRIPLE SIGN-OFF | +-----------------------------------------------------------------+ | v - PHASE 5: Implement /triad.implement + +================================================================================================ + STAGE 4: BUILD Command: /aod.build +================================================================================================ + + /aod.build +-----------------------------------------------------------------------+ | Wave 1: [Agent] [Agent] [Agent] (parallel) | | +----- Architect checkpoint -----+ | @@ -98,21 +107,30 @@ | Wave 3: [Agent] (sequential) | +-----------------------------------------------------------------------+ +-----------------------------------------------------------------+ - | Sign-off: [Architect] checkpoints at wave boundaries | + | Gate: [Architect] checkpoints at wave boundaries | +-----------------------------------------------------------------+ | v - PHASE 6: Review & Deploy /triad.close-feature + +================================================================================================ + STAGE 5: DELIVER Command: /aod.deliver +================================================================================================ + + /aod.deliver +-----------------------------------------------------------------------+ - | Parallel: [Code-Reviewer] [Security-Analyst] [Architect] | - | +----- Definition of Done check -----+ | - | Deploy: [DevOps] --> staging --> production | + | 1. Definition of Done validation | + | 2. Retrospective: metrics, surprises, next ideas | + | 3. KB entry from lessons learned | + | 4. New ideas --> GitHub Issues (stage:discover) --> FEEDBACK LOOP | +-----------------------------------------------------------------------+ + +-----------------------------------------------------------------+ + | Gate: DoD check (all tiers) | + +-----------------------------------------------------------------+ ================================================================================================ ARTIFACT TRAIL ================================================================================================ - IDEAS.md --> USER_STORIES.md --> PRD.md --> spec.md --> plan.md --> tasks.md --> CODE - PDL PDL Triad Triad Triad Triad Triad + GitHub Issue --> PRD --> spec.md --> plan.md --> tasks.md --> CODE --> Retrospective + Discover Define Plan Plan Plan Build Deliver ``` diff --git a/docs/guides/AOD_LIFECYCLE.md b/docs/guides/AOD_LIFECYCLE.md new file mode 100644 index 0000000..a3f0172 --- /dev/null +++ b/docs/guides/AOD_LIFECYCLE.md @@ -0,0 +1,259 @@ +# AOD Lifecycle Reference + +**Version**: 1.0.0 +**Status**: Active +**Spec Reference**: `specs/010-aod-lifecycle-formalization/spec.md` (FR-011) + +--- + +## The AOD Lifecycle + +The AOD Lifecycle is a single, linear sequence of 5 stages organized into 2 phases. All work passes through these stages from idea to delivered feature. + +``` + DISCOVERY DELIVERY + .-----------------------. .------------------------------------------------. + | | | | + | [1. Discover]-->[2. Define]-->[3. Plan]-->[4. Build]-->[5. Deliver] | + | | | | + '-----------------------' '------------------------------------------------' + | + Feedback Loop + | + New ideas --> Discover +``` + +### Lifecycle with Governance Gates + +Governance gates are Triad approval checkpoints that operate **between stages**, not as stages themselves. Gates determine who approves before work advances. + +``` + DISCOVERY PHASE DELIVERY PHASE + ================ ====================================== + + +------------+ +----------+ +---------+ +---------+ +---------+ + | | | | | | | | | | + | 1.Discover | | 2.Define | | 3. Plan | | 4.Build | |5.Deliver| + | | | | | | | | | | + | Capture | | Create | | Spec | | Execute | | Close | + | ideas + | | PRD with | | + Arch | | tasks | | feature | + | ICE score | | Triad | | plan + | | with | | + retro | + | | | review | | tasks | | reviews | | | + +-----+------+ +----+-----+ +----+----+ +----+----+ +----+----+ + | | | | | + v v v v v + +---------+ +---------+ +------------------+ +---------+ +---------+ + | GATE | | GATE | | GATES | | GATE | | GATE | + | PM val. | | PRD | | PM spec sign-off | | Arch | | DoD | + | (tier- | | review | | PM+Arch plan | | check- | | check | + | depend.)| | (tier- | | Triple sign-off | | points | | | + +---------+ | depend.)| +------------------+ +---------+ +---------+ + +---------+ +``` + +--- + +## Stage Definitions + +### 1. Discover (Discovery Phase) + +**Purpose**: Capture new feature ideas, score them with ICE, and gather evidence of the problem being solved. + +| | | +|---|---| +| **Primary Command** | `/aod.discover` | +| **Key Output** | Scored idea with evidence, GitHub Issue (`stage:discover`) | +| **Governance Gate** | PM validation (tier-dependent) | + +### 2. Define (Discovery Phase) + +**Purpose**: Create a Product Requirements Document (PRD) through structured Triad review, establishing the "what" and "why" for a feature. + +| | | +|---|---| +| **Primary Command** | `/aod.define` | +| **Key Output** | Approved PRD in `docs/product/02_PRD/` | +| **Governance Gate** | Triad PRD review (tier-dependent) | + +### 3. Plan (Delivery Phase) + +**Purpose**: Produce the specification, architecture plan, and task breakdown. This is the most complex stage, with 3 sequential sub-steps managed by a single router command. + +| | | +|---|---| +| **Primary Command** | `/aod.plan` (router -- auto-delegates to sub-steps) | +| **Key Output** | `spec.md`, `plan.md`, `tasks.md` in `.aod/` | +| **Governance Gates** | PM spec sign-off, PM+Architect plan sign-off, Triple sign-off on tasks | + +**Sub-steps** (auto-detected by `/aod.plan`): + +| Sub-step | Command | Sign-off | +|----------|---------|----------| +| Specification | `/aod.spec` | PM sign-off | +| Architecture Plan | `/aod.project-plan` | PM + Architect sign-off | +| Task Breakdown | `/aod.tasks` | PM + Architect + Team-Lead sign-off | + +### 4. Build (Delivery Phase) + +**Purpose**: Execute tasks from the approved task breakdown with architect checkpoints during implementation. + +| | | +|---|---| +| **Primary Command** | `/aod.build` | +| **Key Output** | Implemented feature on feature branch | +| **Governance Gate** | Architect checkpoints during execution | + +### 5. Deliver (Delivery Phase) + +**Purpose**: Close the feature with Definition of Done validation and a structured retrospective that feeds learnings back into discovery. + +| | | +|---|---| +| **Primary Command** | `/aod.deliver` | +| **Key Output** | Closed feature, retrospective, KB entry, new ideas (feedback loop) | +| **Governance Gate** | DoD check (all tiers) | + +--- + +## Governance Tiers + +Governance gates are a **separate, configurable layer** on top of the lifecycle. Choose a tier that matches your project's risk level. The lifecycle stages are the same regardless of tier -- only the gates change. + +### Tier Overview + +| Tier | Gate Count | When to Use | +|------|-----------|-------------| +| **Light** | 2 | Solo developers, prototypes, internal tools, hackathons | +| **Standard** (default) | 6 | Team projects, production features, most work | +| **Full** | all | Regulated industries, critical systems, high-stakes launches | + +### Tier Descriptions + +**Light (2 gates)**: Minimal ceremony. Triple sign-off at Plan stage and DoD at Deliver. Discover and Define gates are optional or skipped. For work where speed matters more than risk mitigation. + +**Standard (6 gates, default)**: Balanced governance. PM validation at Discover, PRD review at Define, PM+Architect sign-off plus Triple sign-off at Plan, Architect checkpoints at Build, DoD at Deliver. Appropriate for most production work. + +**Full (all gates)**: Maximum rigor. Everything in Standard plus a separate PM spec sign-off before the architecture plan. For environments where audit trails and formal approval at every boundary are required. + +### Configuration + +Set the governance tier in `.aod/memory/constitution.md`: + +```yaml +governance: + tier: standard # light | standard | full +``` + +### Rules + +- Triple sign-off (PM + Architect + Team-Lead on tasks) is the **minimum governance floor** for all tiers +- DoD check and Architect build checkpoints apply to **all tiers** +- Tier affects only Discover, Define, and Plan stage gates +- Tier is configured per project, not per feature + +--- + +## Governance Gate Matrix + +Which gates activate at each stage, per tier. + +| Tier | Discover | Define | Plan | Build | Deliver | +|------|----------|--------|------|-------|---------| +| **Light** | Optional | Skip | Triple sign-off only | Architect checkpoints | DoD | +| **Standard** | PM validation | PRD review | PM+Arch + Triple | Architect checkpoints | DoD | +| **Full** | PM validation | PRD review | PM spec + PM+Arch plan + Triple | Architect checkpoints | DoD | + +**Reading the matrix**: "PM+Arch + Triple" means PM and Architect sign-off on the architecture plan, followed by PM + Architect + Team-Lead sign-off on the task breakdown. "PM spec" means a separate PM sign-off on the specification before the architecture plan proceeds. + +--- + +## Command Reference + +### Primary Lifecycle Commands (1 per stage) + +| Command | Stage | Phase | What It Does | +|---------|-------|-------|-------------| +| `/aod.discover` | Discover | Discovery | Capture idea, ICE score, evidence prompt, PM validation | +| `/aod.define` | Define | Discovery | Create PRD with Triad review | +| `/aod.plan` | Plan | Delivery | Router: auto-delegates to `/aod.spec`, `/aod.project-plan`, `/aod.tasks` | +| `/aod.build` | Build | Delivery | Execute tasks with architect checkpoints | +| `/aod.deliver` | Deliver | Delivery | Close feature with DoD check and retrospective | + +### Plan Sub-Commands (invoked by `/aod.plan` router) + +| Command | Plan Sub-Step | Output | +|---------|--------------|--------| +| `/aod.spec` | Specification | `spec.md` with PM sign-off | +| `/aod.project-plan` | Architecture Plan | `plan.md` with PM + Architect sign-off | +| `/aod.tasks` | Task Breakdown | `tasks.md` with Triple sign-off | + +### Utility Commands (no governance gates) + +| Command | Purpose | +|---------|---------| +| `/aod.score` | Re-score an existing idea (stays in Discover stage) | +| `/aod.status` | Regenerate BACKLOG.md on demand, show stage summary | +| `/aod.analyze` | Cross-artifact consistency check | +| `/aod.clarify` | Resolve spec ambiguities | +| `/aod.checklist` | Generate quality checklist (Definition of Done) | +| `/aod.constitution` | View or update governance constitution | + +### Minimum Feature Sequence + +``` +/aod.discover --> /aod.define --> /aod.plan (x3 sessions) --> /aod.build --> /aod.deliver +``` + +Five commands. `/aod.plan` handles the Plan stage internally across 3 sessions (spec, project-plan, tasks). + +--- + +## Where Do I Find Things? + +Artifacts are organized into 3 zones. Each zone has a distinct purpose. + +### `.aod/` Zone -- Active Feature State + +The source of truth for the current feature being worked on. + +| File | Purpose | +|------|---------| +| `spec.md` | Feature specification (Plan stage output) | +| `plan.md` | Architecture plan (Plan stage output) | +| `tasks.md` | Task breakdown (Plan stage output) | +| `memory/constitution.md` | Governance principles + tier configuration | + +### `specs/NNN-*/` Zone -- Feature Archives + +Per-feature directory for research, design artifacts, and review records. + +| File | Purpose | +|------|---------| +| `research.md` | Pre-specification research findings | +| `data-model.md` | Entity model and state machine design | +| `checklists/` | Quality checklists for the feature | +| `agent-assignments.md` | Task-to-agent mapping (Team-Lead output) | +| `spec.md` | Archived spec (copied from `.aod/`) | +| `plan.md` | Archived plan (copied from `.aod/`) | +| `tasks.md` | Archived tasks (copied from `.aod/`) | + +### `docs/product/` Zone -- Product Documentation + +Long-lived product artifacts that span features. + +| File/Directory | Purpose | +|----------------|---------| +| `02_PRD/` | Product Requirements Documents (Define stage output) | +| `02_PRD/INDEX.md` | PRD index with status tracking | +| `_backlog/BACKLOG.md` | Auto-generated backlog grouped by lifecycle stage | +| `_backlog/archive/` | Archived legacy backlog files | +| `01_Product_Vision/` | Product vision and strategy | +| `03_Product_Roadmap/` | Roadmap and timeline | +| `05_User_Stories/` | User story library | +| `06_OKRs/` | Objectives and Key Results | + +--- + +**Last Updated**: 2026-02-09 +**Maintained By**: Product Manager (lifecycle governance) +**Source**: Feature 010 -- AOD Lifecycle Formalization diff --git a/docs/guides/AOD_LIFECYCLE_GUIDE.md b/docs/guides/AOD_LIFECYCLE_GUIDE.md new file mode 100644 index 0000000..b5523cf --- /dev/null +++ b/docs/guides/AOD_LIFECYCLE_GUIDE.md @@ -0,0 +1,286 @@ +# AOD Complete Lifecycle Guide + +**Version**: 2.0.0 +**Read Time**: ~8 minutes + +**Related**: +- [AOD Quickstart](AOD_QUICKSTART.md) -- Quick onboarding guide +- [AOD Infographic](AOD_INFOGRAPHIC.md) -- Visual workflow at a glance +- [SDLC Triad Reference](../AOD_TRIAD.md) -- Governance layer documentation +- [AOD Lifecycle Reference](AOD_LIFECYCLE.md) -- Stage definitions and governance tiers + +This guide covers the complete product lifecycle from raw idea to shipped feature using the AOD (Agentic Oriented Development) Lifecycle. + +--- + +## Visual Flow + +``` + DISCOVERY DELIVERY + .-----------------------. .------------------------------------------------. + | | | | + | [1. Discover]-->[2. Define]-->[3. Plan]-->[4. Build]-->[5. Deliver] | + | | | | + '-----------------------' '------------------------------------------------' + | + Feedback Loop + | + New ideas --> Discover +``` + +--- + +## Complete Lifecycle Overview + +``` +Discovery Delivery +────────────────────────────────── ────────────────────────────────── + +Stage 1 Stage 2 Stage 3 Stage 4 Stage 5 +Discover → Define → Plan → Build → Deliver + │ │ │ │ │ + ▼ ▼ ▼ ▼ ▼ +GitHub Issue PRD doc spec.md + Implemented Closed feature + ++ evidence plan.md + feature retrospective + + tasks.md KB entry +``` + +--- + +## Stage 1: Discover + +**Command**: `/aod.discover "your idea"` (full flow with PM validation) or `/aod.discover` with capture-only mode + +**What happens**: +1. A unique IDEA-NNN identifier is generated +2. The idea description is recorded +3. ICE scoring (Impact, Confidence, Effort) is applied +4. Evidence prompt: "Who has this problem, and how do you know?" +5. PM validation gate (tier-dependent) +6. If approved: user story generated, GitHub Issue created with `stage:discover` label + +**Output**: GitHub Issue with `stage:discover` label, scored idea with evidence. + +**ICE Quick Reference**: +- P0 (25-30): Critical — fast-track +- P1 (18-24): High — next sprint +- P2 (12-17): Medium — when capacity allows +- Deferred (< 12): Auto-deferred — PM override via `/aod.validate` + +--- + +## Stage 2: Define + +**Command**: `/aod.define ` + +**What happens**: +1. PRD creation flow begins with Triad review +2. If a backlog item is selected, PRD frontmatter includes source traceability: + ```yaml + source: + idea_id: IDEA-001 + story_id: US-001 + ``` +3. PM drafts, Architect + Team-Lead review, PM finalizes + +**Output**: PRD in `docs/product/02_PRD/{NNN}-{topic}-{date}.md` + +**Governance Gate**: Triad PRD review (tier-dependent) + +--- + +## Stage 3: Plan + +**Command**: `/aod.plan` (router — run up to 3 times) + +The Plan stage has 3 sequential sub-steps. The `/aod.plan` router auto-detects which sub-step you're on based on artifact state. + +| Sub-step | Direct Command | Output | Sign-off | +|----------|---------------|--------|----------| +| Specification | `/aod.spec` | spec.md | PM | +| Architecture Plan | `/aod.project-plan` | plan.md | PM + Architect | +| Task Breakdown | `/aod.tasks` | tasks.md + agent-assignments.md | PM + Architect + Team-Lead | + +**Router logic**: +1. No spec.md → delegates to `/aod.spec` +2. Spec approved, no plan.md → delegates to `/aod.project-plan` +3. Plan approved, no tasks.md → delegates to `/aod.tasks` +4. All approved → "Plan stage complete" + +### Specification (Sub-step 1) + +**What happens**: +1. Research phase: KB query, codebase exploration, architecture docs, web search +2. Spec generation with functional requirements, user scenarios, acceptance criteria +3. PM review and sign-off + +### Architecture Plan (Sub-step 2) + +**What happens**: +1. Architecture decisions, API contracts, data models +2. PM + Architect dual sign-off + +### Task Breakdown (Sub-step 3) + +**What happens**: +1. Tasks decomposed from plan with agent assignments +2. Parallel execution waves defined +3. PM + Architect + Team-Lead triple sign-off + +--- + +## Stage 4: Build + +**Command**: `/aod.build` + +**What happens**: +1. Execute tasks from approved task breakdown +2. Architect checkpoints at wave boundaries +3. Implementation proceeds wave by wave + +**Output**: Implemented feature on feature branch + +**Governance Gate**: Architect checkpoints during execution + +--- + +## Stage 5: Deliver + +**Command**: `/aod.deliver` + +**What happens**: +1. Definition of Done validation +2. Structured retrospective: + - Estimated vs. actual duration + - "What surprised us" (lessons learned) + - "What should we do next" (new ideas) +3. KB entry from lessons learned +4. New ideas fed back to Discover as GitHub Issues with `stage:discover` label + +**Output**: Closed feature, retrospective, KB entry, feedback loop to Discover + +**Governance Gate**: DoD check (all tiers) + +--- + +## Commands by Stage + +| Stage | Command | Output | +|-------|---------|--------| +| 1. Discover | `/aod.discover ` | GitHub Issue + scored idea | +| 2. Define | `/aod.define ` | PRD | +| 3. Plan | `/aod.plan` (router) | spec.md, plan.md, tasks.md | +| 4. Build | `/aod.build` | Implemented feature | +| 5. Deliver | `/aod.deliver` | Closed feature + retrospective | + +**Full flow shortcut**: `/aod.discover ` covers the entire Discover stage in one command. + +--- + +## Traceability Model + +The complete traceability chain from idea to delivery: + +``` +IDEA-001 (GitHub Issue, stage:discover) + └── US-001 (User Story) + └── PRD 005 (docs/product/02_PRD/005-*.md) + └── spec.md (specs/005-*/spec.md) + └── plan.md (specs/005-*/plan.md) + └── tasks.md (specs/005-*/tasks.md) + └── Implementation files +``` + +Each artifact references its source: +- User Story → links to IDEA-NNN via Source column +- PRD → links to IDEA-NNN and US-NNN via `source` frontmatter +- Spec → links to PRD via `prd_reference` frontmatter +- Plan → links to Spec via `spec_reference` +- Tasks → links to Plan via `plan_reference` + +--- + +## Status Flow Diagram + +### Idea Status (GitHub Issues) + +``` +[Capture] → stage:discover (>= 12) → stage:define (PRD started) + │ + └→ Deferred (< 12) → Re-scored (>= 12) → stage:define + │ + └→ Rejected (PM rejected) +``` + +### Feature Lifecycle (GitHub Issue labels) + +``` +stage:discover → stage:define → stage:plan → stage:build → stage:deliver +``` + +--- + +## End-to-End Example + +### Step 1: Discover + +```bash +/aod.discover "Add dark mode support for the dashboard" +``` + +- **IDEA-001** created, GitHub Issue with `stage:discover` +- ICE Score: 24 (I:9 C:9 E:6) — P1 (High) +- Evidence: "Customer feedback — 12 requests in last quarter" +- PM agent reviews: APPROVED + +### Step 2: Define + +```bash +/aod.define dark-mode-support +``` + +- PRD created with `source.idea_id: IDEA-001` +- GitHub Issue label updated to `stage:define` + +### Step 3: Plan (3 sessions) + +```bash +/aod.plan # Session 1: generates spec.md (PM sign-off) +/aod.plan # Session 2: generates plan.md (PM + Architect sign-off) +/aod.plan # Session 3: generates tasks.md (Triple sign-off) +``` + +- GitHub Issue label updated to `stage:plan` + +### Step 4: Build + +```bash +/aod.build +``` + +- Tasks executed with Architect checkpoints +- GitHub Issue label updated to `stage:build` + +### Step 5: Deliver + +```bash +/aod.deliver +``` + +- DoD validated, retrospective captured, KB entry created +- GitHub Issue label updated to `stage:deliver` +- New ideas from retrospective → new GitHub Issues with `stage:discover` + +Feature delivered with full traceability from original idea to shipped code. + +--- + +## Summary + +| Stage | Command | Output | Governance | +|-------|---------|--------|-----------| +| 1. Discover | `/aod.discover` | Scored idea + evidence | PM validation (tier-dependent) | +| 2. Define | `/aod.define` | PRD | Triad PRD review | +| 3. Plan | `/aod.plan` (x3) | spec + plan + tasks | PM, PM+Arch, Triple sign-off | +| 4. Build | `/aod.build` | Implementation | Architect checkpoints | +| 5. Deliver | `/aod.deliver` | Closed feature + retro | DoD check | diff --git a/docs/guides/AOD_MIGRATION.md b/docs/guides/AOD_MIGRATION.md new file mode 100644 index 0000000..ec28558 --- /dev/null +++ b/docs/guides/AOD_MIGRATION.md @@ -0,0 +1,136 @@ +# AOD Migration Reference + +A quick-lookup guide for transitioning from the old `/pdl.*` and `/triad.*` command namespaces to the unified `/aod.*` namespace. All behavior is identical -- only names have changed. + +--- + +## Command Mapping + +### Lifecycle Commands + +| Before | After | Stage | +|--------|-------|-------| +| `/pdl.idea` + `/pdl.validate` + `/pdl.run` | `/aod.discover` | Discover | +| `/pdl.score` | `/aod.score` | Discover (utility) | +| `/aod.define` | `/aod.define` | Define | +| `/aod.spec` | `/aod.spec` | Plan (sub-step) | +| `/aod.project-plan` | `/aod.project-plan` | Plan (sub-step) | +| `/aod.tasks` | `/aod.tasks` | Plan (sub-step) | +| -- (NEW) | `/aod.plan` | Plan (router) | +| `/aod.build` | `/aod.build` | Build | +| `/aod.deliver` | `/aod.deliver` | Deliver | + +### Utility Commands + +| Before | After | Notes | +|--------|-------|-------| +| `/aod.analyze` | `/aod.analyze` | Cross-artifact consistency check | +| `/aod.clarify` | `/aod.clarify` | Resolve spec ambiguities | +| `/aod.checklist` | `/aod.checklist` | Definition of Done checklist | +| `/aod.constitution` | `/aod.constitution` | View or update governance | +| -- (NEW) | `/aod.status` | On-demand backlog snapshot | + +### Unchanged Commands + +| Command | Notes | +|---------|-------| +| `/continue` | Not lifecycle-specific -- unchanged | +| `/execute` | Not lifecycle-specific -- unchanged | + +--- + +## Skill Directory Renames + +| Old Directory | New Directory | Notes | +|---------------|---------------|-------| +| `.claude/skills/pdl-idea/` | `.claude/skills/aod-discover/` | Merged with pdl-validate and pdl-run | +| `.claude/skills/pdl-validate/` | `.claude/skills/aod-discover/` | Merged into aod-discover | +| `.claude/skills/pdl-run/` | `.claude/skills/aod-discover/` | Merged into aod-discover | +| `.claude/skills/pdl-score/` | `.claude/skills/aod-score/` | Renamed | +| `.claude/skills/prd-create/` | `.claude/skills/aod-define/` | Renamed | +| `.claude/skills/spec-validator/` | `.claude/skills/aod-spec/` | Renamed | +| `.claude/skills/architecture-validator/` | `.claude/skills/aod-project-plan/` | Renamed | +| `.claude/skills/thinking-lens/` | `.claude/skills/aod-lens/` | Renamed | +| `.claude/skills/implementation-checkpoint/` | `.claude/skills/aod-build/` | Renamed | + +**New skills** (no old equivalent): + +| Directory | Purpose | +|-----------|---------| +| `.claude/skills/aod-plan/` | Plan stage router -- auto-detects sub-step | +| `.claude/skills/aod-status/` | On-demand backlog regeneration | +| `.claude/skills/aod-deliver/` | Delivery with structured retrospective | + +--- + +## Guide File Renames + +| Old File | New File | +|----------|----------| +| `docs/guides/PDL_TRIAD_QUICKSTART.md` | `docs/guides/AOD_QUICKSTART.md` | +| `docs/guides/PDL_TRIAD_LIFECYCLE.md` | `docs/guides/AOD_LIFECYCLE_GUIDE.md` | +| `docs/guides/PDL_TRIAD_INFOGRAPHIC.md` | `docs/guides/AOD_INFOGRAPHIC.md` | + +**New files** (no old equivalent): + +| File | Purpose | +|------|---------| +| `docs/guides/AOD_LIFECYCLE.md` | Lifecycle reference (5 stages, governance tiers, command mapping) | +| `docs/guides/AOD_MIGRATION.md` | This document | + +--- + +## For Existing Users + +If you have muscle memory for the old command names, here is what you need to know: + +1. **All behavior is identical.** The `/aod.*` commands do exactly the same thing as their `/pdl.*` and `/triad.*` predecessors. Only the names changed. + +2. **`/continue` and `/execute` are unchanged.** These commands are not lifecycle-specific and were not renamed. + +3. **Your existing specs, plans, and tasks files are unaffected.** The `.aod/spec.md`, `.aod/plan.md`, and `.aod/tasks.md` files keep their names and format. Frontmatter structure is unchanged. + +4. **The lifecycle documentation explains the new model.** See `docs/guides/AOD_LIFECYCLE.md` for the full 5-stage lifecycle reference, governance tier descriptions, and a "Where Do I Find Things?" cross-zone guide. + +--- + +## New Concepts + +Three capabilities are new in this release and have no old equivalent. + +### Plan Router (`/aod.plan`) + +A single entry point for the Plan stage. Instead of remembering whether to run `/aod.spec`, `/aod.project-plan`, or `/aod.tasks`, type `/aod.plan` at the start of each session. The router reads artifact frontmatter to detect which sub-step you are on and auto-invokes the correct command. + +- No spec.md yet? Router calls `/aod.spec`. +- Spec approved but no plan.md? Router calls `/aod.project-plan`. +- Plan approved but no tasks.md? Router calls `/aod.tasks`. +- All approved? Router reports "Plan stage complete. Run `/aod.build` to proceed." + +Direct sub-commands (`/aod.spec`, `/aod.project-plan`, `/aod.tasks`) still work independently for power users. + +### Governance Tiers (Light / Standard / Full) + +Choose how much ceremony your project needs. The tier determines which governance gates are active at each lifecycle stage. + +| Tier | Gates | Best For | +|------|-------|----------| +| **Light** | 2 (Triple sign-off + DoD) | Solo projects, prototypes, low-risk features | +| **Standard** | 6 (default) | Team projects, production features | +| **Full** | All gates including separate PM spec sign-off | Regulated environments, high-risk features | + +Configure in `.aod/memory/constitution.md`: + +```yaml +governance: + tier: standard # light | standard | full +``` + +Triple sign-off is the minimum governance floor for all tiers. + +### GitHub-Backed Tracking + +Every `/aod.*` lifecycle command now updates a GitHub Issue with a `stage:*` label reflecting the current lifecycle stage. After each command, `BACKLOG.md` is regenerated from GitHub Issues, grouped by stage (Discover, Define, Plan, Build, Deliver). + +- Run `/aod.status` at any time for an on-demand backlog snapshot with item counts per stage. +- If `gh` CLI is unavailable or no GitHub remote is configured, commands proceed normally and skip GitHub operations with a warning. diff --git a/docs/guides/AOD_QUICKSTART.md b/docs/guides/AOD_QUICKSTART.md new file mode 100644 index 0000000..edbf697 --- /dev/null +++ b/docs/guides/AOD_QUICKSTART.md @@ -0,0 +1,186 @@ +# AOD Quickstart + +**Version**: 2.0.0 +**Read Time**: ~5 minutes + +**Related**: +- [AOD Lifecycle Reference](AOD_LIFECYCLE.md) -- Stage-by-stage deep reference +- [AOD Infographic](AOD_INFOGRAPHIC.md) -- Visual workflow at a glance +- [SDLC Triad Reference](../AOD_TRIAD.md) -- Governance layer documentation +- [AOD Migration Guide](AOD_MIGRATION.md) -- Old command mapping + +--- + +## Workflow Overview + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ AOD LIFECYCLE │ +└─────────────────────────────────────────────────────────────────────────────┘ + + Discovery Delivery + ───────── ──────── + + ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ + │1.Discover│───▶│ 2.Define │───▶│ 3. Plan │───▶│ 4.Build │───▶│5.Deliver │ + │ │ │ │ │ │ │ │ │ │ + └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ + │ │ + └───────────────────── Feedback Loop ◀──────────────────────────┘ +``` + +--- + +## What is AOD? + +AOD is **Agentic Oriented Development** -- a unified lifecycle with 5 stages that takes work from raw idea to delivered feature. Governance gates (Triad sign-offs) operate as a **separate, configurable layer** between stages. AOD answers two questions: **"Should we build this?"** (Discovery) and **"How do we build this right?"** (Delivery). + +--- + +## Quick Start + +The fastest path from idea to implementation: + +```bash +# Full flow: 5 commands covering 5 stages +/aod.discover "Add dark mode support" # Stage 1: Capture idea + ICE score + PM validation +/aod.define dark-mode-support # Stage 2: Create PRD with Triad review +/aod.plan # Stage 3: Router (run 3x for spec → plan → tasks) +/aod.build # Stage 4: Execute tasks with Architect checkpoints +/aod.deliver # Stage 5: Close feature with retrospective +``` + +`/aod.plan` handles the Plan stage internally across 3 sessions (spec, project-plan, tasks). It auto-detects which sub-step you're on. + +--- + +## Command Reference + +### Primary Lifecycle Commands (1 per stage) + +| Command | Stage | What It Does | +|---------|-------|-------------| +| `/aod.discover` | 1. Discover | Capture idea, ICE score, evidence prompt, PM validation | +| `/aod.define` | 2. Define | Create PRD with Triad review | +| `/aod.plan` | 3. Plan | Router: auto-delegates to `/aod.spec`, `/aod.project-plan`, `/aod.tasks` | +| `/aod.build` | 4. Build | Execute tasks with architect checkpoints | +| `/aod.deliver` | 5. Deliver | Close feature with DoD check and retrospective | + +### Utility Commands + +| Command | Purpose | +|---------|---------| +| `/aod.score` | Re-score an existing idea | +| `/aod.status` | Regenerate BACKLOG.md, show stage summary | +| `/aod.analyze` | Cross-artifact consistency check | +| `/aod.clarify` | Resolve spec ambiguities | +| `/aod.checklist` | Generate quality checklist (Definition of Done) | +| `/aod.constitution` | View or update governance constitution | + +--- + +## ICE Scoring Quick Reference + +ICE stands for **Impact**, **Confidence**, and **Effort** (ease of implementation). Each dimension is scored 1-10, with a total range of 3-30. + +### Quick-Assessment Anchors + +| Dimension | High (9) | Medium (6) | Low (3) | +|-----------|----------|------------|---------| +| **Impact** | Transformative | Solid improvement | Minor enhancement | +| **Confidence** | Proven pattern | Some unknowns | Speculative | +| **Effort (Ease)** | Days of work | Weeks of work | Months of work | + +### Priority Tiers + +| Score Range | Priority | Action | +|-------------|----------|--------| +| 25-30 | P0 (Critical) | Fast-track to development | +| 18-24 | P1 (High) | Queue for next sprint | +| 12-17 | P2 (Medium) | Consider when capacity allows | +| < 12 | Deferred | Auto-defer; requires PM override via `/aod.validate` | + +### Auto-Defer Gate + +Ideas scoring below 12 are automatically deferred. The PM can override this gate using `/aod.validate IDEA-NNN`. + +--- + +## Governance Tiers + +Governance gates are a configurable layer. Choose a tier that matches your risk level. + +| Tier | Gate Count | When to Use | +|------|-----------|-------------| +| **Light** | 2 | Solo developers, prototypes, internal tools | +| **Standard** (default) | 6 | Team projects, production features | +| **Full** | all | Regulated industries, critical systems | + +Configure in `.aod/memory/constitution.md`: +```yaml +governance: + tier: standard # light | standard | full +``` + +--- + +## Triad Roles Summary + +| Role | Defines | Authority | Key Question | +|------|---------|-----------|--------------| +| **PM** | What & Why | Scope & requirements | Does this solve the right problem? | +| **Architect** | How | Technical decisions | Is this technically sound? | +| **Team-Lead** | When & Who | Timeline & resources | Can we deliver this effectively? | + +--- + +## Sign-off Requirements + +| Stage | Required Sign-offs | Command | +|-------|-------------------|---------| +| Define | PM + Architect + Team-Lead | `/aod.define` | +| Plan: Spec | PM | `/aod.spec` (via `/aod.plan`) | +| Plan: Architecture | PM + Architect | `/aod.project-plan` (via `/aod.plan`) | +| Plan: Tasks | PM + Architect + Team-Lead | `/aod.tasks` (via `/aod.plan`) | +| Build | Architect checkpoints | `/aod.build` | +| Deliver | DoD check | `/aod.deliver` | + +Each step auto-validates before proceeding. If a reviewer returns **CHANGES REQUESTED**, the phase repeats until all required sign-offs are **APPROVED**. + +--- + +## File Locations + +``` +Active Feature: + .aod/ # Source of truth + ├── spec.md # Feature specification + ├── plan.md # Implementation plan + └── tasks.md # Task breakdown + +Feature Archives: + specs/{NNN}-{feature}/ # Per-feature archives + +Product Artifacts: + docs/product/02_PRD/ # PRD documents + docs/product/_backlog/ # BACKLOG.md (auto-generated) +``` + +--- + +## Troubleshooting + +**"Idea auto-deferred but I want to build it"** +Use `/aod.validate IDEA-NNN` to submit the idea for PM review. The PM can override the auto-defer gate with documented rationale. + +**"Is Discovery mandatory?"** +No. You can start directly at `/aod.define` without any Discovery artifacts. + +**"Spec has no PM sign-off"** +Use `/aod.plan` (which invokes `/aod.spec`) instead of creating spec.md manually. The command automatically invokes PM review. + +**"Plan blocked after multiple iterations"** +Split the feature into smaller, independently deliverable pieces, or escalate to the user for scope clarification. + +**"Command not found"** +All lifecycle commands use the `/aod.*` prefix. Run `/help` to see all available commands. See [AOD Migration Guide](AOD_MIGRATION.md) for old-to-new command mapping. diff --git a/docs/guides/PDL_TRIAD_LIFECYCLE.md b/docs/guides/PDL_TRIAD_LIFECYCLE.md deleted file mode 100644 index caffe44..0000000 --- a/docs/guides/PDL_TRIAD_LIFECYCLE.md +++ /dev/null @@ -1,339 +0,0 @@ -# PDL + Triad Complete Lifecycle Guide - -**Version**: 1.0.0 -**Read Time**: ~8 minutes - -**Related**: -- [PDL + Triad Quickstart](PDL_TRIAD_QUICKSTART.md) -- Unified onboarding guide -- [PDL + Triad Infographic](PDL_TRIAD_INFOGRAPHIC.md) -- Visual workflow at a glance -- [SDLC Triad Reference](../AOD_TRIAD.md) -- Comprehensive Triad documentation - -This guide covers the complete product lifecycle from raw idea to shipped feature, integrating the Product Discovery Lifecycle (PDL) with the Triad workflow. - ---- - -## Visual Flow - -``` -PDL Discovery Triad Delivery -───────────────────────────────────── ───────────────────────────────────────── -┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌────────┐ -│ IDEA │──▶│ SCORE │──▶│ VALIDATE │══▶│ PRD │──▶│SPECIFY │──▶│ PLAN │ -│ │ │ (ICE) │ │ (PM) │ │ │ │ │ │ │ -└────────┘ └────────┘ └──────────┘ └────────┘ └────────┘ └────────┘ - Stage 1 Stage 2 Stage 3 Stage 5 Stage 6 Stage 7 - │ │ - ┌──────────┐ │ ▼ - │ BACKLOG │◀───┘ ┌────────┐ ┌────────┐ - │ │ │DEPLOYED│◀──│IMPLEMENT│ - └──────────┘ │ │ │ │ - Stage 4 └────────┘ └────────┘ - ┌────────┐ Stage 10 Stage 9 - │ TASKS │──────────────────▲ - │ │ - └────────┘ - Stage 8 -``` - ---- - -## Complete Lifecycle Overview - -``` -PDL (Discovery) Triad (Delivery) -────────────────────────────────── ────────────────────────────────── - -Stage 1 Stage 2 Stage 3 Stage 5 Stages 6-10 -Idea Capture → ICE Scoring → PM Validation → Triad Handoff → PRD → Spec → Plan → Tasks → Implement - │ │ │ │ - ▼ ▼ ▼ ▼ -01_IDEAS.md 01_IDEAS.md 02_USER_STORIES.md PRD with source -(New entry) (Scored) (User story) traceability - - Stage 4 - Product Backlog - (Prioritized stories) -``` - ---- - -## Stage 1: Idea Capture - -**Command**: `/pdl.idea "your idea"` or `/pdl.run "your idea"` - -**What happens**: -1. A unique IDEA-NNN identifier is generated -2. The idea description is recorded -3. The source is captured (Brainstorm, Customer Feedback, Team Idea, User Request) -4. The idea is added to `docs/product/_backlog/01_IDEAS.md` - -**Output**: A new row in the Ideas Backlog table. - -**Example Entry**: -``` -| IDEA-001 | Add dark mode to dashboard | Brainstorm | 2026-01-29 | Scoring | 24 (I:9 C:9 E:6) | -``` - ---- - -## Stage 2: ICE Scoring - -**Integrated with**: Stage 1 (scoring happens during capture) - -**What happens**: -1. Each dimension (Impact, Confidence, Effort) is scored 1-10 -2. Quick-assessment shortcuts: High (9), Medium (6), Low (3) -3. ICE Total = Impact + Confidence + Effort (range 3-30) -4. Priority tier assigned based on total score -5. Auto-defer gate: Score < 12 automatically defers the idea - -**Score Tiers**: -- P0 (25-30): Critical — fast-track to development -- P1 (18-24): High — queue for next sprint -- P2 (12-17): Medium — consider when capacity allows -- Deferred (< 12): Auto-deferred — requires PM override - ---- - -## Stage 3: PM Validation - -**Command**: `/pdl.validate IDEA-NNN` or automatic in `/pdl.run` - -**What happens**: -1. The product-manager agent reviews the idea -2. PM evaluates alignment with vision, scoring accuracy, and user value -3. **If Approved**: A user story is generated and added to the backlog -4. **If Rejected**: The idea status is updated to "Rejected" - -**PM Override**: For auto-deferred ideas (score < 12), PM can approve with documented rationale. - -**Example User Story**: -``` -"As a Template Adopter, I want dark mode support for the dashboard, -so that I can reduce eye strain during extended sessions." -``` - ---- - -## Stage 4: Product Backlog - -**File**: `docs/product/_backlog/02_USER_STORIES.md` - -**What happens**: -1. Approved ideas become user stories in "As a [persona], I want [action], so that [benefit]" format -2. Stories are prioritized by ICE score tier -3. Status starts as "Ready for PRD" - -**Status Flow**: -``` -Ready for PRD → In PRD → In Development → Delivered -``` - ---- - -## Stage 5: Triad Handoff - -**Command**: `/triad.prd ` - -**What happens**: -1. The PRD creation flow detects backlog items with "Ready for PRD" status -2. If a backlog item is selected, PRD frontmatter includes source traceability: - ```yaml - source: - idea_id: IDEA-001 - story_id: US-001 - ``` -3. The user story status updates from "Ready for PRD" to "In PRD" - -This source traceability ensures every PRD can be traced back to the original idea and validated user story, creating an unbroken audit trail from discovery through delivery. - ---- - -## Stages 6-10: Triad Workflow - -Once the PRD is created, the standard Triad workflow takes over: - -| Stage | Command | Output | Sign-offs | -|-------|---------|--------|-----------| -| 6 | `/triad.specify` | spec.md | PM | -| 7 | `/triad.plan` | plan.md | PM + Architect | -| 8 | `/triad.tasks` | tasks.md | PM + Architect + Team-Lead | -| 9 | `/triad.implement` | Code/Files | Architect checkpoints | -| 10 | `/triad.close-feature` | Docs updated | Final validation | - -### Sign-off Details by Stage - -| Stage | Phase | Sign-offs | What Gets Validated | -|-------|-------|-----------|---------------------| -| 6 | Specify | PM | Requirements alignment, user story coverage, scope boundaries | -| 7 | Plan | PM + Architect | Technical feasibility, architecture decisions, risk assessment | -| 8 | Tasks | PM + Architect + Team-Lead | Task completeness, agent assignments, parallel execution plan | -| 9 | Implement | Architect (checkpoints) | Code quality, architecture compliance at wave boundaries | -| 10 | Close | Auto | Documentation completeness, feature library update | - -**Review Outcomes**: -- **APPROVED**: Proceed to next phase -- **CHANGES REQUESTED**: Revise and re-submit for review -- **BLOCKED**: Critical issue -- halt until resolved - -### Artifact Examples - -**spec.md** (Stage 6): -``` -## Functional Requirements -### FR-1: Dark Mode Toggle -- System shall provide a toggle in the dashboard settings panel -- Acceptance: Theme switches within 200ms without page reload - -## User Scenarios -### Scenario 1: Enable Dark Mode -Given the user is on the dashboard -When they toggle dark mode in settings -Then all UI elements switch to the dark color scheme -``` - -**plan.md** (Stage 7): -``` -## Technical Approach -### Component: ThemeProvider -- Pattern: React Context with CSS custom properties -- Risk: Third-party component compatibility (Medium) - -## Architecture Decisions -- ADR-001: CSS custom properties over CSS-in-JS for theme switching -``` - -**tasks.md** (Stage 8): -``` -## Wave 1 (Parallel) -- [ ] T-001: Create ThemeProvider context (frontend-developer) -- [ ] T-002: Define dark color tokens (ux-ui-designer) - -## Wave 2 (Depends on Wave 1) -- [ ] T-003: Update dashboard components (frontend-developer) -``` - ---- - -## Commands by Stage - -| Stage | PDL Command | Triad Command | Output | -|-------|-------------|---------------|--------| -| 1. Idea Capture | `/pdl.idea ` | -- | 01_IDEAS.md entry | -| 2. ICE Scoring | (integrated) | -- | ICE score in IDEAS.md | -| 3. PM Validation | `/pdl.validate IDEA-NNN` | -- | User story in 02_USER_STORIES.md | -| 4. Product Backlog | (automatic) | -- | Status: Ready for PRD | -| 5. Triad Handoff | -- | `/triad.prd ` | PRD with source traceability | -| 6. Specify | -- | `/triad.specify` | spec.md | -| 7. Plan | -- | `/triad.plan` | plan.md | -| 8. Tasks | -- | `/triad.tasks` | tasks.md + agent-assignments.md | -| 9. Implement | -- | `/triad.implement` | Code/Files | -| 10. Close | -- | `/triad.close-feature NNN` | Documentation updates | - -**Full flow shortcut**: `/pdl.run ` covers stages 1-4 in one command. - ---- - -## Traceability Model - -The complete traceability chain from idea to delivery: - -``` -IDEA-001 (01_IDEAS.md) - └── US-001 (02_USER_STORIES.md) - └── PRD 005 (docs/product/02_PRD/005-*.md) - └── spec.md (specs/005-*/spec.md) - └── plan.md (specs/005-*/plan.md) - └── tasks.md (specs/005-*/tasks.md) - └── Implementation files -``` - -Each artifact references its source: -- User Story → links to IDEA-NNN via Source column -- PRD → links to IDEA-NNN and US-NNN via `source` frontmatter -- Spec → links to PRD via `prd_reference` frontmatter -- Plan → links to Spec via `spec_reference` -- Tasks → links to Plan via `plan_reference` - ---- - -## Status Flow Diagram - -### Idea Status (01_IDEAS.md) - -``` -[Capture] → Scoring (>= 12) → Validated (PM approved) - │ - └→ Deferred (< 12) → Scoring (re-scored >= 12) → Validated - │ │ - └→ Rejected (PM rejected) → Scoring (re-scored) ────┘ -``` - -### User Story Status (02_USER_STORIES.md) - -``` -Ready for PRD → In PRD → In Development → Delivered -``` - ---- - -## End-to-End Example - -### Step 1: Capture and Score - -```bash -/pdl.run "Add dark mode support for the dashboard" -``` - -- **IDEA-001** created -- ICE Score: 24 (I:9 C:9 E:6) — P1 (High) -- Source: User Request - -### Step 2: PM Validation (automatic in /pdl.run) - -- PM agent reviews: APPROVED -- Rationale: "High user demand, proven pattern, moderate effort" - -### Step 3: User Story Generated - -- **US-001**: "As a Template Adopter, I want dark mode support for the dashboard, so that I can reduce eye strain during extended sessions." -- Priority: 2 (P1) -- Status: Ready for PRD - -### Step 4: Triad Handoff - -```bash -/triad.prd dark-mode-support -``` - -- PRD created with `source.idea_id: IDEA-001` and `source.story_id: US-001` -- US-001 status updated to "In PRD" - -### Step 5: Triad Workflow - -```bash -/triad.specify -/triad.plan -/triad.tasks -/triad.implement -/triad.close-feature 005 -``` - -Feature delivered with full traceability from original idea to shipped code. - ---- - -## Summary - -| Stage | Artifact | Purpose | Owner | -|-------|----------|---------|-------| -| 1 | 01_IDEAS.md | Raw concept + ICE score | PM | -| 2 | (integrated) | ICE scoring during capture | PM | -| 3 | 02_USER_STORIES.md | PM-validated user story | PM | -| 4 | 02_USER_STORIES.md | Prioritized product backlog | PM | -| 5 | PRD | Business context, scope, metrics | PM + Architect + Team-Lead | -| 6 | spec.md | Functional requirements | PM | -| 7 | plan.md | Technical architecture | PM + Architect | -| 8 | tasks.md | Work breakdown + agent assignments | PM + Architect + Team-Lead | -| 9 | Code | Implementation | Agents | -| 10 | Feature Library | Production record | Auto | diff --git a/docs/guides/PDL_TRIAD_QUICKSTART.md b/docs/guides/PDL_TRIAD_QUICKSTART.md deleted file mode 100644 index fdced0c..0000000 --- a/docs/guides/PDL_TRIAD_QUICKSTART.md +++ /dev/null @@ -1,191 +0,0 @@ -# PDL + Triad Unified Quickstart - -**Version**: 1.0.0 -**Read Time**: ~5 minutes - -**Related**: -- [PDL + Triad Lifecycle Guide](PDL_TRIAD_LIFECYCLE.md) -- Stage-by-stage deep reference -- [PDL + Triad Infographic](PDL_TRIAD_INFOGRAPHIC.md) -- Visual workflow at a glance -- [SDLC Triad Reference](../AOD_TRIAD.md) -- Comprehensive Triad documentation - ---- - -## Workflow Overview - -``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ PDL + TRIAD UNIFIED WORKFLOW │ -└─────────────────────────────────────────────────────────────────────────────┘ - - PDL (Discovery) Triad (Delivery) - ─────────────── ──────────────── - - ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌────────┐ - │ IDEA │───▶│ SCORE │───▶│ VALIDATE │═══▶│ PRD │───▶│SPECIFY │───▶│ PLAN │ - │ │ │ (ICE) │ │ (PM) │ │ │ │ │ │ │ - └────────┘ └────────┘ └──────────┘ └────────┘ └────────┘ └────────┘ - │ - ┌────────┐ ┌──────────┐ │ - │DEPLOYED│◀───│IMPLEMENT │◀──────────────────────────────┌────────┐◀─────────┘ - │ │ │ │ │ TASKS │ - └────────┘ └──────────┘ └────────┘ -``` - ---- - -## What is PDL? - -PDL is the **Product Discovery Lifecycle** -- a structured discovery phase that captures ideas, scores them with ICE (Impact, Confidence, Effort), validates with a PM, and maintains a prioritized product backlog. PDL answers the question: **"Should we build this?"** It is entirely optional; you can skip it and start directly at the Triad workflow. - ---- - -## What is Triad? - -The **SDLC Triad** is a governance framework ensuring Product-Architecture-Engineering alignment throughout the delivery process. Three specialized roles -- PM (What & Why), Architect (How), and Team-Lead (When & Who) -- provide sign-offs at each phase to prevent technical inaccuracies and scope drift. Triad answers the question: **"How do we build this right?"** - ---- - -## Quick Start - -The fastest path from idea to implementation: - -```bash -# Option 1: Full flow (PDL discovery + Triad delivery) -/pdl.run "Add dark mode support" # Capture + Score + Validate + Backlog -/triad.prd dark-mode-support # Create PRD with Triad validation -/triad.specify # Create spec with PM sign-off -/triad.plan # Create plan with PM + Architect sign-off -/triad.tasks # Create tasks with triple sign-off -/triad.implement # Execute with Architect checkpoints - -# Option 2: Skip PDL (start directly at Triad) -/triad.prd dark-mode-support # PDL is optional -``` - ---- - -## PDL Command Reference - -| Command | Purpose | Input | Output | -|---------|---------|-------|--------| -| `/pdl.run ` | Full discovery flow in one step | Idea description | IDEA + User Story (if approved) | -| `/pdl.idea ` | Capture idea + ICE scoring only | Idea description | IDEA entry in backlog | -| `/pdl.score IDEA-NNN` | Re-score an existing idea | Idea identifier | Updated ICE score | -| `/pdl.validate IDEA-NNN` | PM validation + user story generation | Idea identifier | User Story (if approved) | - ---- - -## Triad Command Reference - -| Command | Purpose | Sign-offs | Output | -|---------|---------|-----------|--------| -| `/triad.prd ` | Create PRD with Triad validation | PM + Architect + Team-Lead | PRD file | -| `/triad.specify` | Create spec with research phase | PM | spec.md | -| `/triad.plan` | Create implementation plan | PM + Architect | plan.md | -| `/triad.tasks` | Create task breakdown | PM + Architect + Team-Lead | tasks.md + agent-assignments.md | -| `/triad.implement` | Execute with checkpoints | Architect checkpoints | Implementation | -| `/triad.close-feature NNN` | Close completed feature | Auto | Documentation updates | - ---- - -## ICE Scoring Quick Reference - -ICE stands for **Impact**, **Confidence**, and **Effort** (ease of implementation). Each dimension is scored 1-10, with a total range of 3-30. - -### Quick-Assessment Anchors - -| Dimension | High (9) | Medium (6) | Low (3) | -|-----------|----------|------------|---------| -| **Impact** | Transformative | Solid improvement | Minor enhancement | -| **Confidence** | Proven pattern | Some unknowns | Speculative | -| **Effort (Ease)** | Days of work | Weeks of work | Months of work | - -### Priority Tiers - -| Score Range | Priority | Action | -|-------------|----------|--------| -| 25-30 | P0 (Critical) | Fast-track to development | -| 18-24 | P1 (High) | Queue for next sprint | -| 12-17 | P2 (Medium) | Consider when capacity allows | -| < 12 | Deferred | Auto-defer; requires PM override via `/pdl.validate` | - -### Auto-Defer Gate - -Ideas scoring below 12 are automatically deferred. This catches ideas where all dimensions score poorly (e.g., Low/Low/Low = 9). The PM can override this gate using `/pdl.validate IDEA-NNN`. - ---- - -## PDL to Triad Handoff - -When a user story reaches "Ready for PRD" status in the product backlog, run `/triad.prd ` to begin the Triad delivery workflow. The PRD creation flow detects backlog items with "Ready for PRD" status and links them automatically. - -The PRD includes `source.idea_id` and `source.story_id` fields in its frontmatter, establishing full traceability: - -``` -IDEA --> User Story --> PRD --> spec.md --> plan.md --> tasks.md --> Code -``` - -Each artifact references its source, so you can trace any piece of delivered code back to the original idea. - ---- - -## Triad Roles Summary - -| Role | Defines | Authority | Key Question | -|------|---------|-----------|--------------| -| **PM** | What & Why | Scope & requirements | Does this solve the right problem? | -| **Architect** | How | Technical decisions | Is this technically sound? | -| **Team-Lead** | When & Who | Timeline & resources | Can we deliver this effectively? | - ---- - -## Sign-off Requirements - -| Phase | Required Sign-offs | Command | -|-------|-------------------|---------| -| PRD | PM + Architect + Team-Lead | `/triad.prd` | -| Specification | PM | `/triad.specify` | -| Plan | PM + Architect | `/triad.plan` | -| Tasks | PM + Architect + Team-Lead | `/triad.tasks` | -| Implementation | Architect checkpoints | `/triad.implement` | - -Each step auto-validates before proceeding. If a reviewer returns **CHANGES REQUESTED**, the phase repeats until all required sign-offs are **APPROVED**. - ---- - -## File Locations - -``` -PDL Artifacts: - docs/product/_backlog/ - ├── 01_IDEAS.md # All captured ideas with ICE scores - └── 02_USER_STORIES.md # PM-validated user stories - -Triad Artifacts: - .aod/ # Active feature (source of truth) - ├── spec.md # Feature specification - ├── plan.md # Implementation plan - └── tasks.md # Task breakdown - - specs/{NNN}-{feature}/ # Archived specifications - docs/product/02_PRD/ # PRD documents -``` - ---- - -## Troubleshooting - -**"Idea auto-deferred but I want to build it"** -Use `/pdl.validate IDEA-NNN` to submit the idea for PM review. The PM can override the auto-defer gate with documented rationale. - -**"Is PDL mandatory?"** -No. PDL is entirely optional. You can start directly at `/triad.prd` without any PDL artifacts. - -**"Spec has no PM sign-off"** -Use `/triad.specify` instead of creating spec.md manually. The Triad command automatically invokes PM review and records the sign-off. - -**"Plan blocked after multiple iterations"** -Split the feature into smaller, independently deliverable pieces, or escalate to the user for scope clarification. - -**"Command not found"** -Ensure you are using the correct prefix: `/pdl.` for discovery commands and `/triad.` for delivery commands. Run `/help` to see all available commands. diff --git a/docs/product/01_Product_Vision/README.md b/docs/product/01_Product_Vision/README.md index 24918e3..50cace2 100644 --- a/docs/product/01_Product_Vision/README.md +++ b/docs/product/01_Product_Vision/README.md @@ -116,7 +116,7 @@ All PRDs in `docs/product/02_PRD/` must reference this vision: - PRD user stories must serve defined personas ### Spec Validation -When creating `spec.md` with `/triad.specify`: +When creating `spec.md` with `/aod.spec`: - product-manager validates spec aligns with product vision - Architect ensures technical approach serves user needs - Team-lead prioritizes work based on persona value @@ -195,7 +195,7 @@ docs/product/01_Product_Vision/ **Agent Tools**: - `.claude/agents/product-manager.md` - Product Manager agent -- `/triad.prd` - Create PRD with Triad governance +- `/aod.define` - Create PRD with Triad governance --- diff --git a/docs/product/02_PRD/000-example-feature.md b/docs/product/02_PRD/000-example-feature.md index 3b00893..4ce55ae 100644 --- a/docs/product/02_PRD/000-example-feature.md +++ b/docs/product/02_PRD/000-example-feature.md @@ -124,8 +124,8 @@ **PM Approval**: ✅ Approved on {{CURRENT_DATE}} -**Next Step**: Create spec with `/triad.specify` +**Next Step**: Create spec with `/aod.spec` --- -**Template Instructions**: This is an annotated example. Delete this PRD after creating your first real PRD. Use `/triad.prd ` to generate a new PRD with automatic Triad validation. +**Template Instructions**: This is an annotated example. Delete this PRD after creating your first real PRD. Use `/aod.define ` to generate a new PRD with automatic Triad validation. diff --git a/docs/product/03_Product_Roadmap/README.md b/docs/product/03_Product_Roadmap/README.md index 6b348f4..390c85f 100644 --- a/docs/product/03_Product_Roadmap/README.md +++ b/docs/product/03_Product_Roadmap/README.md @@ -16,7 +16,7 @@ Before MVP, you don't have enough information: - No validated assumptions - Priorities will change -**Pre-MVP**: Focus on `/triad.prd` → build MVP +**Pre-MVP**: Focus on `/aod.define` → build MVP **Post-MVP**: Create roadmap based on what you learned --- diff --git a/docs/product/04_Journey_Maps/README.md b/docs/product/04_Journey_Maps/README.md index 453ac56..b8a2457 100644 --- a/docs/product/04_Journey_Maps/README.md +++ b/docs/product/04_Journey_Maps/README.md @@ -15,7 +15,7 @@ Before MVP: - You don't know actual pain points vs. imagined ones - The onboarding flow doesn't exist yet -**Pre-MVP**: Focus on `/triad.prd` (includes target users in vision) → build MVP +**Pre-MVP**: Focus on `/aod.define` (includes target users in vision) → build MVP **Post-MVP**: Map real user journeys based on actual behavior and feedback --- diff --git a/docs/product/_backlog/README.md b/docs/product/_backlog/README.md index ace7a2f..e08f0d0 100644 --- a/docs/product/_backlog/README.md +++ b/docs/product/_backlog/README.md @@ -10,16 +10,16 @@ The Product Discovery Lifecycle (PDL) provides structured backlog management thr | File | Purpose | Managed By | |------|---------|------------| -| `01_IDEAS.md` | All captured ideas with ICE scores and status | `/pdl.idea`, `/pdl.run`, `/pdl.score` | -| `02_USER_STORIES.md` | PM-validated user stories prioritized for development | `/pdl.validate`, `/pdl.run` | +| `01_IDEAS.md` | All captured ideas with ICE scores and status | `/aod.discover`, `/aod.discover`, `/aod.score` | +| `02_USER_STORIES.md` | PM-validated user stories prioritized for development | `/aod.validate`, `/aod.discover` | ### How It Works -1. **Capture**: Run `/pdl.idea` or `/pdl.run` to add ideas with ICE scoring +1. **Capture**: Run `/aod.discover` or `/aod.discover` to add ideas with ICE scoring 2. **Score**: Ideas are scored on Impact, Confidence, and Effort (1-10 each) -3. **Validate**: Run `/pdl.validate` to submit ideas for PM review +3. **Validate**: Run `/aod.validate` to submit ideas for PM review 4. **Backlog**: Approved ideas become user stories in `02_USER_STORIES.md` -5. **Handoff**: Run `/triad.prd` to create a PRD from a backlog item +5. **Handoff**: Run `/aod.define` to create a PRD from a backlog item ### Single-User Assumption @@ -29,11 +29,11 @@ PDL assumes single-user/single-agent editing of backlog files. No concurrent edi Existing individual backlog files (e.g., `feature-idea-name.md`) are preserved alongside the new table-based files. To migrate: -1. Run `/pdl.idea` for each existing backlog item to add it to `01_IDEAS.md` -2. Run `/pdl.validate` for items ready for development to add them to `02_USER_STORIES.md` +1. Run `/aod.discover` for each existing backlog item to add it to `01_IDEAS.md` +2. Run `/aod.validate` for items ready for development to add them to `02_USER_STORIES.md` 3. Optionally archive or delete the original individual files after migration -New ideas should use `/pdl.idea` or `/pdl.run` to add entries directly to the consolidated tables. +New ideas should use `/aod.discover` or `/aod.discover` to add entries directly to the consolidated tables. --- @@ -43,8 +43,8 @@ For projects not using PDL, individual backlog files are still supported. ## What Goes Here -- Features identified during `/triad.prd` that are "nice to have" -- Ideas from `/triad.prd` that were descoped from MVP +- Features identified during `/aod.define` that are "nice to have" +- Ideas from `/aod.define` that were descoped from MVP - User requests that align with vision but aren't prioritized yet - Technical improvements that aren't urgent @@ -64,7 +64,7 @@ _backlog/ # [Feature Name] **Added**: YYYY-MM-DD -**Source**: [/triad.prd | User Request | Team Idea] +**Source**: [/aod.define | User Request | Team Idea] **Priority**: [High | Medium | Low] **Effort Estimate**: [Small | Medium | Large | Unknown] @@ -85,7 +85,7 @@ _backlog/ When a backlog item is ready to build: -1. Create a PRD: `/triad.prd ` +1. Create a PRD: `/aod.define ` 2. Reference the backlog item in the PRD 3. Move or delete the backlog file 4. Follow normal Triad workflow @@ -93,7 +93,7 @@ When a backlog item is ready to build: ## Review Cadence Review the backlog: -- **Quarterly**: During OKR planning — re-score deferred ideas with `/pdl.score` +- **Quarterly**: During OKR planning — re-score deferred ideas with `/aod.score` - **After MVP Launch**: Prioritize next wave of features from `02_USER_STORIES.md` - **When Capacity Opens**: Look for quick wins — check P2 items in `01_IDEAS.md` - **Monthly**: Review deferred ideas for changed circumstances diff --git a/docs/standards/PRODUCT_SPEC_ALIGNMENT.md b/docs/standards/PRODUCT_SPEC_ALIGNMENT.md index cea963d..3ce32c4 100644 --- a/docs/standards/PRODUCT_SPEC_ALIGNMENT.md +++ b/docs/standards/PRODUCT_SPEC_ALIGNMENT.md @@ -37,7 +37,7 @@ Per **Constitution v1.2.0, Principle X: Product-Spec Alignment (NON-NEGOTIABLE)* ### Required Workflow (NON-NEGOTIABLE) ``` -1. /triad.prd → Product Manager creates PRD +1. /aod.define → Product Manager creates PRD │ ├─ PM researches product context (vision, OKRs, roadmap) ├─ PM documents requirements in industry-standard format @@ -50,7 +50,7 @@ Per **Constitution v1.2.0, Principle X: Product-Spec Alignment (NON-NEGOTIABLE)* ├─ PM addresses feedback and finalizes PRD └─ PRD marked as "Approved" in INDEX.md -3. /triad.specify → Create spec.md from PRD +3. /aod.spec → Create spec.md from PRD │ ├─ Architect reads approved PRD ├─ Architect creates spec.md referencing PRD @@ -64,7 +64,7 @@ Per **Constitution v1.2.0, Principle X: Product-Spec Alignment (NON-NEGOTIABLE)* ├─ PM uses sign-off checklist (see below) └─ PM approves OR exercises veto with required changes -5. /triad.plan → Create plan.md from spec +5. /aod.project-plan → Create plan.md from spec │ ├─ Architect creates technical plan ├─ plan.md references product docs @@ -76,7 +76,7 @@ Per **Constitution v1.2.0, Principle X: Product-Spec Alignment (NON-NEGOTIABLE)* ├─ PM checks technical approach serves user stories └─ PM approves OR exercises veto -7. /triad.tasks → Create tasks.md from plan +7. /aod.tasks → Create tasks.md from plan │ ├─ Team Lead breaks down implementation ├─ tasks.md prioritization considers user value @@ -88,7 +88,7 @@ Per **Constitution v1.2.0, Principle X: Product-Spec Alignment (NON-NEGOTIABLE)* ├─ PM checks MVP scope matches PRD in-scope items └─ PM approves OR exercises veto -9. /triad.implement → Execute implementation +9. /aod.build → Execute implementation │ └─ Implementation begins ONLY after PM approval ``` @@ -220,7 +220,7 @@ Product Manager adds this section to spec.md, plan.md, or tasks.md after validat **Status**: ✅ Approved for implementation -**Next Step**: [/triad.plan / /triad.tasks / /triad.implement] +**Next Step**: [/aod.project-plan / /aod.tasks / /aod.build] --- ``` @@ -390,10 +390,10 @@ Constitution v1.2.0, Principle X makes PM sign-off **NON-NEGOTIABLE**. ### 2. Workflow Integration Triad commands enforce PM sign-off: -- `/triad.specify` requires approved PRD -- `/triad.plan` requires PM-approved spec.md -- `/triad.tasks` requires PM-approved plan.md -- `/triad.implement` requires PM-approved tasks.md +- `/aod.spec` requires approved PRD +- `/aod.project-plan` requires PM-approved spec.md +- `/aod.tasks` requires PM-approved plan.md +- `/aod.build` requires PM-approved tasks.md ### 3. Pull Request Requirements @@ -417,7 +417,7 @@ pm_approver: product-manager ### 5. Validation Commands -Use `/triad.analyze` to validate product-spec consistency: +Use `/aod.analyze` to validate product-spec consistency: - Checks PRD → spec → plan → tasks traceability - Validates all artifacts have PM sign-off - Identifies misalignments and missing approvals @@ -431,10 +431,10 @@ Use `/triad.analyze` to validate product-spec consistency: - `root-cause-analyzer` - Dig into complex requirement ambiguities **Commands**: -- `/triad.prd ` - Create new PRD -- `/triad.specify` - Create spec from PRD -- `/triad.analyze` - Validate product-spec consistency -- `/triad.clarify` - Ask clarifying questions +- `/aod.define ` - Create new PRD +- `/aod.spec` - Create spec from PRD +- `/aod.analyze` - Validate product-spec consistency +- `/aod.clarify` - Ask clarifying questions **Agents**: - `product-manager` - Product Manager with alignment validation expertise diff --git a/docs/standards/TRIAD_COLLABORATION.md b/docs/standards/TRIAD_COLLABORATION.md index f626694..59e97ec 100644 --- a/docs/standards/TRIAD_COLLABORATION.md +++ b/docs/standards/TRIAD_COLLABORATION.md @@ -101,7 +101,7 @@ Step 0.5: Architect Provides Baseline (INFRASTRUCTURE ONLY) ├─ Create: specs/{feature-id}/architect-baseline.md └─ Output: Infrastructure baseline report handed to PM -Step 1: PM Drafts PRD (via /triad.prd) +Step 1: PM Drafts PRD (via /aod.define) ├─ Reads architecture docs ├─ Incorporate Architect baseline into "Current State" section ├─ Define product requirements (What & Why) but NOT timeline @@ -126,7 +126,7 @@ Step 4: PM Finalizes PRD ├─ Incorporate: Tech-Lead timeline + Architect feedback ├─ Validate: Product requirements still achievable ├─ Publish: Approved PRD with triple validation -└─ Output: Final PRD ready for /triad.specify +└─ Output: Final PRD ready for /aod.spec ``` **Timeline**: ~2-4 hours for full Triad review cycle @@ -143,7 +143,7 @@ Step 4: PM Finalizes PRD Step 0: PM Analyzes Product Need └─ Same as infrastructure workflow -Step 1: PM Drafts PRD (via /triad.prd) +Step 1: PM Drafts PRD (via /aod.define) ├─ Define product requirements ├─ Mark timeline as "TBD" └─ Output: Draft PRD @@ -401,7 +401,7 @@ Step 3: PM Finalizes PRD **Automated Triad (Future)**: ```bash # Auto-invoke Triad for PRD creation -/triad.prd +/aod.define # What it does: # 1. Auto-detect infrastructure vs feature work diff --git a/scripts/extract.sh b/scripts/extract.sh new file mode 100755 index 0000000..09533dd --- /dev/null +++ b/scripts/extract.sh @@ -0,0 +1,320 @@ +#!/bin/bash +# scripts/extract.sh - Agentic Oriented Development Kit Extraction Manifest +# +# Manifest-driven extraction from private repo to public template repo. +# Supports initial extraction and ongoing synchronization (--sync). +# +# Usage: +# ./scripts/extract.sh [OPTIONS] +# +# Options: +# --sync Re-sync from private repo (re-applies content resets) +# --dry-run Preview operations without copying files +# --dest DIR Override destination directory (default: ../agentic-oriented-development-kit) +# +# This script is the single source of truth for what constitutes template content. + +set -euo pipefail + +# Colors +RED='\033[0;31m' +GREEN='\033[0;32m' +BLUE='\033[0;34m' +YELLOW='\033[1;33m' +NC='\033[0m' + +# Defaults +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SOURCE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +DEST_DIR="${SOURCE_DIR}/../agentic-oriented-development-kit" +DRY_RUN=false +SYNC_MODE=false + +# Counters +FILES_COPIED=0 +FILES_RESET=0 +FILES_CREATED=0 +FILES_SKIPPED=0 + +# Parse arguments +while [[ $# -gt 0 ]]; do + case $1 in + --sync) SYNC_MODE=true; shift ;; + --dry-run) DRY_RUN=true; shift ;; + --dest) DEST_DIR="$2"; shift 2 ;; + -h|--help) + echo "Usage: $0 [--sync] [--dry-run] [--dest DIR]" + echo "" + echo "Options:" + echo " --sync Re-sync (re-applies content resets)" + echo " --dry-run Preview operations without copying" + echo " --dest DIR Override destination directory" + exit 0 + ;; + *) echo -e "${RED}Unknown option: $1${NC}"; exit 1 ;; + esac +done + +# ============================================================================ +# MANIFEST: Template files and directories to extract +# This is the canonical definition of what constitutes template content. +# ============================================================================ + +MANIFEST_DIRS=( + # Core Agent Infrastructure + ".claude/agents" + ".claude/skills" + ".claude/commands" + ".claude/rules" + ".claude/lib" + ".claude/config" + + # Core Principles & Standards + "docs/core_principles" + "docs/standards" + + # Architecture Templates + "docs/architecture" + + # DevOps Templates (subdirectories) + "docs/devops/01_Local" + "docs/devops/02_Staging" + "docs/devops/03_Production" + + # Product Templates (subdirectories) + "docs/product/03_Product_Roadmap" + "docs/product/04_Journey_Maps" + "docs/product/05_User_Stories" + "docs/product/06_OKRs" + + # Guides + "docs/guides" + + # Testing + "docs/testing" + + # AOD Scripts & Templates + ".aod/scripts/bash" + ".aod/templates" +) + +MANIFEST_FILES=( + # .claude root files + ".claude/README.md" + ".claude/INFRASTRUCTURE_SETUP_SUMMARY.md" + ".claude/mcp-config.json" + + # Product templates (specific files only) + "docs/product/01_Product_Vision/README.md" + "docs/product/02_PRD/000-example-feature.md" + "docs/product/02_PRD/INDEX.md" + "docs/product/_backlog/README.md" + "docs/product/_backlog/01_IDEAS.md" + "docs/product/_backlog/02_USER_STORIES.md" + + # DevOps root files + "docs/devops/README.md" + "docs/devops/CI_CD_GUIDE.md" + "docs/devops/FEATURE_MATRIX.md" + + # Doc root files + "docs/AOD_TRIAD.md" + "docs/DOCS_TO_UPDATE_AFTER_NEW_FEATURE.md" + "docs/INSTITUTIONAL_KNOWLEDGE.md" + + # AOD memory + ".aod/memory/constitution.md" + + # Scripts + "scripts/init.sh" + "scripts/check.sh" + + # Root files + "CLAUDE.md" + "Makefile" + ".env.example" + ".gitignore" + "MIGRATION.md" + "LICENSE" +) + +# Files that need content reset after copy (FR-2) +# These are copied first, then overwritten with template-clean content +CONTENT_RESET_FILES=( + "docs/product/02_PRD/INDEX.md" + "docs/product/_backlog/01_IDEAS.md" + "docs/product/_backlog/02_USER_STORIES.md" +) + +# ============================================================================ +# FUNCTIONS +# ============================================================================ + +log_action() { + local action="$1" + local path="$2" + if $DRY_RUN; then + echo -e " ${YELLOW}[DRY-RUN]${NC} ${action}: ${path}" + else + echo -e " ${GREEN}${action}${NC}: ${path}" + fi +} + +copy_file() { + local src="$1" + local dest="$2" + if [[ ! -f "$src" ]]; then + echo -e " ${RED}MISSING${NC}: $src" + FILES_SKIPPED=$((FILES_SKIPPED + 1)) + return + fi + log_action "COPY" "$dest" + if ! $DRY_RUN; then + mkdir -p "$(dirname "$dest")" + cp "$src" "$dest" + fi + FILES_COPIED=$((FILES_COPIED + 1)) +} + +copy_dir() { + local src="$1" + local dest="$2" + if [[ ! -d "$src" ]]; then + echo -e " ${RED}MISSING DIR${NC}: $src" + FILES_SKIPPED=$((FILES_SKIPPED + 1)) + return + fi + log_action "COPY DIR" "$dest" + if ! $DRY_RUN; then + mkdir -p "$dest" + # Copy all files preserving structure + while IFS= read -r f; do + local target="$dest/$f" + mkdir -p "$(dirname "$target")" + cp "$src/$f" "$target" + FILES_COPIED=$((FILES_COPIED + 1)) + done < <(cd "$src" && find . -type f) + else + # Count files for dry-run + local count + count=$(find "$src" -type f | wc -l | tr -d ' ') + FILES_COPIED=$((FILES_COPIED + count)) + fi +} + +# ============================================================================ +# MAIN EXECUTION +# ============================================================================ + +echo -e "${BLUE}Agentic Oriented Development Kit — Extraction${NC}" +echo "" +echo " Source: $SOURCE_DIR" +echo " Destination: $DEST_DIR" +echo " Mode: $(if $SYNC_MODE; then echo 'SYNC'; else echo 'EXTRACT'; fi)" +echo " Dry Run: $DRY_RUN" +echo "" + +# Create destination if needed +if ! $DRY_RUN; then + mkdir -p "$DEST_DIR" +fi + +# --- Step 1: Copy directories --- +echo -e "${BLUE}Step 1: Copying template directories...${NC}" +for dir in "${MANIFEST_DIRS[@]}"; do + copy_dir "$SOURCE_DIR/$dir" "$DEST_DIR/$dir" +done + +# --- Step 2: Copy individual files --- +echo "" +echo -e "${BLUE}Step 2: Copying individual template files...${NC}" +for file in "${MANIFEST_FILES[@]}"; do + copy_file "$SOURCE_DIR/$file" "$DEST_DIR/$file" +done + +# --- Step 3: Create .gitkeep for empty directories --- +echo "" +echo -e "${BLUE}Step 3: Creating .gitkeep for empty directories...${NC}" + +GITKEEP_DIRS=( + "specs" + "docs/agents" + "docs/architecture/01_system_design" +) + +for dir in "${GITKEEP_DIRS[@]}"; do + log_action "GITKEEP" "$dir/.gitkeep" + if ! $DRY_RUN; then + mkdir -p "$DEST_DIR/$dir" + touch "$DEST_DIR/$dir/.gitkeep" + fi + FILES_CREATED=$((FILES_CREATED + 1)) +done + +# --- Step 4: Content resets (FR-2) --- +# Always run on --sync; on initial extract these will be overwritten later in Phase 3B +if $SYNC_MODE; then + echo "" + echo -e "${BLUE}Step 4: Applying content resets (sync mode)...${NC}" + + # INDEX.md: Reset to show only example feature + if ! $DRY_RUN; then + cat > "$DEST_DIR/docs/product/02_PRD/INDEX.md" << 'RESET_EOF' +# PRD Index + +| # | Feature | Status | Date | +|---|---------|--------|------| +| 000 | [Example Feature](000-example-feature.md) | Template | — | +RESET_EOF + fi + log_action "RESET" "docs/product/02_PRD/INDEX.md" + FILES_RESET=$((FILES_RESET + 1)) + + # IDEAS.md: Reset to empty table + if ! $DRY_RUN; then + cat > "$DEST_DIR/docs/product/_backlog/01_IDEAS.md" << 'RESET_EOF' +# Ideas Backlog + +| ID | Idea | ICE Score | Status | Date | +|----|------|-----------|--------|------| +RESET_EOF + fi + log_action "RESET" "docs/product/_backlog/01_IDEAS.md" + FILES_RESET=$((FILES_RESET + 1)) + + # USER_STORIES.md: Reset to empty table + if ! $DRY_RUN; then + cat > "$DEST_DIR/docs/product/_backlog/02_USER_STORIES.md" << 'RESET_EOF' +# User Stories Backlog + +| ID | User Story | Priority | Status | Feature | +|----|-----------|----------|--------|---------| +RESET_EOF + fi + log_action "RESET" "docs/product/_backlog/02_USER_STORIES.md" + FILES_RESET=$((FILES_RESET + 1)) +fi + +# --- Summary --- +echo "" +echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" +echo -e "${GREEN}Extraction Summary${NC}" +echo " Files copied: $FILES_COPIED" +echo " Files reset: $FILES_RESET" +echo " Files created: $FILES_CREATED" +echo " Files skipped: $FILES_SKIPPED" +echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + +if [[ $FILES_SKIPPED -gt 0 ]]; then + echo -e "${YELLOW}Warning: $FILES_SKIPPED files were not found in source.${NC}" + exit 1 +fi + +if $SYNC_MODE && ! $DRY_RUN; then + echo "" + echo -e "${YELLOW}Sync complete. Run verification suite before committing:${NC}" + echo " cd $DEST_DIR && grep -rn 'product-led-spec-kit\|Spec Kit\|spec-kit\|SPEC_KIT' ." +fi + +echo "" +echo -e "${GREEN}Done.${NC}" diff --git a/scripts/init.sh b/scripts/init.sh index e6570bf..cd5212a 100755 --- a/scripts/init.sh +++ b/scripts/init.sh @@ -114,13 +114,13 @@ echo " 1. Review your product vision:" echo " docs/product/01_Product_Vision/README.md" echo "" echo " 2. Create your first PRD:" -echo " /triad.prd " +echo " /aod.define " echo "" -echo " 3. Follow the Triad workflow:" -echo " /triad.specify → Define requirements" -echo " /triad.plan → Create technical plan" -echo " /triad.tasks → Generate task list" -echo " /triad.implement → Execute implementation" +echo " 3. Follow the AOD workflow:" +echo " /aod.spec → Define requirements" +echo " /aod.project-plan → Create technical plan" +echo " /aod.tasks → Generate task list" +echo " /aod.build → Execute implementation" echo "" echo -e "${BLUE}📚 Key Documentation:${NC}" echo " - Getting Started: docs/GETTING_STARTED.md" diff --git a/specs/000-example-feature/plan.md b/specs/000-example-feature/plan.md index 0dcde68..9217c53 100644 --- a/specs/000-example-feature/plan.md +++ b/specs/000-example-feature/plan.md @@ -1,6 +1,6 @@ # Plan: Example Feature -> **Example** -- delete this directory after creating your first real feature with `/triad.plan`. +> **Example** -- delete this directory after creating your first real feature with `/aod.project-plan`. **Feature ID**: 000 **Status**: Example diff --git a/specs/000-example-feature/spec.md b/specs/000-example-feature/spec.md index 0948c12..b860af7 100644 --- a/specs/000-example-feature/spec.md +++ b/specs/000-example-feature/spec.md @@ -1,6 +1,6 @@ # Spec: Example Feature -> **Example** -- delete this directory after creating your first real feature with `/triad.specify`. +> **Example** -- delete this directory after creating your first real feature with `/aod.spec`. **Feature ID**: 000 **Status**: Example diff --git a/specs/000-example-feature/tasks.md b/specs/000-example-feature/tasks.md index d4275e7..27e96e1 100644 --- a/specs/000-example-feature/tasks.md +++ b/specs/000-example-feature/tasks.md @@ -1,6 +1,6 @@ # Tasks: Example Feature -> **Example** -- delete this directory after creating your first real feature with `/triad.tasks`. +> **Example** -- delete this directory after creating your first real feature with `/aod.tasks`. **Feature ID**: 000 **Status**: Example