bodangren avatar

synthesisflow-skills

SynthesisFlow: Modular skills for spec-driven development with hybrid LLM-guided + helper-script architecture

GitHub stars
11

Install

/plugin install synthesisflow-skills@bodangren-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add bodangren/git-workflow.

Contents

Discovered from source

Skills 13

Agent Integrator Skill

Purpose

Idempotently create or update the AGENTS.md file in a project to register AgenticDev skills for discovery by AI agents. This skill ensures that any compatible AI agent working in the repository can discover and use the AgenticDev methodology and available skills.

When to Use

Use this skill in the following situations:

  • After running project-init to initialize AgenticDev in a new project
  • When installing AgenticDev skills in an existing project
  • After adding new skills to the .claude/skills/ directory
  • Updating the agent guide with new workflow information
  • Ensuring AI agents can discover available AgenticDev capabilities

Prerequisites

  • Project has .claude/skills/ directory with AgenticDev skills installed
  • Write permissions to project root directory
  • Optional: Existing AGENTS.md file (script creates if missing)

AGENTS.md Purpose

The AGENTS.md file serves as a discovery mechanism for AI agents:

  • Agent Discovery: AI agents read this file to learn about available workflows
  • Methodology Documentation: Explains AgenticDev philosophy and core principles
  • Skill Catalog: Lists all available skills and their purposes
  • Getting Started: Provides entry point for new agents working in the project

Workflow

Step 1: Determine If Update Is Needed

Check if AGENTS.md needs to be created or updated:

# Check if file exists
ls -la AGENTS.md

# Check if AgenticDev section exists
grep "SYNTHESIS_FLOW" AGENTS.md

Step 2: Run the Helper Script

Execute the script to update AGENTS.md:

# Use default location (AGENTS.md in project root)
bash scripts/update-agents-file.sh

# Or specify custom location
bash scripts/update-agents-file.sh -f path/to/custom-agents.md

Step 3: Understand What the Script Does

The helper script uses an idempotent update strategy:

  1. Creates file if missing:

    • Uses touch to ensure target file exists
    • Safe to run even if file doesn't exist yet
  2. Checks for existing content:

    • Looks for <!-- SYNTHESIS_FLOW_START --> marker
    • Determines if this is an update or initial creation
  3. Updates existing content:

    • If markers found, replaces content between markers
    • Preserves any other content in the file
    • Uses awk to safely replace marked section
  4. Adds new content:

    • If markers not found, appends AgenticDev guide to end of file
    • Adds both start and end markers for future updates
  5. Preserves other content:

    • Only modifies content between markers
    • Safe to run multiple times (idempotent)
    • Won't overwrite other project documentation

Step 4: Verify the Update

Check that AGENTS.md was updated correctly:

# View the file
cat AGENTS.md

# Verify markers are present
grep -A 5 "SYNTHESIS_FLOW_START" AGENTS.md

Step 5: Commit the Changes

If the update looks correct, commit to the repository:

git add AGENTS.md
git commit -m "docs: Update AGENTS.md with AgenticDev guide"
git push

Error Handling

Permission Denied

Symptom: Script cannot write to AGENTS.md

Solution:

  • Check file permissions: ls -la AGENTS.md
  • Ensure you have write access to project root
  • Run with appropriate permissions

Marker Corruption

Symptom: Content between markers is malformed

Solution:

  • Manually edit AGENTS.md to fix markers
  • Ensure both <!-- SYNTHESIS_FLOW_START --> and <!-- SYNTHESIS_FLOW_END --> are present
  • Re-run script to regenerate content

Custom File Path Issues

Symptom: Script creates file in wrong location

Solution:

  • Use -f flag with full path: bash scripts/update-agents-file.sh -f /full/path/to/file.md
  • Verify path exists: mkdir -p /path/to/directory
  • Check current working directory

Notes

  • Idempotent design: Safe to run multiple times without side effects
  • Preserves other content: Only updates content between markers
  • Marker-based: Uses HTML comments as markers (invisible in rendered markdown)
  • Default location: AGENTS.md in project root (standard convention)
  • Custom locations: Use -f flag for alternative file paths
  • Run after setup: Typically run once after project-init, then rarely
  • Update when skills change: Re-run if new skills are added or removed
  • AI agent discovery: Helps agents understand available AgenticDev capabilities
  • Version control: Commit AGENTS.md so all contributors see the guide

Change Integrator Skill

Purpose

Perform post-merge integration tasks after a code PR is successfully merged. This skill completes the development cycle by moving approved specs from docs/changes/ to docs/specs/, updating the retrospective with learnings, cleaning up feature branches, and updating project board status. It ensures the repository remains clean and the documentation reflects the current state.

A key feature of this skill is the automated maintenance of RETROSPECTIVE.md. When the file grows too large, the script automatically uses the Gemini CLI to summarize older entries, keeping the document concise and readable while preserving key historical learnings.

When to Use

Use this skill in the following situations:

  • After a code PR is merged to main
  • Completing a feature that had a spec proposal
  • Finalizing a task and cleaning up branches
  • Updating retrospective with completed work
  • Moving approved specs to source-of-truth location

Prerequisites

  • Code PR has been merged to main branch
  • Feature branch name is known
  • PR number is known
  • Project board item ID is known (if using project boards)
  • gh CLI tool installed and authenticated
  • gemini CLI tool installed and authenticated
  • Currently on main branch with latest changes

Workflow

Step 1: Verify PR is Merged

Before running integration, confirm the PR was successfully merged:

gh pr view PR_NUMBER --json state,mergedAt

Ensure the state is "MERGED" and mergedAt timestamp is populated.

Step 2: Identify Integration Needs

Determine what needs to be integrated:

  • Spec files: Was this a feature with a spec proposal in docs/changes/?
  • Branch cleanup: What is the feature branch name?
  • Project board: What is the item ID to mark as done?
  • Retrospective: What were the key learnings from this task?

Step 3: Run the Helper Script (Optional)

If using the automated script for integration:

bash scripts/integrate-change.sh -p PR_NUMBER -b BRANCH_NAME -i ITEM_ID -w "WENT_WELL" -l "LESSON" [-c CHANGE_DIR]

Parameters:

  • -p: PR number that was merged
  • -b: Feature branch name (e.g., feat/45-restructure-doc-indexer)
  • -i: Project board item ID
  • -w: A quote about what went well.
  • -l: A quote about the key lesson learned.
  • -c: Optional path to change proposal directory (e.g., docs/changes/my-feature)

Step 4: Understand What the Script Does

The helper script automates these steps:

  1. Verifies PR is merged: Queries GitHub API and aborts if PR is not in MERGED state.
  2. Switches to main and pulls: Ensures work is on the latest main branch.
  3. Deletes feature branch: Removes both remote and local branches.
  4. Integrates spec files (if applicable): Moves spec-delta.md to docs/specs/ and commits the change.
  5. Updates project board: Sets the task status to "Done".
  6. Updates retrospective: Appends a new entry. If RETROSPECTIVE.md exceeds a line limit (e.g., 150 lines), it automatically summarizes older sprint entries using the Gemini CLI to keep the file manageable.
  7. Pushes all changes: Pushes integration commits to main.

Step 5: Manual Integration (Alternative)

If not using the script, perform these steps manually:

5a. Switch to Main and Update
git switch main
git pull
5b. Delete Feature Branch
# Delete remote branch
git push origin --delete feat/45-restructure-doc-indexer

# Delete local branch
git branch -D feat/45-restructure-doc-indexor
5c. Integrate Spec Files (If Applicable)

If the feature had a spec proposal:

# Identify the change directory
ls docs/changes/

# Move spec-delta to specs
SPEC_NAME="my-feature"
cp docs/changes/$SPEC_NAME/spec-delta.md docs/specs/$SPEC_NAME.md

# Remove change directory
rm -r docs/changes/$SPEC_NAME

# Commit integration
git add docs/
git commit -m "docs: Integrate approved spec from feat/45-my-feature"
5d. Update Project Board
gh project item-edit \
  --project-id PROJECT_ID \
  --id ITEM_ID \
  --field-id FIELD_ID \
  --single-select-option-id DONE_OPTION_ID
5e. Update Retrospective

Add learnings to RETROSPECTIVE.md following the established format. See the retrospective for examples.

# Edit RETROSPECTIVE.md to add entry
git add RETROSPECTIVE.md
git commit -m "docs: Add retrospective for PR #45"
5f. Push Changes
git push

Step 6: Verify Integration

After integration completes:

# Verify branch deleted
git branch -a | grep feat/45

# Verify spec integrated (if applicable)
ls docs/specs/

# Verify retrospective updated
tail -20 RETROSPECTIVE.md

# Verify project board updated
gh project item-list PROJECT_NUMBER --owner @me

Automated Retrospective Summarization

To prevent RETROSPECTIVE.md from becoming unmanageably long, the integrate-change.sh script includes an automated summarization feature powered by the Gemini CLI.

How it works:

  1. Threshold Check: Before adding a new entry, the script checks the line count of RETROSPECTIVE.md.
  2. Trigger: If the line count exceeds a defined threshold (e.g., 150 lines), the summarization process is triggered.
  3. Preservation: The script preserves the initial sections of the file, including the introduction and the "Historical Learnings" section.
  4. Summarization: It takes the older sprint entries, sends them to the gemini CLI, and requests a concise summary that preserves key learnings and markdown structure.
  5. Reconstruction: The script then overwrites RETROSPECTIVE.md with the preserved header, a new "Summarized Sprints (via Gemini)" section, and the newly generated summary.
  6. New Entry: Finally, it appends the new retrospective entry to the freshly summarized file.

This ensures that the file remains a valuable and readable source of information without requiring manual pruning.

Error Handling

PR Not Merged

Symptom: Script reports PR is not in MERGED state

Solution:

  • Verify PR number is correct
  • Wait for PR to be merged
  • Check auto-merge status if enabled
  • Manually merge PR if needed

Branch Already Deleted

Symptom: Git reports branch doesn't exist

Solution:

  • This is normal if auto-merge deleted the branch
  • Continue with remaining integration steps
  • Script handles this gracefully with || echo "..."

Spec Directory Not Found

Symptom: Script cannot find change directory

Solution:

  • Verify the change directory path is correct
  • Check if this feature even had a spec proposal
  • Skip spec integration step if not applicable
  • Use -c flag only when spec exists

Permission Denied on Project Board

Symptom: GitHub API returns 403 error

Solution:

  • Verify project board IDs are correct
  • Ensure you have write access to the project
  • Check gh authentication: gh auth status
  • Update script configuration variables if needed

Gemini CLI Issues

Symptom: The script fails during the "Updating retrospective..." step with an error related to the gemini command.

Solution:

  • Ensure the gemini CLI is installed and in your system's PATH.
  • Verify you are authenticated. Run gemini auth if needed.
  • Check for any Gemini API-related issues or outages.
  • If the issue persists, you can temporarily increase the RETROSPECTIVE_MAX_LINES variable in the script to bypass the summarization and add your entry.

Retrospective Format Issues

Symptom: The automated summary has formatting problems or seems to have lost critical information.

Solution:

  • The summarization is automated and may not be perfect. The original, unsummarized content is not retained by the script.
  • You can review the commit history for RETROSPECTIVE.md in git to find the previous version if you need to recover information.
  • Manually edit the summarized content to fix any formatting issues.
  • Consider adjusting the prompt sent to the Gemini CLI within the summarize_retrospective function in the script for better results in the future.

Configuration Notes

The script uses these hardcoded configuration variables (lines 31-33):

PROJECT_ID="PVT_kwHOARC_Ns4BG9YU"
FIELD_ID="PVTSSF_lAHOARC_Ns4BG9YUzg32qas"  # Workflow Stage
DONE_OPTION_ID="6bc77efe"

To adapt for your project:

  1. Find your project ID: gh project list --owner @me
  2. Find field ID: gh api graphql -f query='...' (see GitHub docs)
  3. Find done option ID: Query project field values
  4. Update these variables in the script

Note: A future version should detect these dynamically.

Notes

  • Run after PR is merged: This is post-merge cleanup, not pre-merge preparation
  • Spec integration is optional: Only for features that started with spec proposals
  • Retrospective is required: Always update with learnings from completed work
  • Branch cleanup prevents clutter: Keeps repository clean and organized
  • Project board sync: Ensures status accurately reflects completed work
  • Manual steps work too: Script is a convenience, not required
  • Integration commits go to main: These are documentation updates, not code changes
  • Keep retrospective focused: Capture what worked, what didn't, and key lessons
  • One PR per integration: Run the workflow once per merged PR
  • Script is not fully automated: Still requires parameters and decision-making

Document Indexer Skill

Purpose

Provide just-in-time context about available project documentation without loading full file content into the context window. The doc-indexer scans all markdown files in the docs/ directory, extracts their YAML frontmatter metadata, and returns a structured map of available documentation. This enables efficient discovery of specs, plans, retrospectives, and other documentation while minimizing token usage.

When to Use

Use this skill in the following situations:

  • At the beginning of any work session to understand the current state of documentation
  • When starting work on a new issue to identify relevant specs and context
  • Before proposing changes to understand existing specifications
  • When planning a sprint to review available approved specs
  • Anytime you need an overview of project documentation without reading full files

Prerequisites

  • The project must have a docs/ directory
  • Documentation files should follow the convention of including YAML frontmatter
  • The jq tool is NOT required (script works without it)

Workflow

Step 1: Run the Documentation Scanner

Execute the helper script to scan all markdown files in the docs/ directory:

bash scripts/scan-docs.sh

This will output a human-readable summary showing each document's frontmatter metadata.

For machine-readable JSON output (useful for programmatic processing):

bash scripts/scan-docs.sh -j

Step 2: Review the Documentation Map

The scanner returns information about all markdown files found in docs/, including:

  • File path: Location of the documentation file
  • Frontmatter metadata: Key-value pairs from YAML frontmatter (title, status, type, etc.)
  • Compliance warnings: Files missing YAML frontmatter are flagged

Example human-readable output:

---
file: docs/specs/001-synthesis-flow.md
title: AgenticDev Methodology
status: approved
type: spec
---
file: docs/changes/my-feature/proposal.md
title: My Feature Proposal
status: in-review
type: proposal
[WARNING] Non-compliant file (no frontmatter): docs/README.md

Example JSON output:

[
  {
    "file": "docs/specs/001-synthesis-flow.md",
    "compliant": true,
    "frontmatter": {
      "title": "AgenticDev Methodology",
      "status": "approved",
      "type": "spec"
    }
  },
  {
    "file": "docs/README.md",
    "compliant": false,
    "frontmatter": null
  }
]

Step 3: Use the Map to Identify Relevant Documentation

Based on the documentation map, identify which specific files to read for your current task:

  • For implementation work: Look for approved specs related to your issue
  • For spec proposals: Review existing specs to understand the current state
  • For sprint planning: Identify approved specs ready for implementation
  • For learning context: Find retrospectives and design docs

Step 4: Read Specific Documentation Files

Once you've identified relevant files from the map, use the Read tool to load their full content:

# Example: Read a specific spec identified from the map
Read docs/specs/001-synthesis-flow.md

This two-step approach (scan first, then read selectively) minimizes token usage while ensuring you have access to all necessary context.

Error Handling

No docs/ Directory

Symptom: Script reports "No such file or directory"

Solution:

  • Verify you're in the project root directory
  • Check if the project has been initialized with project-init skill
  • Create docs/ directory structure if needed

Files Missing Frontmatter

Symptom: Script outputs "[WARNING] Non-compliant file (no frontmatter): ..."

Impact: These files won't have structured metadata in the output

Solution:

  • Add YAML frontmatter to documentation files for better discoverability
  • Frontmatter should be at the top of the file between --- markers
  • Example format:
    ---
    title: My Document
    status: draft
    type: design
    ---
    
    # Document content starts here
    

Script Permission Errors

Symptom: "Permission denied" when running the script

Solution:

chmod +x scripts/scan-docs.sh

Output Interpretation Guide

Frontmatter Fields

Common frontmatter fields you'll encounter:

  • title: Human-readable document title
  • status: Document state (draft, in-review, approved, archived)
  • type: Document category (spec, proposal, design, retrospective, plan)
  • epic: Associated epic issue number
  • sprint: Sprint identifier
  • author: Document author
  • created: Creation date
  • updated: Last update date

Using JSON Output Programmatically

The JSON output mode is particularly useful when:

  • Filtering documents by specific criteria (e.g., only approved specs)
  • Counting documents by type or status
  • Building automated workflows
  • Integrating with other tools

Example using jq to filter approved specs:

bash scripts/scan-docs.sh -j | jq '.[] | select(.frontmatter.status == "approved")'

Notes

  • The scanner is non-invasive and read-only - it never modifies files
  • Large projects with many docs benefit most from this just-in-time approach
  • The script scans recursively through all subdirectories in docs/
  • Empty frontmatter sections are treated as non-compliant
  • The scan is fast and can be run frequently without performance concerns
  • Consider running this at the start of each work session to stay current with documentation changes

Doc Validator

Purpose

Scan the repository for Markdown files (.md) located outside of predefined, allowed directories. This skill helps prevent documentation sprawl and enforces a consistent repository structure by warning about .md files in non-standard locations.

When to Use

Use this skill in the following situations:

  • During code reviews to ensure documentation is properly organized
  • As part of CI/CD quality checks
  • Before merging changes that add new documentation
  • When auditing the repository for documentation compliance
  • Called automatically by other skills (issue-executor, change-integrator)

Prerequisites

  • Standard bash utilities (find, bash)
  • Project follows AgenticDev directory conventions

Workflow

Step 1: Run the Validator

Execute the validator script to scan for misplaced Markdown files:

bash skills/doc-validator/scripts/doc-validator.sh

Step 2: Review Warnings

The script outputs warnings for any .md files found in non-standard locations:

WARNING: Markdown file in non-standard location: ./src/notes.md
WARNING: Markdown file in non-standard location: ./scripts/temp-docs.md

Step 3: Take Action

For each warning:

  1. Determine if the file should exist: Is it temporary or abandoned?
  2. Move to proper location: Relocate to docs/ or appropriate skill directory
  3. Add to allowed patterns: If it's a legitimate exception (update the script)
  4. Remove the file: If it's no longer needed

Allowed Patterns

The validator considers these locations as standard and will not warn about them:

  • Root-level documentation: README.md, LICENSE, AGENTS.md, RETROSPECTIVE.md
  • Main docs directory: docs/**/*.md (all subdirectories)
  • Skill documentation:
    • skills/*/SKILL.md
    • skills/*/references/*.md
    • skills/*/examples/*.md
    • .claude/skills/*/SKILL.md
    • .claude/skills/*/references/*.md
    • .claude/skills/*/examples/*.md

Error Handling

False Positives

Symptom: The validator warns about a file that should be allowed

Solution:

  • Check if the file matches an allowed pattern
  • If it's a legitimate location not covered by current patterns, update doc-validator.sh
  • Add the new pattern to the ALLOWED_PATTERNS array

Script Not Finding Files

Symptom: The script runs but finds no files or fewer files than expected

Solution:

  • Verify you're running from the repository root
  • Check file permissions
  • Ensure .md files exist in the repository

Permission Denied

Symptom: Script cannot access certain directories

Solution:

  • Check directory permissions
  • Ensure the script is executable: chmod +x skills/doc-validator/scripts/doc-validator.sh

Notes

  • Non-destructive: The script only reports issues, it does not move or delete files
  • Excludes: Automatically skips .git/ and .agenticdev-backup-* directories
  • Integration: Designed to be called by other skills as part of quality checks
  • Extensible: Easy to add new allowed patterns by updating the script
  • CI-friendly: Returns parsable output suitable for automated checks

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.

Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:

  • Purpose: What problem does this interface solve? Who uses it?
  • Tone: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
  • Constraints: Technical requirements (framework, performance, accessibility).
  • Differentiation: What makes this UNFORGETTABLE? What's the one thing someone will remember?

CRITICAL: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:

  • Production-grade and functional
  • Visually striking and memorable
  • Cohesive with a clear aesthetic point-of-view
  • Meticulously refined in every detail

Frontend Aesthetics Guidelines

Focus on:

  • Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
  • Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
  • Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
  • Spatial Composition: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
  • Backgrounds & Visual Details: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.

NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.

Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.

IMPORTANT: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.

Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

Issue Executor

Purpose

To kickstart the development workflow for a single GitHub issue by generating a comprehensive, context-aware implementation plan. This skill leverages the Gemini CLI to synthesize issue details, relevant specifications, and historical learnings from the project retrospective into a clear, actionable plan. It then creates an isolated feature branch, setting the stage for focused, spec-driven development.

When to Use

Use this skill in the following situations:

  • Starting work on a planned GitHub issue from the current sprint.
  • Beginning a work session and wanting a synthesized plan before coding.
  • Needing to load and understand all context for an issue efficiently.

Prerequisites

  • GitHub repository with issues created (via sprint-planner skill).
  • Git working directory is clean (no uncommitted changes).
  • Currently on the main branch.
  • gh CLI tool installed and authenticated.
  • jq tool installed for JSON parsing.
  • gemini CLI tool installed and authenticated.
  • Project has a docs/ structure with specs and a RETROSPECTIVE.md.

Core Principles

Context is King

Instead of just viewing files, the skill synthesizes all relevant context into a coherent plan:

  • Issue details: Requirements and acceptance criteria.
  • Spec files: All specifications referenced in the issue.
  • Retrospective: Learnings from past work to avoid repeating mistakes.

Isolation

All work happens on a dedicated feature branch to:

  • Protect the main branch from work-in-progress.
  • Enable a clean Pull Request workflow.
  • Allow abandoning work without impacting the main codebase.

Atomic Work

Each issue represents a single, well-defined task that can be completed and reviewed as a unit.

Workflow

Step 1: Identify the Issue

Determine which issue to work on. The user specifies the issue number (e.g., #45).

Step 2: Run the Helper Script

Execute the work-on-issue.sh script with the issue number:

bash scripts/work-on-issue.sh 45

Step 3: Understand What the Script Does

The helper script automates these critical setup steps:

  1. Validates Prerequisites: Checks for jq, a clean git status, and being on the main branch.
  2. Fetches Issue Details: Retrieves the issue title and body from GitHub.
  3. Finds Context Files: Locates all referenced spec files (.md) in docs/specs/ or docs/changes/ and identifies RETROSPECTIVE.md.
  4. Synthesizes Implementation Plan: Constructs a detailed prompt with the issue details and file context (@file syntax) and calls the gemini CLI. It asks Gemini to produce a step-by-step implementation plan based on all provided information.
  5. Displays the Plan: Prints the generated plan from Gemini to the console.
  6. Creates Feature Branch: Generates a conventional branch name (e.g., feat/45-restructure-doc-indexer) and checks it out.
  7. Confirms Readiness: Displays a success message confirming that the branch is ready and the plan has been generated.

Step 4: Review the Implementation Plan

After the script completes, carefully review the implementation plan generated by Gemini. This plan is your starting guide for the implementation, synthesized from all available project context.

Step 5: Begin Implementation

With the plan and feature branch ready:

  1. Follow the steps outlined in the generated plan.
  2. Write code that meets the acceptance criteria.
  3. Test your changes thoroughly.
  4. Commit work incrementally.
  5. Push to the remote branch when ready to create a Pull Request.

Error Handling

Working Directory Not Clean / Not on Main Branch

Symptom: Script reports uncommitted changes or that you are not on the main branch. Solution: Commit, stash, or discard your changes. Switch back to the main branch before re-running the script.

Missing jq or gemini Tool

Symptom: Script reports that jq or gemini is not installed. Solution: Install the required tool. For jq, use sudo apt install jq or brew install jq. For gemini, follow its official installation instructions.

Gemini CLI Issues

Symptom: The script fails while generating the implementation plan, showing an error from the gemini command. Solution:

  • Ensure the gemini CLI is installed correctly and is in your system's PATH.
  • Verify your authentication status with gemini auth.
  • Check for Gemini API outages or connectivity issues.
  • Examine the prompt being sent to Gemini for any syntax errors.

Spec File Not Found

Symptom: The script runs, but the plan doesn't seem to include context from a spec file you expected. Solution:

  • Ensure the issue body explicitly references the spec file with its full path (e.g., docs/specs/my-spec.md). The script only includes files that are directly mentioned.
  • Verify the referenced file path is correct and the file exists.

Notes

  • The script's primary output is now an actionable implementation plan, not just a list of files.
  • The quality of the plan depends on the quality of the input (issue description, specs, retrospective).
  • The generated plan is a guide; use your own expertise to adapt and improve it as you work.
  • Branch naming follows the convention: feat/ISSUE_NUMBER-kebab-case-title.

PRD Authoring Skill

Purpose

To accelerate and enhance early-stage project planning by using a powerful generative AI to create high-quality first drafts of key strategic documents. This skill integrates the Gemini CLI into the PRD authoring workflow, transforming it from a manual template-filling exercise into a dynamic, AI-assisted process.

The skill guides users from a vague project idea to a well-defined Product Requirements Document (PRD) by:

  • Generating a Product Brief: Creates a comprehensive brief from a simple project name.
  • Generating a Research Plan: Uses the product brief to generate a targeted research document.
  • Generating a full PRD: Synthesizes the brief and research into a detailed PRD with objectives, requirements, and success criteria.

This approach bridges the gap between "we have an idea" and "we're ready to write specs" with unprecedented speed and quality.

When to Use

Use this skill in the following situations:

  • Starting a new project from an initial concept.
  • Generating a first draft of a product brief, research plan, or PRD.
  • Validating an existing PRD against quality standards.
  • Breaking down a PRD into epics for sprint planning.

Do NOT use this skill for:

  • Implementation-level specifications (use spec-authoring instead).
  • Sprint planning from approved specs (use sprint-planner instead).

Prerequisites

  • Project initialized with AgenticDev structure (docs/ directory exists).
  • gemini CLI tool installed and authenticated.

PRD Philosophy

Strategy Before Tactics: PRDs define WHAT we're building and WHY before specs define HOW we'll build it. This skill uses AI to rapidly generate the "WHAT" and "WHY" so that teams can focus on review, refinement, and strategic alignment.


Workflow Commands

The status Command

Purpose

Assess project readiness and provide guidance on next workflow steps. This is the recommended starting point.

Workflow

Run the status check to understand the current state of your PRD documents.

bash scripts/prd-authoring.sh status [project-name]

The script will report which documents exist (product-brief.md, research.md, prd.md, etc.) and recommend the next logical command to run.


The brief Command

Purpose

Generate a comprehensive, high-quality first draft of a Product Brief from a simple project name.

Workflow
Step 1: Run Brief Generation Script

Execute the script with your project name.

bash scripts/prd-authoring.sh brief "Your Awesome Project Name"
Step 2: Understand What the Script Does

Instead of creating an empty template, the script calls the Gemini CLI with a detailed prompt, asking it to generate a full product brief. This includes plausible, well-structured content for:

  • Problem Statement
  • Target Users
  • Proposed Solution
  • Value Proposition
  • Success Metrics

The output from Gemini is saved as the first draft in docs/prds/your-awesome-project-name/product-brief.md.

Step 3: Review and Refine

Open the generated file. Review the AI-generated content with your team and stakeholders, refining the details to match your specific vision. The draft provides a strong foundation, saving hours of initial writing.


The research Command

Purpose

Generate a targeted, context-aware market research plan based on the contents of your product brief.

Workflow
Step 1: Run Research Generation Script

Once your product brief is reviewed and saved, run the research command:

bash scripts/prd-authoring.sh research your-awesome-project-name
Step 2: Understand What the Script Does

The script sends the entire content of your product-brief.md to the Gemini CLI. It prompts the AI to act as a business analyst and generate a research plan that logically follows from the brief. The generated draft will include sections for:

  • Competitive Analysis
  • Market Insights
  • User Feedback Analysis
  • Technical Considerations
  • Actionable Recommendations

This draft is saved to docs/prds/your-awesome-project-name/research.md.

Step 3: Execute Research and Refine Document

Use the AI-generated document as a guide for your research activities. Fill in the details and refine the analysis based on your actual findings.


The create-prd Command

Purpose

Generate a comprehensive, detailed first draft of a Product Requirements Document (PRD) by synthesizing the product brief and the research document.

Workflow
Step 1: Run PRD Creation Script

After completing your brief and research documents, run the create-prd command:

bash scripts/prd-authoring.sh create-prd your-awesome-project-name
Step 2: Understand What the Script Does

This is the most powerful feature. The script sends the full content of both your product brief and your research document to the Gemini CLI. It prompts the AI to generate a detailed PRD that includes:

  • SMART Objectives
  • Measurable Success Criteria
  • Specific Functional and Non-Functional Requirements
  • Constraints, Assumptions, and Out-of-Scope items

The resulting draft, saved in docs/prds/your-awesome-project-name/prd.md, is a deeply contextualized document that connects business goals from the brief with insights from the research.

Step 3: Review, Validate, and Refine

The generated PRD provides an excellent starting point. Review it with your team to ensure all requirements are accurate, testable, and aligned with project goals. Use the validate-prd command to check for quality.


The validate-prd Command

Purpose

Validate an existing PRD against quality standards, checking for missing sections, vague requirements, and unmeasurable success criteria. This command does not use the Gemini CLI; it uses pattern matching to enforce quality.

Workflow

Run the validation check on your PRD:

bash scripts/prd-authoring.sh validate-prd your-awesome-project-name

Review the report and address any issues found.


The decompose Command

Purpose

Break down a validated PRD into epics for sprint planning. This helps transition from strategic planning to tactical execution.

Workflow

Once your PRD is validated, run the decompose command:

bash scripts/prd-authoring.sh decompose your-awesome-project-name

This creates an epics.md file with a template structure for you to define your epics.


Error Handling and Troubleshooting

Gemini CLI Issues

Symptom: The script fails during the brief, research, or create-prd commands with an error related to the gemini command.

Solution:

  • Ensure the gemini CLI is installed and in your system's PATH.
  • Verify you are authenticated. Run gemini auth if needed.
  • Check for any Gemini API-related issues or outages.
  • Examine the prompt being constructed in the prd-authoring.sh script for any potential issues.

Other Issues

For issues related to file existence, permissions, or validation errors, the script provides detailed error messages and recommendations. Always check the script's output for guidance.


Best Practices

  • Review and Refine: The AI-generated drafts are a starting point, not a final product. Always review and tailor the content to your specific project needs.
  • Garbage In, Garbage Out: The quality of the generated research and prd documents depends on the quality of the product-brief you provide. Take time to refine the initial brief.
  • Iterate: Use the status command to guide you through the workflow. Don't be afraid to go back and refine a previous document if new insights emerge.

Project Init Skill

Purpose

Initialize a new project with the AgenticDev directory structure and configuration files. This skill sets up the foundational folders needed for the spec-driven development workflow, creating a standard structure for specifications, change proposals, and documentation.

When to Use

Use this skill in the following situations:

  • Starting a completely new project that will use AgenticDev
  • Adding AgenticDev methodology to an existing project with no existing documentation
  • Setting up a consistent structure for spec-driven development
  • Ensuring project follows AgenticDev conventions from the beginning

Important: If the project already has documentation in a docs/ directory, use the project-migrate skill instead. It will properly catalog, categorize, and migrate existing documentation into the AgenticDev structure while preserving git history and updating links.

Prerequisites

  • Write permissions to the target directory
  • Git repository already initialized (recommended but not required)

Workflow

Step 1: Assess the Current Project State

Before initializing, determine:

  • Is this a brand new project or an existing codebase?
  • Does a docs/ directory already exist?
  • If docs/ exists, does it contain markdown files?
  • Where should the AgenticDev structure be created?

Decision Tree:

  • No docs/ directory: Proceed with project-init (this skill)
  • Empty docs/ directory: Proceed with project-init (this skill)
  • docs/ with existing markdown files: Use project-migrate skill instead

The init-project.sh script will automatically detect existing documentation and suggest using project-migrate if appropriate.

Step 2: Run the Initialization Script

Execute the helper script to create the directory structure:

For current directory:

bash scripts/init-project.sh

For a specific directory:

bash scripts/init-project.sh -d /path/to/project

The script will create:

  • docs/specs/ - Source-of-truth for approved specifications
  • docs/changes/ - Staging area for proposed changes (Spec PRs)

Step 3: Verify Structure Creation

Check that the directories were created successfully:

ls -la docs/

Expected output:

docs/
├── specs/
└── changes/

Step 4: Initialize Supporting Files (Manual)

After the directory structure is created, consider adding these files:

Create RETROSPECTIVE.md (in project root):

cat > RETROSPECTIVE.md << 'EOF'
# Development Retrospective

This file captures learnings from completed tasks to inform and improve future development work.

## Active Improvements
EOF

Create AGENTS.md (using agent-integrator skill):

# Use the agent-integrator skill to create AGENTS.md
bash skills/agent-integrator/scripts/update-agents-file.sh

Step 5: Next Steps

After initialization, guide the user on getting started:

  1. Create first specification: Use the spec-authoring skill to propose the first feature
  2. Set up GitHub integration: Create GitHub repository if not exists, set up project board
  3. Document the system: Add initial specs to docs/specs/ directory
  4. Initialize git tracking: Ensure new directories are committed to version control

Error Handling

Directory Already Exists

Symptom: Script reports that directories already exist or initialization appears to do nothing

Solution:

  • Check if docs/specs/ and docs/changes/ already exist
  • If they exist, the project is already initialized
  • No action needed - the script is idempotent

Permission Denied

Symptom: "Permission denied" when creating directories

Solution:

  • Verify write permissions to the target directory
  • Check if parent directory exists
  • Try with appropriate permissions: sudo if necessary (rare)

Wrong Directory Initialized

Symptom: Directories created in unexpected location

Solution:

  • Remove incorrect directories: rm -rf docs/
  • Re-run with explicit path: bash scripts/init-project.sh -d /correct/path
  • Always verify current working directory before running

Directory Structure Explained

docs/specs/

Purpose: Source-of-truth for all approved specifications

Contents:

  • Approved specification files
  • Design documents
  • Architecture decisions
  • System requirements

Example structure:

docs/specs/
├── 001-initial-system.md
├── 002-authentication.md
└── feature-name/
    ├── spec.md
    └── design.md

docs/changes/

Purpose: Staging area for proposed changes before approval

Contents:

  • Change proposals in review
  • Spec deltas for new features
  • Task breakdowns
  • Planning documents

Example structure:

docs/changes/
├── my-feature/
│   ├── proposal.md
│   ├── spec-delta.md
│   └── tasks.md
└── another-feature/
    └── proposal.md

Workflow: Changes start in docs/changes/, get approved via Spec PR, then move to docs/specs/

project-init vs project-migrate

Understanding when to use each skill:

Use project-init when:

  • Starting a brand new project from scratch
  • Project has no existing documentation
  • docs/ directory is empty or doesn't exist
  • You just need the basic AgenticDev directory structure

Use project-migrate when:

  • Project has existing documentation in docs/ or other locations
  • You want to migrate legacy docs into AgenticDev structure
  • You need to preserve git history during migration
  • Documentation has relative links that need updating
  • You want doc-indexer compliant frontmatter added automatically

Smooth Handoff

The init-project.sh script automatically detects existing documentation and will:

  1. Count markdown files in docs/ (excluding docs/specs/ and docs/changes/)
  2. If found, display a recommendation to use project-migrate
  3. Show the benefits of using project-migrate over basic initialization
  4. Give you the option to continue with project-init or cancel

This ensures you always use the right skill for your situation.

Notes

  • The script is idempotent - safe to run multiple times
  • Existing directories won't be overwritten or deleted
  • The script only creates directories, no files are created automatically
  • Consider adding .gitkeep files to track empty directories in git
  • This is just the directory scaffold - content comes from using other skills
  • The structure is intentionally minimal - projects add what they need
  • Detection logic: The script checks for markdown files in docs/, excluding those already in specs/ or changes/ subdirectories

Project Migrate Skill

Purpose

To intelligently migrate existing projects (brownfield) to the AgenticDev directory structure using a powerful, AI-assisted workflow. This skill goes beyond simple file moving by leveraging the Gemini CLI to analyze document content, ensuring accurate categorization and the generation of rich, meaningful metadata. It provides a safe, guided migration with discovery, analysis, backup, and validation phases to ensure zero data loss and high-quality results.

When to Use

Use this skill in the following situations:

  • Adding AgenticDev to an existing project with established documentation.
  • Migrating docs from an ad-hoc structure to AgenticDev conventions.
  • When you want to automatically and intelligently categorize and add metadata to existing documents.
  • To ensure a safe migration with backups and rollback capabilities.

Prerequisites

  • Project with existing documentation (docs/, documentation/, wiki/, or markdown files).
  • Git repository initialized.
  • Write permissions to the project directory.
  • gemini CLI tool installed and authenticated.
  • doc-indexer skill available for final compliance checking.

Workflow

The skill guides you through a series of phases with interactive approval.

Step 1: Run the Migration Script

Execute with one of three modes:

Interactive (default) - Review and approve each phase:

bash scripts/project-migrate.sh

Dry-run - Preview the plan without making any changes:

bash scripts/project-migrate.sh --dry-run

Auto-approve - Skip prompts for automation (useful for CI/CD):

bash scripts/project-migrate.sh --auto-approve

Step 2: Review Each Phase

Phase 1 & 2 - AI-Powered Discovery and Analysis: The script scans for all markdown files. For each file, it calls the Gemini CLI to analyze the document's content, not just its filename. This results in a much more accurate categorization of files into types like spec, proposal, adr, etc. The output is a detailed plan mapping each file to its new, correct location in the AgenticDev structure.

Phase 3 - Planning: Shows you the complete, AI-driven migration plan for your approval. You can review source and target mappings before any files are moved.

Phase 4 - Backup: Creates a timestamped backup directory of your entire docs/ folder and includes a rollback.sh script before any changes are made.

Phase 5 - Migration: Executes the plan, moving files using git mv to preserve history and creating the necessary directory structure.

Phase 6 - LLM-Based Link Updates: Uses the Gemini CLI to intelligently identify and correct broken or outdated relative links within migrated files. This LLM-based approach is more robust than simple path recalculation, as it understands document context and can handle edge cases that pattern matching might miss.

Phase 7 - Validation: Verifies that all files were migrated correctly, checks link integrity, and validates the new directory structure.

Phase 8 - AI-Powered Frontmatter Generation (Optional): For files that lack YAML frontmatter, the script uses the Gemini CLI to read the file content and generate rich, doc-indexer compliant frontmatter. This includes a suggested title, the type determined during the analysis phase, and a concise description summarizing the document's purpose.

Step 3: Post-Migration

After successful completion:

  • Review the validation report for any warnings.
  • Run the doc-indexer skill to verify full documentation compliance.
  • Commit the migration changes to git.

Error Handling

Gemini CLI Issues

Symptom: The script fails during the "Analysis" or "Frontmatter Generation" phase with an error related to the gemini command.

Solution:

  • Ensure the gemini CLI is installed and in your system's PATH.
  • Verify you are authenticated by running gemini auth.
  • Check for Gemini API outages or network connectivity issues.
  • The script has basic fallbacks, but for best results, ensure the Gemini CLI is functional.

Other Issues

For issues related to permissions, conflicts, or broken links, the script provides detailed error messages and resolution suggestions during its interactive execution. The backup and rollback script is always available for a safe exit.

Notes

  • AI-Enhanced: Uses Gemini for intelligent content analysis, not just simple pattern matching.
  • Safe by default: Creates a full backup with a rollback script before making any changes.
  • Git-aware: Preserves file history using git mv.
  • Interactive: You review and approve the AI-generated plan before execution.
  • Rich Metadata: Generates high-quality frontmatter, including titles and descriptions.
  • LLM-Powered Link Correction: Uses Gemini to intelligently update relative links with context awareness.

Skill Lister

Purpose

Provide a comprehensive overview of all available AgenticDev skills in the project. The skill-lister scans the .claude/skills/ directory, extracts skill metadata from SKILL.md files, and returns a formatted list of all discovered skills with their descriptions and script paths. This enables AI agents to quickly understand what capabilities are available without manually exploring the directory structure.

When to Use

Use this skill in the following situations:

  • At the beginning of any work session to understand available AgenticDev capabilities
  • When onboarding to a new project using AgenticDev
  • Before deciding which skill to use for a particular task
  • When documenting or auditing the project's AgenticDev setup
  • To verify that all expected skills are installed and accessible

Prerequisites

  • The project must have a .claude/skills/ directory
  • Skills should follow the convention of including SKILL.md files with YAML frontmatter
  • No additional tools required (pure bash implementation)

Workflow

Step 1: Run the Skill Lister

Execute the helper script to scan all skills in the .claude/skills/ directory:

bash .claude/skills/skill-lister/scripts/list-skills.sh

This will output a human-readable summary showing each skill's metadata including:

  • Skill name
  • Description
  • Available scripts

For machine-readable JSON output (useful for programmatic processing):

bash .claude/skills/skill-lister/scripts/list-skills.sh -j

Step 2: Review the Skills List

The scanner returns information about all skills found in .claude/skills/, including:

  • Skill name: The identifier for the skill (from YAML frontmatter)
  • Description: What the skill does and when to use it
  • Script paths: All executable scripts available for the skill
  • Directory: Location of the skill in the filesystem

Step 3: Choose the Appropriate Skill

Based on the output, select the skill that best matches your current task:

  • Need to understand documentation? → Use doc-indexer
  • Starting work on an issue? → Use issue-executor
  • Proposing a change? → Use spec-authoring
  • Planning a sprint? → Use sprint-planner
  • Setting up a new project? → Use project-init

Error Handling

No Skills Directory Found

Symptom: Script reports that .claude/skills/ directory doesn't exist

Solution:

  • Verify you're in the project root directory
  • Run project-init skill to set up AgenticDev
  • Check if skills are installed in a different location

Missing SKILL.md Files

Symptom: Script lists skills but shows no metadata

Solution:

  • Verify that each skill directory contains a SKILL.md file
  • Check that SKILL.md files have proper YAML frontmatter with name and description fields
  • Run validation script if available: bash scripts/validate-skills.sh

No Scripts Found

Symptom: Skill is listed but shows no scripts

Solution:

  • Verify that the skill's scripts/ directory exists and contains executable files
  • Check file permissions: chmod +x .claude/skills/*/scripts/*
  • Some skills may not have scripts (documentation-only skills)

Permission Denied

Symptom: Cannot read skill directories or files

Solution:

  • Check directory permissions: ls -la .claude/skills/
  • Ensure you have read access to the skills directory
  • Verify the script itself is executable: chmod +x .claude/skills/skill-lister/scripts/list-skills.sh

Notes

  • Bootstrap context: Designed to be run by agent-integrator to provide AI agents with skill discovery capability
  • Lightweight: Minimal dependencies, works with standard bash tools
  • Extensible: Automatically discovers new skills as they're added
  • JSON support: Can output structured data for integration with other tools
  • Convention-based: Relies on standard AgenticDev skill structure (SKILL.md + scripts/)
  • Safe to run: Read-only operation with no side effects
  • Discovery pattern: Similar to doc-indexer but for skills instead of documentation

Spec Authoring Skill

Purpose

To manage the creation and refinement of feature specifications using a powerful, AI-assisted workflow. This skill leverages the Gemini CLI to accelerate the spec-driven development process by:

  1. Generating Drafts: Automatically creates high-quality, multi-file draft proposals for new features.
  2. Analyzing Feedback: Synthesizes review comments from Pull Requests into an actionable summary of recommended changes.

This approach allows developers and product managers to move from idea to an approved, implementation-ready specification with greater speed and clarity.

When to Use

Use this skill in the following situations:

  • Proposing a new feature or significant change.
  • Generating a first draft of a specification for review.
  • Processing and incorporating feedback from a Spec PR.

Prerequisites

  • Project initialized with AgenticDev structure (docs/specs/ and docs/changes/ directories exist).
  • GitHub repository set up.
  • gh CLI tool installed and authenticated.
  • gemini CLI tool installed and authenticated.

Spec PR Philosophy

Specs as Code: All specification changes follow the same rigor as code changes—proposed via branches, reviewed via PRs, and merged upon approval. This skill supercharges that philosophy with AI.


The propose Command

Purpose

Generate a comprehensive, multi-file draft proposal for a new feature from a single command.

Workflow

Step 1: Define the Proposal Name

Choose a clear, descriptive name for your feature, such as "User Authentication System" or "Real-time Notifications".

Step 2: Run the Helper Script

Execute the script to generate the draft proposal:

bash scripts/spec-authoring.sh propose "Feature Name"

The script will:

  1. Create a new directory in docs/changes/feature-name/.
  2. Make three parallel calls to the Gemini CLI to generate drafts for proposal.md, spec-delta.md, and tasks.md.
    • proposal.md: A high-level overview with problem statement, proposed solution, and success criteria.
    • spec-delta.md: A detailed technical specification with requirements and design decisions.
    • tasks.md: A preliminary breakdown of implementation tasks.
  3. Save the AI-generated content into these files.
Step 3: Review and Refine the Drafts

The script provides you with a complete, context-aware first draft of your entire proposal. Your next step is to review and refine these documents to ensure they align with your vision before opening a Spec PR.


The update Command

Purpose

Intelligently process feedback from a Spec PR by using AI to analyze review comments and generate a summarized action plan.

Workflow

Step 1: Identify the PR Number

Determine which Spec PR you need to update.

Step 2: Run the Feedback Analysis Script

Execute the script with the PR number:

bash scripts/spec-authoring.sh update PR_NUMBER

This command will:

  1. Find the local files associated with the PR's branch.
  2. Fetch all review comments from the PR.
  3. Send the full content of your spec files and all the comments to the Gemini CLI.
  4. Ask the AI to act as a reviewer and provide a summarized list of recommended changes for each file.
Step 3: Address the Synthesized Feedback

The script will output a clear, actionable plan that synthesizes all the reviewer feedback. Use this analysis to efficiently update your proposal files, address the comments, and push your changes for re-review.


Error Handling

Gemini CLI Issues

Symptom: The script fails during the propose or update commands with an error related to the gemini command. Solution:

  • Ensure the gemini CLI is installed and in your system's PATH.
  • Verify you are authenticated (gemini auth).
  • Check for Gemini API outages or network issues.

Proposal Directory Already Exists

Symptom: The propose command reports that the directory already exists. Solution: Choose a different name for your proposal or work with the existing one.

Could Not Find Proposal Directory

Symptom: The update command cannot find the local files for the PR. Solution: Ensure you have the correct PR branch checked out and that the local directory in docs/changes/ matches the branch name.

Notes

  • AI-Assisted Workflow: This skill is designed to be a powerful assistant. It generates high-quality drafts and analyzes feedback, but the final strategic decisions and refinements are yours to make.
  • Speed and Quality: By automating the initial drafting and feedback synthesis, this skill allows you to focus on the high-value work of design, review, and alignment.
  • Iterative Process: Use the propose command to start, and the update command to iterate based on team feedback, creating a rapid and efficient spec development cycle.

Sprint Manager

Purpose

To autonomously execute a sprint by coordinating the implementation of GitHub issues through a structured workflow that leverages subagents for isolated work and maintains a clean context window for sprint-level coordination.

When to Use

Use this skill in the following situations:

  • Starting work on a set of sprint issues from a GitHub milestone
  • Implementing multiple issues autonomously with minimal user intervention
  • Coordinating a development workflow that requires code review and integration
  • Managing serial execution of dependent or independent issues

Prerequisites

  • GitHub repository with issues assigned to a milestone
  • Git working directory is clean (no uncommitted changes)
  • gh CLI tool installed and authenticated
  • gemini CLI tool installed and authenticated (optional, for plan generation)
  • Codex MCP available for PR review
  • Project has issue-executor and change-integrator skills (or equivalent workflow)

Architecture

The sprint manager operates as a coordinator that delegates work to subagents:

Sprint Manager (main context)
│
├── For each issue:
│   ├── 1. Generate implementation plan (Gemini CLI or manual)
│   ├── 2. Create feature branch
│   ├── 3. Launch implementer subagent → creates PR
│   ├── 4. Review PR (Codex MCP)
│   ├── 5. Fix issues if needed (another subagent)
│   ├── 6. Merge on approval
│   └── 7. Launch integrator subagent → cleanup & retrospective
│
└── Report sprint summary

Core Workflow

Phase 1: Sprint Setup

  1. Identify sprint issues by querying the GitHub milestone:

    gh issue list --milestone "Sprint X" --state open --json number,title,labels
    
  2. Prioritize issues based on labels (P0 > P1 > P2) and dependencies

  3. Track progress using the TodoWrite tool with all sprint issues

Phase 2: Issue Execution Loop

For each issue in priority order:

Step 1: Generate Implementation Plan

Option A - Use issue-executor skill (if Gemini available):

bash scripts/work-on-issue.sh <issue-number>

Option B - Manual plan generation:

  1. Fetch issue details: gh issue view <number> --json title,body
  2. Read relevant specs from docs/specs/ or docs/changes/
  3. Call Gemini CLI with context to generate a step-by-step plan
  4. Create feature branch following convention: feat/<number>-<kebab-title>
Step 2: Delegate Implementation to Subagent

Launch a Task subagent with a comprehensive prompt including:

  • Issue number and acceptance criteria
  • Implementation plan from Step 1
  • Project conventions (from CLAUDE.md)
  • File paths and schema context
  • Expected deliverables (PR URL, test results, files created)
  • Fallback instructions if tools fail

Select appropriate subagent type based on the issue:

  • backend-architect - API routes, database schemas, backend logic
  • frontend-developer - React components, UI, client-side code
  • general-purpose - Mixed or unclear scope

Example prompt structure (see references/implementer-prompt-template.md):

## Task: Implement GitHub Issue #<number> - <title>

You are working on branch `<branch-name>` in `<working-directory>`.

### Issue Summary
<brief description>

### Implementation Plan
<step-by-step plan from Gemini or manual>

### Project Conventions
<key conventions from CLAUDE.md>

### Your Deliverables
1. Implement the code
2. Run lint and tests
3. Commit with conventional commit message
4. Push and create PR

### Report Back
<what to return: PR URL, test results, issues encountered>
Step 3: Review PR with Codex MCP

After subagent returns with PR URL:

mcp__codex__codex with prompt:
"Review PR #<number>: <title>
URL: <pr-url>

The PR implements: <summary>

Focus your review on: <relevant concerns>

Say APPROVED if ready to merge, or list issues with severity."
Step 4: Handle Review Feedback

If Codex finds issues:

  1. Launch another subagent to fix the issues
  2. Provide specific fix instructions from Codex feedback
  3. Re-review after fixes are pushed

If Codex approves:

  • Proceed to merge
Step 5: Merge PR
gh pr merge <number> --squash --auto

Wait for CI to pass, then verify merge:

gh pr view <number> --json state
Step 6: Post-Merge Integration

Launch integrator subagent (see references/integrator-prompt-template.md):

  1. Switch to main and pull latest
  2. Delete feature branch (local and remote)
  3. Update retrospective with learnings
  4. Close issue if not auto-closed
  5. Report completion status

Phase 3: Sprint Completion

After all issues are processed:

  1. Update TodoWrite to mark all issues complete
  2. Summarize sprint results:
    • Issues completed
    • PRs merged
    • Key learnings
    • Any blockers encountered
  3. Report to user

Error Handling

Gemini CLI Fails

If the Gemini CLI fails during plan generation:

  • Fall back to manual plan creation
  • Read issue details directly via gh issue view
  • Check relevant specs in docs/specs/ or docs/changes/
  • Construct implementation plan based on acceptance criteria

Subagent Fails

If an implementer subagent fails:

  • Review the error reported
  • Launch a new subagent with adjusted instructions
  • Consider breaking the task into smaller pieces
  • Flag for user intervention if repeated failures

Codex Review Times Out

If Codex MCP doesn't respond:

  • Retry the review request
  • Fall back to basic automated checks (lint, tests)
  • Flag PR for user manual review

PR Merge Conflicts

If merge fails due to conflicts:

  • Rebase the branch on main
  • Launch subagent to resolve conflicts
  • Re-run tests and review

Prompt Templates

See the references/ directory for detailed prompt templates:

  • references/implementer-prompt-template.md - Template for implementation subagents
  • references/integrator-prompt-template.md - Template for post-merge integration subagents
  • references/review-prompt-template.md - Template for Codex PR reviews

Best Practices

Context Management

  • Keep sprint-level state in the main context (issue tracking, PR URLs, blockers)
  • Delegate all implementation details to subagents
  • Each subagent gets a fresh context - include all needed info in the prompt

Prompt Crafting

  • Be specific about file paths and existing code context
  • Include project conventions explicitly (subagents don't read CLAUDE.md)
  • Specify exact deliverables and report format
  • Provide fallback instructions for common failure modes

Serial vs Parallel

  • Default to serial execution for safety and easier debugging
  • Only parallelize truly independent issues with explicit user approval
  • Never parallelize issues with shared file dependencies

User Communication

  • Report progress after each issue completes
  • Flag blockers immediately rather than retrying indefinitely
  • Provide sprint summary at the end

Notes

  • This skill is designed for serial execution to maintain context clarity
  • Each issue gets its own subagent context, keeping the main context clean
  • The workflow integrates with existing issue-executor and change-integrator skills
  • Codex MCP provides automated code review without user intervention
  • Retrospective updates capture learnings for future sprints

Sprint Planner Skill

Purpose

To plan and initialize a new sprint by intelligently decomposing approved specifications into a comprehensive set of atomic GitHub issues. This skill bridges the gap between high-level specs and executable work items by using the Gemini CLI to analyze the spec's content and generate a thoughtful task breakdown. It then automates the creation of these tasks as GitHub issues within a new sprint milestone.

When to Use

Use this skill in the following situations:

  • Starting a new sprint or development cycle.
  • Converting an approved spec into actionable GitHub issues.
  • When you want an AI-assisted breakdown of an epic into atomic implementation tasks.

Prerequisites

  • Project board configured with an "Approved Backlog" status column.
  • Approved spec files exist in the docs/specs/ directory.
  • An Epic issue exists on GitHub that links to the spec file in its body.
  • gh CLI tool installed and authenticated.
  • jq tool installed for JSON parsing.
  • gemini CLI tool installed and authenticated.

Workflow

Step 1: Review Project Board

Check the project board for approved specs (represented as Epics) ready to be planned.

Step 2: Discuss Sprint Scope with User

Engage the user to determine which epic(s) from the "Approved Backlog" to include in the sprint.

Step 3: Define Sprint Metadata

Work with the user to establish the sprint name (e.g., "Sprint 4").

Step 4: Run the Helper Script

Execute the sprint planning script to automate GitHub issue creation:

bash scripts/create-sprint-issues.sh

Step 5: Understand What the Script Does

The helper script automates these steps:

  1. Queries Project Board: Fetches all items from the "Approved Backlog" and prompts you to select an Epic to plan.
  2. Extracts Spec File: Parses the selected Epic's body to find the associated spec file path.
  3. Creates Milestone: Prompts you for a sprint name and creates the corresponding GitHub milestone.
  4. Decomposes Spec with AI: Instead of relying on a rigid format, the script sends the full content of the spec file and the parent Epic to the Gemini CLI. It asks the AI to generate a list of atomic, actionable tasks based on its understanding of the document.
  5. Creates GitHub Issues: The script parses the structured task list from Gemini's response and creates a GitHub issue for each task. Each issue is automatically titled, assigned to the new milestone, and includes a description and references to the parent Epic and spec file.

Step 6: Verify Issue Creation

After the script completes, review the newly created issues in your milestone.

gh issue list --milestone "Your Sprint Name"

Step 7: Review Created Issues with User

Walk through the AI-generated issues with your team. The generated tasks provide a strong baseline, but you should review them to confirm completeness, adjust priorities, and make any necessary refinements.

Error Handling

jq or Gemini Not Installed

Symptom: Script reports that jq or gemini command is not found. Solution: Install the required tool and ensure it's in your system's PATH.

No Approved Epics Found

Symptom: Script reports no epics in the approved backlog. Solution: Ensure your Epics are in the correct status column on your project board.

Epic Body Missing Spec Reference

Symptom: Script cannot find a spec file path in the Epic's body. Solution: Edit the Epic's issue body on GitHub to include a valid path to a spec file (e.g., docs/specs/my-feature.md).

Gemini CLI Issues

Symptom: The script fails during the task decomposition step with an error from the gemini command. Solution:

  • Ensure the gemini CLI is installed and authenticated (gemini auth).
  • Check for API outages or network issues.
  • The quality of the task breakdown depends on a functional Gemini CLI.

Notes

  • Intelligent Decomposition: The skill no longer relies on a rigid task format in spec files. Gemini reads and understands the document to create tasks.
  • LLM guides strategy, script executes: You decide which spec to plan; the script uses AI to handle the tedious decomposition and issue creation.
  • One epic per run: Run the script once for each Epic you want to plan for the sprint.
  • Traceability is built-in: Each created task issue automatically references the parent Epic and the source spec file.
  • Manual refinement is expected: The AI-generated task list is a starting point. Review and adjust it with your team.

Agents 11

Work on Issue Workflow

Select and start work on a specific issue from assigned GitHub issues.

Purpose

Load full context for an issue and create a feature branch to begin implementation. Ensures clean workflow start with all necessary context loaded before any code is written.

When to Use

Use this workflow when:

  • Starting work on a new issue
  • Switching between issues
  • After completing previous issue
  • Beginning work session

Workflow

1. Verify Clean Working State

# Check current branch is clean
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" != "main" ]; then
  echo "⚠ Currently on branch: $CURRENT_BRANCH"
  echo "Finish current work or switch to main first."
  exit 1
fi

# Check for uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
  echo "⚠ Uncommitted changes detected"
  git status
  echo "Commit or stash changes before starting new issue."
  exit 1
fi

2. Get Current User's Assigned Issues

# Get all open issues assigned to current user
gh issue list \
  --assignee @me \
  --state open \
  --json number,title,labels,milestone,createdAt \
  --limit 50 | jq '.'

3. Get Milestone Details for Context

# Get current sprint milestones
gh api repos/:owner/:repo/milestones \
  --jq '.[] | select(.state == "open") | {number, title, state, dueOn}' \
  | jq -s 'sort_by(.dueOn)'

4. Check for Spec Conflicts

For each candidate issue, verify no conflicting work in progress:

# Extract affected specs from issue body
ISSUE_NUM=123
AFFECTED_SPECS=$(gh issue view $ISSUE_NUM --json body --jq .body \
  | rg "Affected Specs.*" -A 5 \
  | rg "docs/specs/([^/]+)" -o -r '$1')

# Check if any other open issues affect same specs
for SPEC in $AFFECTED_SPECS; do
  CONFLICTS=$(gh issue list \
    --assignee @me \
    --state open \
    --search "docs/specs/$SPEC in:body" \
    --json number,title)

  if [ $(echo "$CONFLICTS" | jq 'length') -gt 1 ]; then
    echo "⚠ Conflict detected: Multiple issues affect $SPEC"
    echo "$CONFLICTS" | jq -r '.[] | "#\(.number) - \(.title)"'
  fi
done

5. Analyze and Recommend Issues

Sort and prioritize issues by:

  1. Priority: P0 > P1 > P2 > P3
  2. Sprint alignment: Current milestone first
  3. Spec readiness: Issues with existing specs
  4. Dependencies: Non-blocked issues first
# Parse priorities from labels
P0_ISSUES=$(gh issue list --assignee @me --state open --label "priority:P0" --json number,title,milestone)
P1_ISSUES=$(gh issue list --assignee @me --state open --label "priority:P1" --json number,title,milestone)
P2_ISSUES=$(gh issue list --assignee @me --state open --label "priority:P2" --json number,title,milestone)

# Show recommendations
echo "=== Recommended Issues ==="
echo ""
echo "Priority P0 (Critical):"
echo "$P0_ISSUES" | jq -r '.[] | "  #\(.number) - \(.title) [\(.milestone.title)]"'
echo ""
echo "Priority P1 (High):"
echo "$P1_ISSUES" | jq -r '.[] | "  #\(.number) - \(.title) [\(.milestone.title)]"'
echo ""
echo "Priority P2 (Medium):"
echo "$P2_ISSUES" | jq -r '.[] | "  #\(.number) - \(.title) [\(.milestone.title)]"'

Present top 3-5 recommendations:

Top recommendations:

1. #201 - Curriculum Framework (P1, S2) ✓ Specs ready
2. #202 - Lesson Player (P1, S2) ✓ Specs ready
3. #203 - Virtual Laboratory System (P2, S2) ⚠ Depends on #201

Which issue would you like to start? (Enter number)

6. Read Full Issue Details

After user selects issue:

ISSUE_NUMBER=201

# Read complete issue
gh issue view $ISSUE_NUMBER

# Read ALL comments (including review suggestions)
gh issue view $ISSUE_NUMBER --comments

IMPORTANT: Pay special attention to review comments posted by review-sprint. These may include:

  • Architecture compliance suggestions
  • Wording and clarity improvements
  • Planning enhancements
  • Spec change recommendations

Consider these suggestions during implementation but use your judgment on how to apply them.

7. Extract and Validate Spec References

# Get issue body
ISSUE_BODY=$(gh issue view $ISSUE_NUMBER --json body --jq .body)

# Extract affected specs
AFFECTED_SPECS=$(echo "$ISSUE_BODY" | rg "Affected Specs" -A 10 | rg "docs/specs/[^)]+")

# Verify each spec exists
echo "Validating spec references..."
for SPEC_PATH in $AFFECTED_SPECS; do
  if [ -f "$SPEC_PATH" ]; then
    echo "✓ Found: $SPEC_PATH"
  else
    echo "✗ Missing: $SPEC_PATH"
    echo ""
    echo "⚠ Spec not found. Run 'init-spec' to create it first."
    exit 1
  fi
done

8. Check Related Issues and Dependencies

# Look for "Related Issues" section in issue body
RELATED_ISSUES=$(echo "$ISSUE_BODY" | rg "Related Issues" -A 5 | rg "#[0-9]+" -o)

if [ -n "$RELATED_ISSUES" ]; then
  echo "=== Related Issues ==="
  for RELATED in $RELATED_ISSUES; do
    RELATED_NUM=$(echo "$RELATED" | tr -d '#')
    RELATED_STATE=$(gh issue view $RELATED_NUM --json state --jq .state)
    RELATED_TITLE=$(gh issue view $RELATED_NUM --json title --jq .title)

    if [ "$RELATED_STATE" = "OPEN" ]; then
      echo "⚠ $RELATED - $RELATED_TITLE (OPEN - may be dependency)"
    else
      echo "✓ $RELATED - $RELATED_TITLE (CLOSED)"
    fi
  done
fi

# Check for blocking issues
BLOCKING=$(echo "$ISSUE_BODY" | rg -i "blocked by|depends on" -A 2)
if [ -n "$BLOCKING" ]; then
  echo ""
  echo "⚠ Warning: This issue may have dependencies:"
  echo "$BLOCKING"
  echo ""
  read -p "Continue anyway? (y/n) " -n 1 -r
  echo
  if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    echo "Aborted. Select a different issue."
    exit 1
  fi
fi

9. Read Affected Specs

echo "=== Reading Affected Specs ==="
for SPEC_PATH in $AFFECTED_SPECS; do
  echo ""
  echo "--- $SPEC_PATH ---"
  cat "$SPEC_PATH"
  echo ""
done

# If spec has design.md, read it too
for SPEC_PATH in $AFFECTED_SPECS; do
  SPEC_DIR=$(dirname "$SPEC_PATH")
  DESIGN_PATH="$SPEC_DIR/design.md"

  if [ -f "$DESIGN_PATH" ]; then
    echo "--- $DESIGN_PATH ---"
    cat "$DESIGN_PATH"
    echo ""
  fi
done

10. Read Development Retrospective

Read accumulated learnings to inform implementation:

if [ -f "RETROSPECTIVE.md" ]; then
  echo ""
  echo "=== Development Retrospective ==="
  cat RETROSPECTIVE.md
  echo ""
  echo "Consider these learnings during implementation:"
  echo "  - Apply success patterns from recent issues"
  echo "  - Avoid known friction points"
  echo "  - Reference well-specified capabilities"
  echo "  - Follow active improvement initiatives"
  echo ""
elif [ -f "docs/RETROSPECTIVE.md" ]; then
  echo ""
  echo "=== Development Retrospective ==="
  cat docs/RETROSPECTIVE.md
  echo ""
  echo "Consider these learnings during implementation."
  echo ""
else
  echo ""
  echo "ℹ No RETROSPECTIVE.md found (this is normal for first few issues)"
  echo ""
fi

Purpose: The retrospective captures:

  • Recent patterns: What worked/didn't work in last 3-5 issues
  • Historical wisdom: Compressed learnings from earlier issues
  • Spec quality: Which specs are good references vs need improvement
  • Active improvements: Current process improvements being tracked

This context helps avoid repeating past mistakes and apply proven patterns.

11. Create Feature Branch

# Extract title and create kebab-case branch name
TITLE=$(gh issue view $ISSUE_NUMBER --json title --jq .title)
KEBAB_TITLE=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g;s/^-|-$//g' | cut -c1-40)

# Determine branch prefix from change type
CHANGE_TYPE=$(echo "$ISSUE_BODY" | rg "\[x\] (ADDED|MODIFIED|REMOVED)" -o -r '$1')

case "$CHANGE_TYPE" in
  "ADDED")
    PREFIX="feat"
    ;;
  "MODIFIED")
    PREFIX="feat"  # or "refactor" depending on scope
    ;;
  "REMOVED")
    PREFIX="refactor"
    ;;
  *)
    # Infer from labels
    if echo "$ISSUE_BODY" | rg -q "type:bug"; then
      PREFIX="fix"
    elif echo "$ISSUE_BODY" | rg -q "type:chore"; then
      PREFIX="chore"
    else
      PREFIX="feat"
    fi
    ;;
esac

BRANCH_NAME="${PREFIX}/${ISSUE_NUMBER}-${KEBAB_TITLE}"

# Create and switch to branch
git switch -c "$BRANCH_NAME"

echo "✓ Created and switched to: $BRANCH_NAME"

12. Initial Setup

Check if any setup is needed:

# Check if package.json changed recently (might need npm install)
MAIN_PACKAGE_DATE=$(git log -1 --format="%ai" main -- package.json 2>/dev/null)
if [ -n "$MAIN_PACKAGE_DATE" ]; then
  echo "Note: package.json was updated recently ($MAIN_PACKAGE_DATE)"
  echo "Running npm install..."
  npm install
fi

# Check if Prisma schema exists (might need generate)
if [ -f "prisma/schema.prisma" ]; then
  echo "Note: Prisma schema detected"
  echo "Running npx prisma generate..."
  npx prisma generate
fi

# Check for other setup scripts
if [ -f "scripts/setup.sh" ]; then
  echo "Note: Found setup script"
  echo "Running scripts/setup.sh..."
  bash scripts/setup.sh
fi

13. Update TODO.md

Add issue to "In Progress" section:

## In Progress

- [ ] #201 - Curriculum Framework (feat/201-curriculum-framework)
  - **Started**: 2025-10-21
  - **Branch**: feat/201-curriculum-framework
  - **Specs**: docs/specs/curriculum-management/spec.md
  - **Priority**: P1
  - **Milestone**: S2

If TODO.md doesn't have "In Progress" section, create it:

# Check if section exists
if ! grep -q "## In Progress" TODO.md; then
  # Add section after sprint section
  sed -i '/^## Phase/a \\n## In Progress\n' TODO.md
fi

# Add issue entry
cat >> TODO.md << EOF

- [ ] #${ISSUE_NUMBER} - ${TITLE} (${BRANCH_NAME})
  - **Started**: $(date +%Y-%m-%d)
  - **Branch**: ${BRANCH_NAME}
  - **Specs**: ${AFFECTED_SPECS}
  - **Priority**: ${PRIORITY}
  - **Milestone**: ${MILESTONE}
EOF

14. Update Sprint File

Find the relevant sprint file and update story status:

# Find sprint file (match milestone to sprint file)
MILESTONE=$(gh issue view $ISSUE_NUMBER --json milestone --jq .milestone.title)
SPRINT_NUM=$(echo "$MILESTONE" | rg "S([0-9]+)" -o -r '$1')
SPRINT_FILE="docs/sprint/S${SPRINT_NUM}.md"

if [ -f "$SPRINT_FILE" ]; then
  # Find the story section and update status
  # This is complex; in practice, manually update the file
  echo "Update $SPRINT_FILE:"
  echo "  - Find story section for: $TITLE"
  echo "  - Add: **Status**: In Progress"
  echo "  - Add: **Branch**: $BRANCH_NAME"
  echo "  - Add: **Started**: $(date +%Y-%m-%d)"
fi

Example sprint file update:

## Curriculum Framework

**User Story**: As an educator...

**Status**: In Progress
**Branch**: feat/201-curriculum-framework
**Started**: 2025-10-21
**Issue**: #201

15. Provide Summary

✓ Started work on issue #201

Issue: Curriculum Framework
Branch: feat/201-curriculum-framework
Priority: P1
Milestone: S2

Affected specs:
  - docs/specs/curriculum-management/spec.md

Review comments: 1 comment (review suggestions available)

Next steps:
  1. Review issue comments and review suggestions
  2. Review spec requirements and scenarios
  3. Implement according to acceptance criteria (considering review feedback)
  4. Write tests per test plan
  5. Run 'test-issue' before submitting
  6. Run 'submit-issue' when ready for PR

Dependencies to watch:
  - None identified

Happy coding! 🚀

Priority Order

Issues are recommended in this order:

  1. P0 - Critical: Blocking bugs, production issues
  2. P1 - High: Important features, high-value work
  3. P2 - Medium: Standard features, improvements
  4. P3 - Low: Nice-to-have, technical debt

Within same priority:

  • Current sprint milestone before future sprints
  • Issues with ready specs before those needing spec work
  • Non-blocked issues before those with dependencies

Dependency Checking

Types of Dependencies

  1. Hard dependencies: "Blocked by #123", "Depends on #123"

    • Must be completed first
    • Halt if not complete
  2. Soft dependencies: "Related to #123", "See also #123"

    • Provide context but not blocking
    • Read for additional information
  3. Spec dependencies: One spec depends on another

    • Check if dependency specs exist
    • Verify dependency requirements are clear

Handling Blocked Issues

If selected issue is blocked:

⚠ Issue #203 is blocked by #201 (Curriculum Framework)

#201 status: In Progress (50% complete)

Options:
1. Wait for #201 to complete
2. Select different issue
3. Proceed with risk (may need rework)

Recommendation: Select different issue and return to #203 later.

Spec Readiness Validation

Before starting work, ensure:

  • All referenced specs exist in docs/specs/
  • Specs have clear requirements
  • Each requirement has scenarios
  • Dependencies between specs are documented
  • Design docs exist for complex changes

If spec is incomplete:

  1. Consider running init-spec to complete it
  2. Or flag issue for spec refinement before starting

File Update Patterns

TODO.md Format

## In Progress

- [ ] #201 - Curriculum Framework (feat/201-curriculum-framework)
  - **Started**: 2025-10-21
  - **Branch**: feat/201-curriculum-framework
  - **Specs**: docs/specs/curriculum-management/spec.md
  - **Priority**: P1
  - **Milestone**: S2
  - **Dependencies**: None

Sprint File Format

## Curriculum Framework

**User Story**: As an educator, I want to define course structures...

**Acceptance Criteria**:
- Course hierarchy supported
- Learning objectives trackable

**Status**: In Progress
**Branch**: feat/201-curriculum-framework
**Started**: 2025-10-21
**Issue**: #201
**Assigned**: @username

Error Handling

Dirty Working Directory

⚠ Error: Uncommitted changes detected

Please commit or stash changes before starting new issue:
  git add .
  git commit -m "wip: save progress"
  # or
  git stash

Then run 'next-issue' again.

Not on Main Branch

⚠ Error: Currently on branch: feat/123-old-issue

Please finish current work first:
  1. Complete implementation
  2. Run 'submit-issue' to create PR
  3. Or: git switch main (to abandon work)

Then run 'next-issue' again.

Missing Specs

⚠ Error: Spec not found
  docs/specs/curriculum-management/spec.md

Issue #201 references specs that don't exist yet.

Action required:
  1. Run: init-spec curriculum-management
  2. Create spec.md with requirements
  3. Run 'next-issue' again

No Available Issues

ℹ No issues assigned to you.

Possible actions:
  1. Check sprint backlog in GitHub
  2. Assign yourself an issue from current sprint
  3. Run 'seed-sprint' to create new issues
  4. Contact Scrum Master for assignment

Advanced: Context Caching

To optimize repeated API calls, consider caching:

# Cache issue list for 5 minutes
CACHE_FILE="/tmp/gh-issues-cache-$(date +%Y%m%d-%H%M).json"
if [ ! -f "$CACHE_FILE" ]; then
  gh issue list --assignee @me --state open --json number,title,labels,milestone > "$CACHE_FILE"
fi

# Use cached data
ISSUES=$(cat "$CACHE_FILE")

Notes

  • Always verify clean state before starting new work
  • Read all related issues for full context
  • Check spec completeness before implementation
  • Update tracking files immediately after branch creation
  • Consider dependencies when selecting issues
  • Prefer current sprint issues over future work
  • Validate specs exist and are complete
  • Note any setup requirements (npm install, prisma generate, etc.)

Product Brief: Payment Gateway Integration

Problem Statement

What problem exists? Our e-commerce platform currently lacks integrated payment processing capabilities, forcing customers to complete purchases through manual invoice processing. This creates significant friction in the buying process, with 45% of customers abandoning their carts during checkout when they discover they cannot pay immediately online.

Who experiences this problem?

  • E-commerce customers attempting to purchase products online (15,000 unique monthly visitors)
  • Sales team manually processing invoices and payment confirmations (handling 800-1,000 transactions/month)
  • Finance team reconciling payments and updating accounting systems (20 hours/week manual work)
  • Customer support handling payment-related inquiries (30% of all support tickets)

How often does it occur?

  • Affects 100% of purchase transactions (approximately 1,000 transactions per month)
  • Daily manual payment processing required for 30-40 orders
  • Weekly reconciliation bottlenecks cause 2-3 day delays in order fulfillment

What's the business impact?

  • Lost revenue: $2.4M annually from cart abandonment (45% abandonment rate on $5.3M annual pipeline)
  • Operational costs: $120K/year in manual payment processing labor (sales + finance teams)
  • Customer satisfaction: NPS score of 35 (below industry average of 50) with payment process cited as top complaint
  • Competitive disadvantage: Losing deals to competitors with seamless online checkout

Target Users

Primary Users

Persona 1: Online Shopper (Sarah)

  • Who they are: Tech-savvy consumers aged 25-45, making purchases $50-$500, expect modern e-commerce experience
  • Key goals: Complete purchases quickly and securely, receive instant confirmation, avoid payment delays
  • Pain points: Cannot pay online, must wait for invoice email, manual payment is time-consuming and feels outdated
  • Frequency of use: 1-3 purchases per month, expect to checkout in under 2 minutes

Persona 2: Sales Representative (Mike)

  • Who they are: Inside sales team member, processes 25-30 orders daily, manages customer relationships
  • Key goals: Close deals faster, reduce administrative work, focus on selling not payment processing
  • Pain points: Spends 2 hours daily creating invoices and following up on payments, manual errors cause delays
  • Frequency of use: Multiple times daily, processes every transaction

Secondary Users

  • Finance Team: Needs automated reconciliation and accurate transaction records, currently spends 20 hours/week on manual entry
  • Customer Support: Handles payment status inquiries and issues, needs visibility into transaction status
  • Business Leadership: Requires revenue reporting, conversion metrics, and fraud prevention

Proposed Solution

Solution Overview Integrate a best-in-class payment gateway (Stripe) to enable secure, real-time online payment processing with support for credit/debit cards, digital wallets (Apple Pay, Google Pay), and one-click checkout for returning customers. The solution will automate payment processing, provide instant confirmation, and integrate with our existing CRM and accounting systems.

How it addresses the problem By enabling online payment processing, customers can complete purchases immediately without friction, eliminating the manual invoice workflow. Sales team can focus on selling instead of payment administration, finance team benefits from automated reconciliation, and the business captures revenue that was previously lost to abandonment.

Key capabilities

  • Secure payment processing for credit/debit cards and digital wallets with PCI DSS compliance
  • One-click checkout for returning customers with saved payment methods
  • Real-time payment confirmation and automated receipt generation
  • Integration with Salesforce CRM for order management and customer records
  • Automated reconciliation with QuickBooks accounting system
  • Fraud detection and prevention with 3D Secure 2.0

What makes this solution different? Unlike our current manual process, this provides instant payment processing (under 3 seconds) with zero manual intervention. Compared to basic payment gateways, we're choosing Stripe for its superior developer experience, comprehensive documentation, and proven reliability at scale.

Value Proposition

User Benefits

  • Speed: Reduce checkout time from 24-48 hours (manual invoice) to under 60 seconds (online payment)
  • Convenience: Pay with preferred method (card, Apple Pay, Google Pay) without leaving the site
  • Security: PCI-compliant payment processing eliminates concerns about sharing card details
  • Trust: Instant confirmation email and receipt provides peace of mind
  • Returning customers: Save payment method for one-click future purchases

Business Benefits

  • Revenue: Reduce cart abandonment from 45% to 15%, recovering $1.8M in annual revenue
  • Operational efficiency: Eliminate 20 hours/week of manual payment processing, saving $100K annually
  • Cash flow: Accelerate payment collection from 3-5 days to instant, improving cash flow by $200K
  • Scalability: Support 10x growth without adding payment processing headcount
  • Data insights: Real-time transaction analytics and conversion funnel visibility
  • Customer satisfaction: Improve NPS score from 35 to 55+ with modern checkout experience

Competitive Advantages

  • Achieve parity with competitors on basic online payment capability (table stakes)
  • Differentiate with faster checkout experience (target: under 60 seconds vs industry average 2-3 minutes)
  • Build foundation for future innovations: subscription billing, international expansion, marketplace features
  • Create switching cost through saved payment methods and purchase history

Success Metrics

Launch Success Criteria

  • Checkout conversion rate: 55% → 75% (reduce abandonment from 45% to 25%)
  • Average checkout time: N/A (manual) → 45 seconds (90th percentile)
  • Payment success rate: N/A → 98% (transactions completed successfully)
  • Customer satisfaction: 35 NPS → 50+ NPS for checkout experience
  • Payment processing uptime: Target 99.9% (maximum 45 minutes downtime per month)

Long-term Success Metrics

  • Monthly transaction volume: 1,000 → 5,000 transactions per month within 6 months
  • Revenue recovery: Recover $1.5M+ in previously abandoned cart revenue within 12 months
  • Saved payment method adoption: 60% of customers save payment method for future use
  • Operational cost reduction: Reduce manual payment processing costs by 80% ($100K annual savings)
  • Average order value: Increase from $275 to $325 due to reduced friction

Leading Indicators

  • First-week transaction volume exceeds 100 successful payments
  • 70%+ of users complete checkout without contacting support
  • Less than 5% of transactions require sales team intervention
  • Payment-related support tickets decrease by 50% in first month
  • 80%+ customer satisfaction rating on post-purchase survey

Research: Payment Gateway Integration

Competitive Analysis

Competitor 1: Stripe

Overview Market leader in developer-focused payment processing with 40%+ market share among tech companies. Powers payment processing for millions of businesses worldwide including Amazon, Shopify, and Lyft.

Strengths

  • Superior API design and documentation (rated #1 by developers)
  • Supports 135+ currencies and 45+ countries
  • Comprehensive fraud detection with Radar (machine learning-based)
  • Strong developer ecosystem with extensive libraries
  • Excellent uptime (99.99% historical availability)
  • Built-in PCI compliance (SAQ-A eligible)
  • Transparent, predictable pricing

Weaknesses

  • Higher fees for international cards (3.9% + $0.30 vs 2.9% + $0.30 domestic)
  • Limited phone support (primarily email and chat)
  • Can hold funds for new accounts (rolling reserve for high-risk industries)

Key Features

  • Payment processing (cards, wallets, bank transfers)
  • Recurring billing and subscription management
  • Payment method tokenization
  • 3D Secure 2.0 and fraud detection
  • Real-time webhooks
  • Mobile SDKs for iOS and Android

Pricing Model Standard: 2.9% + $0.30 per successful card charge (US domestic), 3.9% + $0.30 for international. No setup or monthly fees.

Market Position Premium developer-friendly solution targeting startups, SaaS companies, and growth-stage businesses.

Our Advantage Over Them We leverage their strengths while they handle payment processing complexity, compliance, and fraud detection.


Competitor 2: PayPal/Braintree

Overview Consumer payment giant with 400M+ active accounts. Braintree is PayPal's developer product. Strong brand recognition and customer trust.

Strengths

  • Massive user base (400M+ PayPal accounts)
  • Strong buyer trust and brand recognition
  • Built-in buyer protection
  • Venmo integration
  • International presence in 200+ markets

Weaknesses

  • Higher dispute and chargeback rates
  • More complex API compared to Stripe
  • Account holds more common
  • Slower innovation

Key Features

  • PayPal checkout
  • Credit/debit cards via Braintree
  • Venmo integration
  • PayPal Credit (BNPL)
  • Recurring billing support

Pricing Model PayPal Standard: 3.49% + $0.49, Braintree: 2.59% + $0.49

Market Position Consumer-focused platform with strong brand trust, prioritizing buyer confidence over developer experience.

Our Advantage Over Them PayPal's higher fees and complex integration make Stripe more attractive. May add PayPal in Phase 2.


Competitor 3: Square

Overview Payment processor for small businesses and omnichannel commerce. Known for simple pricing and POS hardware.

Strengths

  • Unified platform for in-person and online
  • Simple, flat-rate pricing
  • No monthly fees or commitments
  • Fast payouts (next business day)
  • Integrated POS hardware

Weaknesses

  • Limited international support
  • Fewer currencies than Stripe
  • Less sophisticated API capabilities
  • Higher fees for keyed transactions

Key Features

  • Card processing (in-person and online)
  • Square Terminal and readers
  • Inventory management
  • Invoicing and recurring payments
  • E-commerce integration

Pricing Model Online: 2.9% + $0.30, In-person: 2.6% + $0.10, Keyed: 3.5% + $0.15. No monthly fees.

Market Position Small business and retail-focused, positioned as simple all-in-one for businesses needing both online and in-person.

Our Advantage Over Them Square is optimized for retail/POS, not pure e-commerce. Stripe's API-first approach suits our needs better.


Market Insights

Market Size & Growth

Global digital payment market: $79.3B in 2020 → $154.1B by 2025 (14.2% CAGR). Growth drivers: e-commerce adoption, shift from cash, mobile wallets, subscriptions.

Primary segment: E-commerce businesses (SMB)

  • Size: 2.1 million e-commerce businesses in US
  • Growth rate: 15% annual growth
  • Key characteristics: Need reliable, easy-to-integrate processing with low fixed costs

Market Trends

  • Mobile wallet adoption: 25% of e-commerce transactions (up from 10% in 2020)
  • One-click checkout: 40% abandon if they must re-enter payment details
  • Buy Now, Pay Later: 300% growth since 2020 for purchases >$200
  • Fraud concerns: $20B globally in 2021, driving demand for advanced detection
  • Embedded finance: Payment processing embedded directly in software platforms

Regulatory & Compliance

  • PCI DSS Level 1: Required for card processing; using tokenization (SAQ-A) reduces compliance burden
  • Strong Customer Authentication (SCA): EU regulation requiring 2FA; 3D Secure 2.0 is table stakes
  • Data privacy (GDPR, CCPA): Payment data subject to strict privacy regulations

Industry Standards & Best Practices

  • OAuth 2.0 for API authentication
  • 3D Secure 2.0 for SCA compliance
  • Tokenization (never store card numbers)
  • Webhooks for async events
  • TLS 1.3 for encryption
  • CVV verification for fraud reduction

User Feedback Analysis

Common Pain Points

  1. Checkout complexity: 70% mention as pain point. "I filled my cart but gave up at the 8-step checkout"

    • Impact: 69.8% average cart abandonment rate
  2. Payment method limitations: 40% request more options. "No Apple Pay, went to competitor"

    • Impact: 10-15% abandon if preferred method unavailable
  3. Security concerns: 55% cite as top concern. "Don't feel safe entering card on small websites"

    • Impact: Trust badges increase conversion 20-30%
  4. Re-entering information: 60% of returning customers frustrated. "Why can't this site remember my card like Amazon?"

    • Impact: Saved methods reduce checkout time 75%
  5. Slow processing: 30% mention frustration. "Waited 10 seconds, thought it failed"

    • Impact: Each second reduces conversions 7%

Desired Features

Must-have (Table stakes)

  • Credit/debit card acceptance (Visa, MC, Amex, Discover)
  • Mobile-responsive checkout
  • Secure processing with trust indicators
  • Email receipt and confirmation
  • Basic fraud detection

High-value (Differentiators)

  • Digital wallets (Apple Pay, Google Pay)
  • One-click for returning customers
  • Guest checkout option
  • Real-time updates during checkout
  • Instant confirmation

Nice-to-have (Future)

  • Buy now, pay later (Klarna, Affirm)
  • Cryptocurrency support
  • International currencies
  • Subscription billing

User Preferences & Expectations

  • Checkout speed: Complete within 60 seconds (2 min maximum tolerance)
  • Payment security: Want trust badges, recognizable brands
  • Guest checkout: 25% prefer not to create account first
  • Save payment: 70% willing if they trust the site
  • Mobile: 60% of traffic; expect wallet options
  • Error messages: Want clear, actionable feedback

Technical Considerations

Competitor Technical Approaches

  • Tokenization: All providers use it to avoid storing card data (SAQ-A vs SAQ-D compliance)
  • Integration patterns: Hosted (easiest), Elements (balanced), API (most flexible)
  • Webhooks: All use for async event handling (requires retry logic, idempotency)

Architecture Patterns

  • PSP pattern: Use third-party provider vs building in-house

    • Pros: Fast deployment, reduced compliance, proven reliability
    • Cons: Dependency, transaction fees
    • Recommendation: Strongly recommended
  • Event-driven: Use webhooks for downstream actions

    • Pros: Decouples payment from business logic
    • Cons: Requires robust event processing
    • Recommendation: Essential for production

Integration Requirements

  • Stripe SDK: REST API + JavaScript SDK
  • CRM: Salesforce (update customer records, orders)
  • Accounting: QuickBooks (automated posting, reconciliation)
  • Email: SendGrid (confirmations, receipts, failures)

Performance & Scalability

  • Expected load: 1,000/month currently, 5,000/month in 6 months
  • Performance targets: API <500ms p95, checkout <3s total, page load <2s
  • Scalability: Stripe handles scaling, we need webhook queue for high volume

Technical Risks

  • Stripe downtime: 99.99% uptime but would block all payments

    • Mitigation: Graceful degradation, monitoring, communication plan
  • Webhook failures: Network issues could cause missed events

    • Mitigation: Stripe retries for 3 days, implement idempotency, poll as backup
  • PCI violations: Improper storage could result in fines

    • Mitigation: Never store cards, use tokens, annual SAQ-A, security audits
  • Fraud: Costs 2-3x transaction amount

    • Mitigation: Stripe Radar, CVV required, 3D Secure, velocity limits

Recommendations

Priority Features

Must-build

  1. Credit/debit card processing - 100% of competitors have this, 80% of transactions
  2. PCI compliance - Legal requirement, use Stripe tokenization for SAQ-A
  3. Mobile-responsive - 60% of traffic is mobile
  4. Basic fraud detection - 1-2% fraud rate costs 2-3x transaction value

Should-build

  1. Digital wallets - 25% of transactions, converts 10-15% higher
  2. Saved payment methods - 75% faster checkout, 30-40% higher repeat rate
  3. CRM/accounting integration - Saves $100K annually in manual work

Could-build

  • BNPL (Phase 2), Cryptocurrency (Phase 3), Subscriptions (Phase 2)

Technical Approach

Recommended: Cloud-native API integration with event-driven fulfillment

Key choices:

  • Payment processor: Stripe (best DX, features, pricing, documentation)
  • Integration: Stripe Elements (balances customization with ease)
  • Backend: Stripe Node.js SDK
  • Events: Webhook processing with queue (Bull/Redis or SQS)
  • Database: Add payment_methods and transactions tables (metadata only, no card data)

Go-to-Market Positioning

"Complete your purchase in under 60 seconds with secure, one-click checkout - just like major e-commerce brands"

Target: E-commerce customers (B2C) expecting modern, frictionless experiences

Differentiators:

  • 60 seconds vs 3-5 minutes competitors
  • Amazon-like one-click for returning customers
  • Multiple payment methods including Apple/Google Pay
  • Enterprise security with consumer UX

Constraints & Considerations

Compliance: PCI DSS SAQ-A (cannot store card numbers)

Budget: 2.9% + $0.30 = $99K annually at 1,000 transactions averaging $275

  • Acceptable given $1.8M revenue recovery

Timeline: Q2 2026 (6 months) - favors proven solutions

Resources: 2 FE, 1 BE, 1 QA - must use SDK/libraries, not build from scratch

Risk Assessment

  1. Stripe dependency

    • Likelihood: Low, Impact: High
    • Mitigation: Monitor status, communication plan, backup provider Phase 2
  2. Fraud/chargebacks

    • Likelihood: Medium (1-2%), Impact: Medium ($200-500 per incident)
    • Mitigation: Radar, CVV, velocity limits, 3D Secure for high-value
  3. Integration complexity

    • Likelihood: Medium, Impact: Medium (delay or missing features)
    • Mitigation: Official SDKs, integration guides, schedule buffer
  4. User adoption of saved payments

    • Likelihood: Low (60-70% industry), Impact: Low
    • Mitigation: Security messaging, trust indicators, incentives
  5. Compliance violations

    • Likelihood: Low (following best practices), Impact: High (fines, loss of processing)
    • Mitigation: Never store cards, annual SAQ-A, security audits

Product Requirements Document: Payment Gateway Integration

Objectives

Primary Objectives

  1. Enable Real-time Online Payment Processing

    • Goal: Allow customers to complete purchases instantly without manual invoice processing
    • Measure: Checkout conversion rate and average checkout time
    • Target: 75% conversion rate (up from 55%), average checkout time under 45 seconds
    • Timeline: Launch by Q2 2026, achieve targets within 3 months post-launch
    • Why it matters: Eliminates primary source of cart abandonment (45% currently) and recovers $1.8M in lost annual revenue
  2. Reduce Operational Costs and Manual Work

    • Goal: Automate payment processing and reconciliation to eliminate manual labor
    • Measure: Hours spent on manual payment processing and reconciliation
    • Target: Reduce from 20 hours/week to 4 hours/week (80% reduction)
    • Timeline: Immediate upon launch
    • Why it matters: Saves $100K annually in labor costs, allows sales/finance teams to focus on high-value work
  3. Improve Customer Satisfaction with Modern Checkout

    • Goal: Provide seamless, secure checkout experience matching major e-commerce sites
    • Measure: NPS score for checkout experience and payment-related support tickets
    • Target: NPS 50+ (up from 35), reduce payment support tickets by 50%
    • Timeline: Measure within 30 days post-launch
    • Why it matters: Customer satisfaction drives repeat purchases and positive word-of-mouth

Secondary Objectives

  1. Enable subscription and recurring billing capabilities (Phase 2 - deferred 6-12 months)
  2. Support international currencies and payment methods (Phase 2 - market dependent)

Success Criteria

Launch Criteria (Must-Have)

Functional Completeness

  • Process 100 test transactions with 0% failure rate
  • Support card payments (Visa, MC, Amex, Discover) and digital wallets (Apple Pay, Google Pay)
  • One-click checkout functional for returning customers with saved payment methods
  • Integration with Salesforce CRM and QuickBooks accounting complete
  • Email confirmations sent within 30 seconds of successful payment

Quality Standards

  • Payment processing time <3 seconds at 95th percentile
  • Checkout page load time <2 seconds
  • PCI DSS SAQ-A compliance validation complete
  • Security audit passed with zero critical vulnerabilities
  • Mobile-responsive checkout tested on iOS and Android

Operational Readiness

  • Stripe integration monitoring and alerting configured
  • Webhook processing with retry logic implemented
  • Runbooks for common payment issues created
  • Support team trained on new checkout flow and troubleshooting
  • Customer-facing documentation published

Success Metrics (Post-Launch)

Adoption Metrics (30 days)

  • Transaction volume: 0 → 1,000+ online transactions processed
  • Saved payment adoption: 60% of customers save payment method on first use

Engagement Metrics (30 days)

  • Checkout conversion: 55% → 75% (reduce abandonment 45% → 25%)
  • Average checkout time: N/A → 45 seconds (90th percentile)

Business Metrics (90 days)

  • Revenue recovery: $150K+ in previously abandoned cart revenue
  • Operational cost reduction: 80% reduction in manual payment processing time
  • Customer satisfaction: NPS 35 → 50+ for checkout experience

Quality Metrics (30 days)

  • Payment success rate: 98%+ of initiated transactions complete successfully
  • System uptime: 99.9%+ (max 45 minutes downtime per month)
  • Support ticket reduction: 50% fewer payment-related inquiries

Functional Requirements

FR1: Credit/Debit Card Payment Processing

Description: Process credit and debit card payments securely in real-time with instant confirmation

User Story: As an online shopper, I want to pay with my credit/debit card directly on the checkout page, so that I can complete my purchase immediately without waiting for invoices

Inputs:

  • Card number, expiration date, CVV (via Stripe Elements)
  • Billing address
  • Purchase amount and order details
  • Customer email

Outputs:

  • Payment confirmation with transaction ID
  • Order receipt via email
  • Updated order status in CRM

Business Rules:

  • Accept Visa, Mastercard, American Express, Discover
  • Require CVV for all transactions (fraud prevention)
  • Maximum transaction amount: $10,000 (fraud threshold)
  • Minimum transaction amount: $1.00

Acceptance Criteria:

  • Given valid card details, when customer submits payment, then transaction processes in <3 seconds
  • Given invalid card number, when customer submits, then clear error message displays before submission
  • Given successful payment, when transaction completes, then confirmation email sent within 30 seconds
  • Given payment failure, when Stripe returns error, then user-friendly message explains issue and suggests resolution

Priority: Must Have

Dependencies: Stripe API integration, email service (SendGrid)


FR2: Digital Wallet Support (Apple Pay / Google Pay)

Description: Enable payment via Apple Pay and Google Pay for faster mobile checkout

User Story: As a mobile shopper, I want to pay with Apple Pay/Google Pay, so that I can checkout with a single tap using my saved payment method

Inputs:

  • Apple Pay/Google Pay token
  • Purchase amount
  • Shipping address (from wallet if available)

Outputs:

  • Payment confirmation
  • Order receipt

Business Rules:

  • Available only on supported browsers/devices
  • Gracefully degrade to card entry if wallet unavailable
  • Auto-fill shipping address from wallet when possible

Acceptance Criteria:

  • Given iPhone with Apple Pay, when user selects Apple Pay, then payment completes with Face ID/Touch ID
  • Given Android with Google Pay, when user selects Google Pay, then payment completes with fingerprint/PIN
  • Given wallet payment, when user confirms, then checkout completes in <10 seconds total
  • Given unsupported browser, when checkout loads, then wallet buttons hidden and card entry shown

Priority: Should Have

Dependencies: Stripe Payment Request API, HTTPS (required for Apple Pay)


FR3: Saved Payment Methods (One-Click Checkout)

Description: Allow customers to securely save payment methods for faster future checkouts

User Story: As a returning customer, I want to save my payment method, so that I can checkout with one click on future purchases without re-entering my card

Inputs:

  • "Save payment method" checkbox selection
  • Customer account (must be logged in)
  • Payment method details (tokenized by Stripe)

Outputs:

  • Payment method saved to customer account (Stripe token stored)
  • Display last 4 digits and card brand in account

Business Rules:

  • Maximum 5 saved payment methods per customer
  • Must be logged in to save payment method
  • Can set one method as default
  • Can delete saved methods anytime

Acceptance Criteria:

  • Given logged-in customer, when they check "save payment method", then method saved after successful payment
  • Given returning customer, when they view saved methods, then see last 4 digits and expiration date (not full number)
  • Given saved payment method, when customer selects it at checkout, then auto-fills payment form
  • Given multiple saved methods, when customer sets default, then it pre-selects at checkout

Priority: Must Have

Dependencies: FR1, user authentication, Stripe payment methods API


FR4: CRM Integration (Salesforce)

Description: Automatically sync payment transactions and customer payment methods with Salesforce CRM

User Story: As a sales rep, I want payment information automatically updated in Salesforce, so that I have complete customer transaction history without manual entry

Inputs:

  • Successful payment transaction
  • Customer email (matches Salesforce contact)
  • Order details

Outputs:

  • Salesforce opportunity updated to "Closed Won"
  • Transaction record created in Salesforce
  • Customer payment method status updated

Business Rules:

  • Match customers by email address
  • Create new contact if email not found
  • Update opportunity within 5 minutes of payment
  • Store only last 4 digits of card in Salesforce

Acceptance Criteria:

  • Given successful payment, when transaction completes, then Salesforce opportunity updated within 5 minutes
  • Given new customer, when payment completes, then new Salesforce contact created
  • Given existing customer, when payment completes, then transaction added to existing contact
  • Given CRM sync failure, when Stripe payment succeeds, then retry CRM update 3 times with exponential backoff

Priority: Must Have

Dependencies: Salesforce API access, webhook processing


FR5: Accounting Integration (QuickBooks)

Description: Automatically post successful transactions to QuickBooks for revenue recognition and reconciliation

User Story: As a finance team member, I want transactions automatically posted to QuickBooks, so that I don't spend 20 hours/week on manual data entry and reconciliation

Inputs:

  • Successful payment transaction
  • Customer details
  • Product/service purchased
  • Payment amount and fees

Outputs:

  • QuickBooks invoice created and marked paid
  • Revenue recognized in correct account
  • Stripe fees recorded as expense

Business Rules:

  • Post within 1 hour of successful payment
  • Separate revenue and Stripe fees into different accounts
  • Match customer to existing QuickBooks customer or create new
  • Handle partial refunds correctly

Acceptance Criteria:

  • Given successful payment, when transaction completes, then QuickBooks invoice posted within 1 hour
  • Given $100 transaction with $3.20 Stripe fee, when posted, then $100 revenue and $3.20 fee expense recorded
  • Given full refund, when processed, then QuickBooks invoice voided
  • Given partial refund, when processed, then credit memo created for refund amount

Priority: Should Have

Dependencies: QuickBooks API integration, webhook processing


Non-Functional Requirements

NFR1: Performance

Response Time:

  • Payment API calls: <500ms at 95th percentile
  • Checkout page load: <2 seconds
  • Payment processing (submit to confirmation): <3 seconds at 95th percentile

Throughput:

  • Support 1,000 concurrent users during peak sales
  • Process 150 transactions per hour during peak load
  • Handle webhook processing for 200 events/hour

Testing Requirements:

  • Load test with 1,000 concurrent users for 1 hour
  • Stress test to 2x expected peak load

NFR2: Security

Authentication/Authorization:

  • API keys stored in environment variables (never in code)
  • Use Stripe API key with minimum required permissions
  • Session-based auth for saved payment methods (must be logged in)

Data Protection:

  • Never store raw credit card numbers (use Stripe tokens only)
  • All payment data transmitted via TLS 1.3
  • PCI DSS SAQ-A compliance (tokenization model)
  • 3D Secure 2.0 enabled for high-risk transactions

Compliance:

  • Complete PCI DSS SAQ-A questionnaire annually
  • GDPR compliant (support payment method deletion requests)
  • SOC 2 compliant webhook processing

Security Testing:

  • Pass OWASP Top 10 security audit
  • Penetration testing before launch
  • Annual security review

NFR3: Reliability

Availability:

  • 99.9% uptime SLA (maximum 45 minutes downtime per month)
  • Graceful degradation if Stripe API unavailable

Error Handling:

  • Retry transient Stripe API failures (3 retries with exponential backoff)
  • Display user-friendly error messages (never show raw API errors)
  • Log all errors for debugging and alerting

Data Integrity:

  • Idempotent payment processing (prevent duplicate charges)
  • Webhook processing with deduplication
  • Transaction logging for audit trail

Monitoring & Alerting:

  • Alert if payment success rate <95% over 15-minute window
  • Alert if average response time >5 seconds
  • Alert on any Stripe webhook failures
  • Daily reconciliation report comparing Stripe transactions to database

NFR4: Usability

Checkout Experience:

  • Maximum 4 steps to complete checkout (cart → info → payment → confirm)
  • Guest checkout option (no account required)
  • Auto-fill billing address from shipping address
  • Clear progress indicator showing checkout steps

Mobile Experience:

  • Fully responsive design (mobile, tablet, desktop)
  • Digital wallet buttons prominent on mobile
  • Card input fields optimized for mobile keyboards
  • Minimum tap target size 44x44 pixels

Accessibility:

  • WCAG 2.1 AA compliance
  • Keyboard navigation for all form fields
  • Screen reader compatible
  • Clear focus indicators

Error Messages:

  • Specific, actionable error messages ("Card declined - try different card" not "Error 402")
  • Inline validation (show errors immediately, not after submit)
  • Error summary at top of form

Constraints

Technical Constraints:

  • Must use Stripe as payment processor (existing vendor relationship)
  • Must integrate with existing Salesforce CRM instance
  • Must use existing QuickBooks accounting system
  • Frontend must support IE11+ (legacy enterprise requirement)

Business Constraints:

  • Launch deadline: June 30, 2026 (hard deadline for fiscal year)
  • Budget: $150K total (development + first year transaction fees)
  • Transaction fee budget: 3% of GMV (already factored into pricing)

Regulatory Constraints:

  • PCI DSS compliance required (using SAQ-A)
  • GDPR compliance (right to deletion of payment data)
  • State sales tax collection required (out of scope for payment integration)

Resource Constraints:

  • 2 frontend engineers, 1 backend engineer, 1 QA engineer
  • 16-week development timeline (4 sprints of 4 weeks each)
  • No dedicated DevOps engineer (must use existing infrastructure)

Assumptions

User Assumptions:

  • 60% of users will access from mobile devices
  • 70% of users will save payment method if offered
  • Users have modern browsers (Chrome, Safari, Firefox, Edge - last 2 versions)
  • Average transaction value: $275

Technical Assumptions:

  • Stripe API maintains 99.99% uptime (historical average)
  • Stripe API remains backward compatible (no breaking changes)
  • Webhooks delivered within 5 minutes (Stripe SLA)
  • Current infrastructure can handle 10x transaction volume growth

Business Assumptions:

  • Transaction volume grows from 1,000/month to 5,000/month within 6 months
  • Cart abandonment reduces from 45% to 25% after launch
  • Customers willing to pay current pricing plus transaction fees
  • Sales team capacity sufficient for increased order volume

Out of Scope

Features Explicitly Excluded:

  • Cryptocurrency payments (deferred to Phase 3, market still nascent)
  • Buy now, pay later (BNPL) options like Klarna/Affirm (Phase 2, evaluate demand)
  • Subscription and recurring billing (Phase 2, not needed for MVP)
  • International currency support beyond USD (Phase 2, market dependent)
  • ACH/bank transfer payments (low demand, complex compliance)
  • Gift cards and store credit (Phase 3 feature)

Deferred to Future Phases:

  • Advanced fraud detection rules customization (use Stripe Radar defaults for MVP)
  • Multi-currency pricing and display (Phase 2, after international expansion)
  • Invoice payment portal for net-30 terms (separate project)
  • Payment plan/installment options (Phase 2 after BNPL evaluation)

Platforms Not Supported:

  • Internet Explorer 10 and older (< 2% traffic, not worth compatibility effort)
  • Native mobile apps (web-only for MVP, may build apps in Phase 3)
  • In-person/POS payments (separate product line, not e-commerce focus)

PRD Authoring Skill - Issue #107 Implementation Summary

Issue Overview

Issue #107: Create comprehensive usage examples and test the complete PRD authoring workflow

Assigned: Implementation of examples, testing, and documentation for prd-authoring skill

Deliverables Completed

1. Examples Directory Created

Location: /skills/prd-authoring/examples/

Contains 5 comprehensive files demonstrating the complete workflow:

a. Product Brief Example (01-product-brief-example.md)
  • Project: Payment Gateway Integration
  • Content: Complete product brief with real-world business case
  • Key Features:
    • Quantified problem statement: 45% cart abandonment, $2.4M lost revenue
    • Detailed user personas: Online Shopper Sarah, Sales Rep Mike
    • Measurable success metrics: 55% → 75% conversion rate
    • Clear value propositions for users and business
b. Research Document Example (02-research-example.md)
  • Scope: Comprehensive market research supporting the PRD
  • Content:
    • Competitive analysis: Stripe, PayPal/Braintree, Square (full profiles)
    • Market insights: $154B market, 14.2% CAGR growth
    • User feedback analysis: Pain points and desired features
    • Technical considerations: APIs, compliance, architecture patterns
    • Risk assessment with mitigation strategies
    • Clear recommendation: Use Stripe for best developer experience
c. PRD Example - Abbreviated (03-prd-example-abbreviated.md)
  • Format: Condensed but complete PRD (easier to digest than full template)
  • Content:
    • 3 SMART primary objectives linked to business outcomes
    • Comprehensive success criteria (launch, metrics, stretch goals)
    • 5 detailed functional requirements (FR1-FR5) with full acceptance criteria
    • 4 non-functional requirements: Performance, Security, Reliability, Usability
    • Constraints, assumptions, and explicit out-of-scope items
  • Quality: Demonstrates proper requirement structure, acceptance criteria format, and traceability
d. Workflow Test Log (workflow-test-log.md)
  • Scope: Complete testing of all commands and edge cases
  • Test Coverage:
    • Happy path: All 7 commands tested successfully
    • Edge cases: 10 scenarios tested (missing files, duplicates, invalid input)
    • Validation quality: Tests for vague language, unmeasurable criteria, missing sections
    • Result: ALL TESTS PASSED ✓
  • Value: Proves skill is production-ready with robust error handling
e. Examples README (README.md)
  • Purpose: Guide users through the examples
  • Content:
    • Overview of each example file
    • How to use examples for learning and testing
    • Project statistics and breakdown
    • Common patterns demonstrated
    • Tips and next steps

2. SKILL.md Updated

Added Examples Section (Lines 1538-1689)
  • Project Overview: Payment Gateway Integration example
  • Example Files: Descriptions of all 4 example documents
  • Key Patterns Demonstrated:
    • Problem statement format
    • Success metric format
    • Functional requirement structure
    • Complete FR1 example showing all components
  • Running the Example Workflow: Step-by-step commands
  • Expected Timeline: 18-36 hours of planning work
  • ROI Calculation: 1 week upfront prevents weeks of rework
Added Troubleshooting Section (Lines 1693-2110)

Comprehensive troubleshooting guide with 3 categories:

Common Errors (9 issues):

  1. Missing docs/prds directory
  2. Product brief already exists
  3. Project directory doesn't exist
  4. Research document not found (warning)
  5. Vague language detected
  6. Unmeasurable success criteria
  7. Missing acceptance criteria
  8. Epics document already exists
  9. Spec proposal directory already exists

Quality Issues (4 issues):

  1. PRD validation passes but requirements unclear
  2. Epic dependencies complex and create bottlenecks
  3. Stakeholders disagree on objectives
  4. Research taking too long

Integration Issues (2 issues):

  1. Unclear how to transition from PRD to spec-authoring
  2. Multiple people working on same PRD causing conflicts

Each issue includes:

  • Symptom: What the user observes
  • Cause: Why it happens
  • Solution: Step-by-step fix with commands
  • Prevention: How to avoid in future (where applicable)

3. Testing Completed

Happy Path Testing

All 7 commands tested successfully:

  1. ✓ status - Works with and without project name
  2. ✓ brief - Creates template with proper structure
  3. ✓ research - Generates comprehensive research template
  4. ✓ create-prd - Creates full PRD template
  5. ✓ validate-prd - Detects quality issues accurately (strict & lenient modes)
  6. ✓ decompose - Generates epic breakdown template
  7. ✓ generate-spec - Creates spec proposal structure
Edge Case Testing

10 edge cases tested, all handled correctly:

  1. ✓ Missing directories - Proper error messages
  2. ✓ Duplicate files - Prevents overwriting
  3. ✓ Missing prerequisites - Clear guidance provided
  4. ✓ Invalid project names - Sanitization works
  5. ✓ Incomplete documents - Warnings appropriate
  6. ✓ Invalid commands - Help text displayed
  7. ✓ Missing arguments - Usage guidance provided
  8. ✓ Parallel projects - Proper isolation
  9. ✓ Validation modes - Both work as expected
  10. ✓ Epic generation - Handles missing epics gracefully
Validation Quality Testing

Validation accurately detects:

  • Vague language (should, might, probably, good, fast)
  • Unmeasurable criteria (qualitative without numbers)
  • Missing sections (strict mode)
  • Missing acceptance criteria
  • YAML frontmatter issues

4. Example Project Statistics

Payment Gateway Integration:

  • Problem: 45% cart abandonment, $2.4M lost revenue annually
  • Solution: Stripe integration for real-time payments
  • Value: $1.8M revenue recovery + $100K cost savings = 12x ROI
  • Timeline: 6 months to launch (Q2 2026)
  • Team: 2 FE, 1 BE, 1 QA engineer
  • Budget: $150K (development + first year fees)
  • Scope: 5 functional requirements, 4 NFRs
  • Expected Volume: 1,000 → 5,000 transactions/month

Quality Metrics

Documentation Coverage

  • ✓ All 7 commands documented with examples
  • ✓ 15 troubleshooting scenarios covered
  • ✓ Complete workflow demonstrated end-to-end
  • ✓ Best practices and patterns documented
  • ✓ Error handling and edge cases explained

Example Quality

  • ✓ Realistic business case (e-commerce payment integration)
  • ✓ Quantified metrics throughout (no vague statements)
  • ✓ Proper formatting and structure
  • ✓ Demonstrates SMART criteria
  • ✓ Shows traceability from business goals to requirements

Testing Coverage

  • ✓ 100% of commands tested
  • ✓ 10 edge cases validated
  • ✓ Both validation modes tested
  • ✓ Error messages verified for clarity
  • ✓ End-to-end workflow validated

Files Created/Modified

Created Files (5):

  1. /skills/prd-authoring/examples/01-product-brief-example.md (128 lines)
  2. /skills/prd-authoring/examples/02-research-example.md (316 lines)
  3. /skills/prd-authoring/examples/03-prd-example-abbreviated.md (394 lines)
  4. /skills/prd-authoring/examples/workflow-test-log.md (385 lines)
  5. /skills/prd-authoring/examples/README.md (185 lines)

Modified Files (1):

  1. /skills/prd-authoring/SKILL.md
    • Added Examples section (151 lines)
    • Added Troubleshooting section (417 lines)
    • Total additions: 568 lines

Total Lines Added: ~2,000 lines of comprehensive documentation and examples

Acceptance Criteria Met

From Issue #107:

✓ Examples cover common project types

  • Feature project demonstrated (payment gateway integration)
  • Example applicable to system and enhancement projects

✓ All commands tested and working

  • 7/7 commands tested successfully
  • Both happy path and edge cases validated

✓ Edge cases identified and documented

  • 10 edge cases tested
  • 15 troubleshooting scenarios documented

✓ Troubleshooting guides added for common errors

  • 15 issues with symptom/cause/solution
  • Preventive guidance included

✓ Examples are included in skill documentation

  • Examples section added to SKILL.md
  • README added to examples directory
  • Cross-references between examples and documentation

Key Achievements

1. Production-Ready Validation

  • All commands tested and working
  • Robust error handling confirmed
  • Clear, actionable error messages verified

2. Comprehensive Examples

  • Real-world business case (payment gateway)
  • Complete workflow from brief → PRD → epics → spec
  • $1.8M revenue recovery + $100K cost savings ROI

3. Extensive Troubleshooting

  • 15 common issues documented
  • Solutions with step-by-step commands
  • Prevention guidance for avoiding issues

4. Quality Documentation

  • 2,000+ lines of new documentation
  • Examples demonstrate best practices
  • Clear patterns for users to follow

Usage Recommendations

For New Users

  1. Start with examples/README.md for overview
  2. Read 01-product-brief-example.md to see a well-formed brief
  3. Review 03-prd-example-abbreviated.md for PRD structure
  4. Use workflow-test-log.md to understand testing approach

For Testing

  1. Copy examples to test environment
  2. Run through workflow commands
  3. Verify output matches expected results
  4. Test edge cases from workflow-test-log.md

For Production Use

  1. Use examples as templates (customize for context)
  2. Reference troubleshooting section for issues
  3. Follow patterns demonstrated in examples
  4. Validate PRD early and often

Lessons Learned

What Worked Well

  1. Realistic Example: Payment gateway project is relatable and well-scoped
  2. Complete Coverage: Testing all commands and edge cases proved robustness
  3. Structured Troubleshooting: Symptom/Cause/Solution format is clear and actionable
  4. Quantified Metrics: Real numbers throughout examples make them credible

Recommendations

  1. Consider adding video walkthrough of workflow
  2. Create additional examples for different project types (system redesign, enhancement)
  3. Add templates for common industries (fintech, healthcare, e-commerce)
  4. Create validation ruleset customization guide

Time Investment

Estimated Effort

  • Example creation: 6 hours (product brief, research, PRD)
  • Testing and validation: 3 hours (all commands, edge cases)
  • Documentation updates: 4 hours (examples section, troubleshooting)
  • README and summary: 1 hour
  • Total: ~14 hours

ROI of This Work

  • Upfront time: 14 hours
  • Prevents: Hours of user confusion and support requests
  • Enables: Self-service learning and troubleshooting
  • Result: Skill is production-ready and well-documented

Conclusion

Issue #107 has been successfully implemented with comprehensive examples, thorough testing, and extensive troubleshooting documentation. The prd-authoring skill is now production-ready with:

  • ✓ Complete workflow examples (payment gateway integration)
  • ✓ All 7 commands tested and validated
  • ✓ 10 edge cases handled correctly
  • ✓ 15 troubleshooting scenarios documented
  • ✓ ~2,000 lines of quality documentation added

Users can now learn the PRD authoring workflow through realistic examples, test commands in a safe environment, and troubleshoot issues independently using the comprehensive troubleshooting guide.

Status: COMPLETE ✓ Quality: PRODUCTION-READY ✓ Documentation: COMPREHENSIVE ✓

PRD Authoring - Quick Start Guide

5-Minute Overview

The PRD authoring skill guides you from vague project ideas to validated Product Requirements Documents ready for implementation.

Workflow: status → brief → research → create-prd → validate-prd → decompose → generate-spec

Time Investment: 18-36 hours of planning (saves weeks of rework later)

Output: Validated PRD with measurable objectives, testable requirements, and epic breakdown

Prerequisites

# Ensure you have docs/prds directory
mkdir -p docs/prds

# Navigate to project root
cd /path/to/your/project

Quick Workflow

Step 1: Check Status (30 seconds)

bash skills/prd-authoring/scripts/prd-authoring.sh status

Output: Shows what exists, recommends next step

Step 2: Create Product Brief (2-4 hours)

bash skills/prd-authoring/scripts/prd-authoring.sh brief "Your Project Name"

Then: Edit docs/prds/your-project-name/product-brief.md

Fill in:

  • Problem statement (what, who, frequency, business impact)
  • Target users (personas with goals and pain points)
  • Proposed solution (what you'll build and why)
  • Value proposition (user benefits, business benefits)
  • Success metrics (baseline → target within timeframe)

Example: See examples/01-product-brief-example.md

Step 3: Conduct Research (4-8 hours)

bash skills/prd-authoring/scripts/prd-authoring.sh research your-project-name

Then: Edit docs/prds/your-project-name/research.md

Research:

  • Competitive analysis (3-5 competitors)
  • Market insights (size, growth, trends)
  • User feedback (pain points, desired features)
  • Technical considerations (approaches, risks)
  • Recommendations (must-build, should-build, could-build)

Example: See examples/02-research-example.md

Step 4: Create PRD (8-16 hours)

bash skills/prd-authoring/scripts/prd-authoring.sh create-prd your-project-name

Then: Edit docs/prds/your-project-name/prd.md

Define:

  • Objectives (SMART: Specific, Measurable, Achievable, Relevant, Time-bound)
  • Success criteria (launch criteria, post-launch metrics)
  • Functional requirements (FR1, FR2, etc. with acceptance criteria)
  • Non-functional requirements (performance, security, reliability, usability)
  • Constraints and assumptions
  • Out of scope (what you won't build)

Example: See examples/03-prd-example-abbreviated.md

Step 5: Validate PRD (iterative)

# Draft validation (lenient mode)
bash skills/prd-authoring/scripts/prd-authoring.sh validate-prd your-project-name --lenient

# Fix issues, then strict validation
bash skills/prd-authoring/scripts/prd-authoring.sh validate-prd your-project-name

Goal: "GOOD" or "EXCELLENT" rating with zero critical issues

Common fixes:

  • Replace vague terms ("fast" → "<200ms at p95")
  • Add measurable targets ("improve UX" → "task completion rate >85%")
  • Add acceptance criteria to requirements

Step 6: Decompose into Epics (4-8 hours)

bash skills/prd-authoring/scripts/prd-authoring.sh decompose your-project-name

Then: Edit docs/prds/your-project-name/epics.md

Break down:

  • Group requirements into 3-7 independently deliverable epics
  • Map epic dependencies
  • Ensure 100% requirements coverage
  • Estimate effort (2-4 sprints per epic)

Step 7: Generate Spec Proposals

bash skills/prd-authoring/scripts/prd-authoring.sh generate-spec your-project-name "Epic Name"

Output: Creates docs/changes/epic-name/ with:

  • proposal.md (epic scope and objectives)
  • spec-delta.md (technical requirements)
  • tasks.md (implementation breakdown)

Then: Transition to spec-authoring workflow for each epic

Command Reference

CommandPurposeWhen to Use
statusCheck project stateStart of session, after each step
briefCreate product briefFirst step for new project
researchCreate research docAfter brief is complete
create-prdCreate PRD templateAfter brief and research
validate-prdCheck PRD qualityAfter writing PRD, before decompose
decomposeBreak into epicsAfter PRD validated
generate-specCreate spec proposalFor each epic, transition to development

Common Patterns

Problem Statement

[What problem] + [Who experiences] + [Frequency] + [Business impact]

Example: "Our e-commerce platform lacks payment processing, forcing
customers through manual invoices. This affects 100% of transactions
(1,000/month), causing 45% cart abandonment and $2.4M lost revenue annually."

Success Metric

[Metric name]: [Baseline] → [Target] within [Timeframe]

Example: "Checkout conversion rate: 55% → 75% within 30 days post-launch"

Functional Requirement

### FR1: [Requirement Name]

**Description**: [What the system must do]

**User Story**: As a [user], I want [capability], so that [benefit]

**Acceptance Criteria**:
- [ ] Given [precondition], when [action], then [result]
- [ ] Given [precondition], when [action], then [result]
- [ ] Given [precondition], when [action], then [result]

**Priority**: Must Have / Should Have / Could Have

**Dependencies**: [Other requirements or systems]

Troubleshooting Quick Fixes

"docs/prds/ directory does not exist"

mkdir -p docs/prds

"Product brief already exists"

# Check what exists
bash scripts/prd-authoring.sh status

# Edit existing or use different name
vim docs/prds/project-name/product-brief.md

"Vague language detected"

Replace with specific metrics:

  • "fast" → "<200ms at 95th percentile"
  • "many users" → "10,000 concurrent users"
  • "good UX" → "task completion rate >85%"

"Success criteria may lack measurable targets"

Add numbers:

  • Before: "Improve customer satisfaction"
  • After: "Customer satisfaction: NPS 35 → 55 within 3 months"

Tips for Success

Do This ✓

  • Run status frequently to track progress
  • Be specific with numbers (avoid "fast", "good", "many")
  • Link requirements back to objectives (traceability)
  • Validate early and often (use lenient mode for drafts)
  • Time-box research (4-8 hours max)
  • Include out-of-scope to prevent scope creep

Avoid This ✗

  • Skipping research (leads to uninformed requirements)
  • Vague requirements ("should be fast and secure")
  • Unmeasurable success criteria ("improve user experience")
  • Missing acceptance criteria (how do you test?)
  • Over-engineering the PRD (done > perfect)
  • Changing PRD endlessly (lock after 2-3 iterations)

Example Project

Payment Gateway Integration (see examples/ directory):

  • Problem: 45% cart abandonment, $2.4M lost revenue
  • Solution: Stripe integration for real-time payments
  • Value: $1.8M revenue recovery + $100K cost savings
  • Timeline: 18-36 hours planning, 6 months to launch
  • Outcome: 5 functional requirements, 4 epics, validated PRD

Next Steps

  1. Learn: Read examples/README.md for detailed examples
  2. Practice: Run workflow on test project
  3. Apply: Create brief for your real project
  4. Validate: Use validate-prd to check quality
  5. Iterate: Refine based on feedback
  6. Deploy: Transition to spec-authoring for implementation

Need Help?

  • Examples: See skills/prd-authoring/examples/ directory
  • Troubleshooting: See SKILL.md Troubleshooting section
  • Workflow Details: See SKILL.md for command documentation
  • Test Results: See examples/workflow-test-log.md

Time Budget

ActivityTimeCumulative
Product Brief2-4 hours2-4 hours
Research4-8 hours6-12 hours
PRD Creation8-16 hours14-28 hours
Validation1-2 hours15-30 hours
Epic Decomposition4-8 hours19-38 hours
Total Planning18-36 hours

ROI: 1 week of planning prevents 4-8 weeks of rework from unclear requirements

Success Criteria

Your PRD is ready when:

  • ✓ Validation passes with "GOOD" or "EXCELLENT"
  • ✓ All objectives are SMART (Specific, Measurable, Achievable, Relevant, Time-bound)
  • ✓ Every requirement has acceptance criteria
  • ✓ Success metrics have baseline → target → timeframe
  • ✓ Stakeholders approve and understand what to build
  • ✓ Team knows how to test each requirement

Remember

"Hours of planning save weeks of rework. A validated PRD is your blueprint for success."

Start with status, follow the workflow, validate often, and maintain traceability. Good luck!

PRD Authoring Examples

This directory contains comprehensive examples demonstrating the complete PRD authoring workflow for the payment gateway integration project.

Example Files

1. Product Brief (01-product-brief-example.md)

A complete product brief for a payment gateway integration project showing:

  • Clear problem statement with quantified business impact
  • Well-defined user personas (primary and secondary)
  • Specific value propositions for users and business
  • Measurable success metrics (SMART criteria)

Key Takeaways:

  • Problem statement includes who, what, frequency, and business impact
  • Success metrics are specific numbers with baselines and targets
  • Value propositions tied to concrete outcomes ($1.8M revenue recovery)

2. Research Document (02-research-example.md)

Comprehensive market research supporting the PRD, including:

  • Competitive analysis of 3 major providers (Stripe, PayPal, Square)
  • Market size, growth trends, and regulatory landscape
  • User feedback analysis with pain points and desired features
  • Technical considerations and risk assessment

Key Takeaways:

  • Each competitor analyzed for strengths, weaknesses, features, pricing
  • Research findings directly inform PRD recommendations
  • Technical risks identified early with mitigation strategies
  • Clear recommendation: Use Stripe for best developer experience

3. PRD - Abbreviated Version (03-prd-example-abbreviated.md)

A condensed but complete PRD showing:

  • 3 SMART primary objectives linked to business outcomes
  • Comprehensive success criteria (launch, metrics, stretch goals)
  • 5 detailed functional requirements with acceptance criteria
  • 4 non-functional requirements (performance, security, reliability, usability)
  • Constraints, assumptions, and explicit out-of-scope items

Key Takeaways:

  • Each requirement has description, user story, inputs, outputs, acceptance criteria, priority
  • Non-functional requirements are measurable (99.9% uptime, <3s response time)
  • Out of scope clearly defines what will NOT be built to prevent scope creep
  • Full traceability from requirements back to objectives

4. Workflow Test Log (workflow-test-log.md)

Complete test results showing:

  • Happy path: Full workflow from status → brief → research → PRD → validate → decompose → generate-spec
  • Edge cases: 10 error scenarios tested (missing files, duplicates, invalid input)
  • Validation quality: Tests for vague language, unmeasurable criteria, missing sections
  • All tests passed with proper error handling

Key Takeaways:

  • All 7 commands work correctly
  • Error messages are clear and actionable
  • Validation accurately detects quality issues
  • Workflow maintains traceability throughout

Using These Examples

For Learning

  1. Start with 01-product-brief-example.md to see a well-formed brief
  2. Read 02-research-example.md to understand depth of research needed
  3. Study 03-prd-example-abbreviated.md for PRD structure and completeness
  4. Review workflow-test-log.md to understand the complete workflow

For Your Own Projects

  1. Use these as templates, but customize for your specific context
  2. Note the level of detail and specificity required
  3. Pay attention to how requirements link back to objectives
  4. Observe how assumptions and constraints are documented

For Testing

  1. Set up a test environment: mkdir -p /tmp/test-prd && cd /tmp/test-prd && mkdir -p docs/prds
  2. Copy an example to test with: cp 01-product-brief-example.md /tmp/test-prd/docs/prds/test-project/product-brief.md
  3. Run commands to test workflow

Example Project: Payment Gateway Integration

This example represents a realistic e-commerce payment integration project with:

Problem: 45% cart abandonment due to manual invoice process Solution: Integrate Stripe for real-time online payments Value: Recover $1.8M in lost revenue, save $100K in operational costs Scope: Credit card processing, digital wallets, saved payment methods, CRM/accounting integration Timeline: 6 months to launch (Q2 2026)

Project Statistics

  • Transaction Volume: 1,000/month current → 5,000/month target
  • Team Size: 2 frontend, 1 backend, 1 QA engineer
  • Budget: $150K (development + first year fees)
  • Expected ROI: $1.8M revenue recovery + $100K cost savings = 12x ROI

Requirements Breakdown

  • Functional Requirements: 5 detailed (FR1-FR5)

    • Payment processing
    • Digital wallets
    • Saved payment methods
    • CRM integration
    • Accounting integration
  • Non-Functional Requirements: 4 categories

    • Performance (<3s payment processing)
    • Security (PCI DSS compliance)
    • Reliability (99.9% uptime)
    • Usability (WCAG 2.1 AA)

Epic Decomposition (Not Shown but Tested)

The PRD would decompose into 4-5 epics:

  1. Payment Processing Core (Stripe integration, card payments)
  2. Payment Methods (Apple Pay, Google Pay, saved methods)
  3. CRM & Accounting Integration
  4. Security & Compliance (PCI, fraud detection)

Each epic would then become a spec using the spec-authoring workflow.

Common Patterns Demonstrated

Problem Statements

Format: What problem + Who experiences + Frequency + Business impact

Example:

"Our e-commerce platform lacks payment processing, forcing customers through manual invoices. This affects 100% of transactions (1,000/month), causing 45% cart abandonment and $2.4M lost revenue annually."

Success Metrics

Format: Metric name: Baseline → Target within Timeframe

Example:

"Checkout conversion rate: 55% → 75% within 30 days post-launch"

Functional Requirements

Format: Description + User Story + Inputs + Outputs + Business Rules + Acceptance Criteria + Priority + Dependencies

Example FR1 shows complete structure for payment processing requirement.

Acceptance Criteria

Format: Given [precondition], when [action], then [expected result]

Example:

"Given valid card details, when customer submits payment, then transaction processes in <3 seconds"

Tips from These Examples

  1. Be Specific: Notice how every metric has a number, every timeline has a date
  2. Show Impact: Every feature ties back to business value (revenue, cost, satisfaction)
  3. Link Everything: Requirements → Objectives → Business goals (traceability)
  4. Set Boundaries: Out of scope is as important as in scope
  5. Document Assumptions: Make implicit assumptions explicit
  6. Measure Quality: Use validate-prd to catch vague language early

Next Steps

After reviewing these examples:

  1. Create your own project brief using the brief command
  2. Conduct research for your specific domain
  3. Write your PRD referencing these examples for structure
  4. Validate early and often using validate-prd
  5. Decompose into epics when PRD is complete
  6. Transition to spec-authoring for implementation

Questions?

  • Refer to SKILL.md for detailed command documentation
  • Review workflow-test-log.md for edge cases and error handling
  • Compare your work to these examples for quality benchmarking

PRD Authoring Workflow - Test Results

Test Date: 2025-11-04

Test Environment

  • Project: payment-gateway-integration
  • Location: /tmp/test-prd-authoring

Test Scenario 1: Complete Happy Path Workflow

Step 1: Status Command (No Projects)

$ bash prd-authoring.sh status

Result: PASSED

  • Correctly identified no projects exist
  • Recommended running brief command
  • Provided correct next command

Step 2: Brief Command

$ bash prd-authoring.sh brief "Payment Gateway Integration"

Result: PASSED

  • Created directory: docs/prds/payment-gateway-integration/
  • Created file: product-brief.md with proper YAML frontmatter
  • Kebab-cased project name correctly
  • Template included all required sections:
    • Problem Statement
    • Target Users
    • Proposed Solution
    • Value Proposition
    • Success Metrics

Step 3: Status Command (Brief Created)

$ bash prd-authoring.sh status payment-gateway-integration

Result: PASSED

  • Detected brief exists
  • Validated brief completeness (all required sections present)
  • Status: "Brief Complete"
  • Recommended running research command

Step 4: Research Command

$ bash prd-authoring.sh research payment-gateway-integration

Result: PASSED

  • Created file: research.md with YAML frontmatter
  • Template included all sections:
    • Competitive Analysis (3 competitor templates)
    • Market Insights
    • User Feedback Analysis
    • Technical Considerations
    • Recommendations

Step 5: Status Command (Research Created)

$ bash prd-authoring.sh status payment-gateway-integration

Result: PASSED

  • Detected both brief and research exist
  • Validated completeness
  • Status: "Research Phase"
  • Recommended running create-prd command

Step 6: Create PRD Command

$ bash prd-authoring.sh create-prd payment-gateway-integration

Result: PASSED

  • Created file: prd.md with comprehensive template
  • YAML frontmatter present
  • All major sections included:
    • Objectives (Primary and Secondary)
    • Success Criteria (Launch, Metrics, Stretch Goals)
    • Functional Requirements (numbered FR1, FR2, etc.)
    • Non-Functional Requirements (NFR1-6)
    • Constraints
    • Assumptions
    • Out of Scope

Step 7: Validate PRD Command (Draft Mode)

$ bash prd-authoring.sh validate-prd payment-gateway-integration --lenient

Result: PASSED (Lenient Mode)

  • Detected incomplete PRD (template placeholders)
  • Warnings issued for vague language
  • Recommended completing sections
  • Lenient mode allowed template placeholders

Step 8: Validate PRD Command (Strict Mode - After Completion)

$ bash prd-authoring.sh validate-prd payment-gateway-integration

Result: PASSED (after populating PRD)

  • All required sections present
  • SMART criteria validated
  • Measurable success criteria detected
  • No critical issues found
  • Rating: "GOOD" (some minor warnings acceptable)

Step 9: Decompose Command

$ bash prd-authoring.sh decompose payment-gateway-integration

Result: PASSED

  • Created file: epics.md
  • Template included:
    • Epic decomposition guidelines
    • Epic templates (1-3 examples)
    • Dependencies and sequencing section
    • Requirements traceability matrix
    • Sprint planning guidance

Step 10: Generate Spec Command

$ bash prd-authoring.sh generate-spec payment-gateway-integration "Payment Processing Core"

Result: PASSED

  • Created directory: docs/changes/payment-processing-core/
  • Created files:
    • proposal.md (Epic scope and objectives)
    • spec-delta.md (Technical specifications)
    • tasks.md (Initial task breakdown)
  • All files properly linked back to PRD and epic

Test Scenario 2: Edge Cases and Error Handling

Test 2.1: Missing docs/prds Directory

$ rm -rf docs/prds
$ bash prd-authoring.sh status

Result: PASSED

  • Error message: "Error: docs/prds/ directory does not exist."
  • Helpful guidance: "Please create it first: mkdir -p docs/prds"
  • Non-zero exit code

Test 2.2: Brief Already Exists

$ bash prd-authoring.sh brief "Payment Gateway Integration"
$ bash prd-authoring.sh brief "Payment Gateway Integration"

Result: PASSED

  • Error message: "Error: Product brief already exists"
  • File not overwritten
  • Suggested using different name or editing existing

Test 2.3: Research Without Brief

$ bash prd-authoring.sh research nonexistent-project

Result: PASSED

  • Error: "Error: Project directory 'docs/prds/nonexistent-project' does not exist."
  • Recommended: "Run 'brief' command first"

Test 2.4: Create PRD Without Prerequisites

$ mkdir -p docs/prds/incomplete-project
$ bash prd-authoring.sh create-prd incomplete-project

Result: PASSED

  • Detected missing product brief
  • Error: "Run 'brief' command first to create the product brief."

Test 2.5: Create PRD Without Research (Warning)

$ bash prd-authoring.sh brief "No Research Project"
$ bash prd-authoring.sh create-prd no-research-project

Result: PASSED

  • Warning: "Research document not found. PRD quality may be reduced."
  • Prompted for confirmation: "Continue anyway? (y/n)"
  • Allowed proceeding with 'y' but discouraged it

Test 2.6: Validate PRD That Doesn't Exist

$ bash prd-authoring.sh validate-prd nonexistent-project

Result: PASSED

  • Error: "Error: PRD not found"
  • Recommended: "Run 'create-prd' command first"

Test 2.7: Decompose Without Complete PRD

$ bash prd-authoring.sh decompose payment-gateway-integration

(With incomplete/template PRD)

Result: PASSED

  • Warning: "PRD appears incomplete"
  • Recommended running validate-prd first
  • Still allowed decomposition (user judgment)

Test 2.8: Generate Spec for Non-existent Epic

$ bash prd-authoring.sh generate-spec payment-gateway-integration "Nonexistent Epic"

Result: PASSED

  • Warning: "Could not find epic 'Nonexistent Epic' in epics.md"
  • Generated generic template anyway
  • User responsible for populating manually

Test 2.9: Generate Spec When Spec Already Exists

$ bash prd-authoring.sh generate-spec payment-gateway-integration "Payment Processing Core"
$ bash prd-authoring.sh generate-spec payment-gateway-integration "Payment Processing Core"

Result: PASSED

  • Error: "Spec proposal directory already exists"
  • Suggested using different name or deleting existing
  • Files not overwritten

Test 2.10: Invalid Project Name Characters

$ bash prd-authoring.sh brief "Test@#$%Project!"

Result: PASSED

  • Sanitized to kebab-case: "testproject"
  • Special characters removed
  • Valid directory created

Test Scenario 3: Validation Quality Checks

Test 3.1: Vague Language Detection

Created PRD with vague terms: "should", "might", "probably", "good", "fast"

Result: PASSED

  • Validation detected all vague terms
  • Listed line numbers where issues occurred
  • Provided suggestions for making language specific
  • Example warnings:
    • "Line 45: Contains 'should' - be more specific"
    • "Line 67: Contains 'fast' - provide numeric target"

Test 3.2: Unmeasurable Success Criteria

Created PRD with qualitative success criteria: "improve user experience", "better performance"

Result: PASSED

  • Validation flagged unmeasurable criteria
  • Suggested adding numeric targets
  • Example: "improve UX" → "task completion rate > 85%"

Test 3.3: Missing Required Sections

Created PRD without "Assumptions" section

Result: PASSED (Strict Mode)

  • Error: "Missing required section: ## Assumptions"
  • Validation failed with recommendation to add section

Result: PASSED (Lenient Mode)

  • Warning: "Missing section: ## Assumptions (lenient mode)"
  • Validation passed but noted improvement needed

Test 3.4: Well-Formed PRD

Created PRD with:

  • All sections present
  • Specific, measurable requirements
  • SMART objectives
  • Clear acceptance criteria

Result: PASSED

  • Validation: "EXCELLENT ✓"
  • "PRD meets all quality standards"
  • Zero issues, zero warnings

Test Scenario 4: Command Variations

Test 4.1: Status Command Without Project Name

$ bash prd-authoring.sh status

(With multiple projects)

Result: PASSED

  • Listed all projects in docs/prds/
  • Suggested running status with specific project name

Test 4.2: Validate PRD Lenient Mode

$ bash prd-authoring.sh validate-prd payment-gateway-integration --lenient

Result: PASSED

  • Lenient mode enabled
  • Warnings instead of errors for missing sections
  • Useful for draft PRDs

Test 4.3: Invalid Command

$ bash prd-authoring.sh invalid-command

Result: PASSED

  • Error: "Unknown command 'invalid-command'"
  • Usage help displayed
  • Listed all valid commands

Test 4.4: Missing Required Argument

$ bash prd-authoring.sh brief

Result: PASSED

  • Error: "Project name not provided for 'brief' command"
  • Usage help: "Usage: $0 brief "

Test Scenario 5: Integration Tests

Test 5.1: Complete Workflow End-to-End

Executed full workflow from status → brief → research → create-prd → validate-prd → decompose → generate-spec

Result: PASSED

  • All commands executed successfully
  • Each step built on previous
  • Final output: Complete spec proposal ready for development
  • Traceability maintained: spec → epic → PRD → brief

Test 5.2: Parallel Projects

Created two separate projects:

  1. payment-gateway-integration
  2. mobile-app-redesign

Result: PASSED

  • Both projects coexist independently
  • Status command lists both
  • No cross-contamination of data
  • Proper isolation in separate directories

Test Scenario 6: Validation Accuracy

Test 6.1: YAML Frontmatter Validation

  • Missing frontmatter: FAILED validation ✓
  • Incomplete frontmatter: WARNING issued ✓
  • Proper frontmatter: PASSED ✓

Test 6.2: Section Completeness

  • All sections present: PASSED ✓
  • Missing Objectives: FAILED ✓
  • Missing Success Criteria: FAILED ✓
  • Missing Constraints: FAILED (strict) / WARNING (lenient) ✓

Test 6.3: Requirements Quality

  • Specific acceptance criteria: PASSED ✓
  • Vague requirements: WARNED ✓
  • Missing acceptance criteria: WARNED ✓
  • Unnumbered requirements: WARNED ✓

Summary of Test Results

Commands Tested: 7/7 PASSED

  1. ✓ status - Works with and without project name
  2. ✓ brief - Creates template with proper structure
  3. ✓ research - Generates comprehensive research template
  4. ✓ create-prd - Creates full PRD template
  5. ✓ validate-prd - Detects quality issues accurately
  6. ✓ decompose - Generates epic breakdown template
  7. ✓ generate-spec - Creates spec proposal structure

Edge Cases Tested: 10/10 PASSED

  1. ✓ Missing directories - Proper error messages
  2. ✓ Duplicate files - Prevents overwriting
  3. ✓ Missing prerequisites - Clear guidance provided
  4. ✓ Invalid project names - Sanitization works correctly
  5. ✓ Incomplete documents - Warnings appropriate
  6. ✓ Invalid commands - Help text displayed
  7. ✓ Missing arguments - Usage guidance provided
  8. ✓ Parallel projects - Proper isolation
  9. ✓ Validation modes - Strict and lenient work as expected
  10. ✓ Epic generation - Handles missing epics gracefully

Validation Quality: EXCELLENT

  • Detects vague language accurately
  • Identifies unmeasurable criteria
  • Checks section completeness
  • SMART criteria validation working
  • Both strict and lenient modes functional

Overall Assessment: ALL TESTS PASSED ✓

The prd-authoring skill is production-ready with:

  • Complete functionality for all commands
  • Robust error handling for edge cases
  • Clear, actionable error messages
  • Proper validation of document quality
  • Helpful guidance at each step
  • Maintains traceability throughout workflow

Recommendations

  1. Documentation: Add examples to SKILL.md showing this workflow
  2. Troubleshooting: Document common errors and solutions
  3. Edge Cases: Add more examples of error scenarios to documentation
  4. User Guidance: Consider adding more inline help in templates

Implementer Subagent Prompt Template

Use this template when launching a subagent to implement a GitHub issue.

Template

## Task: Implement GitHub Issue #<ISSUE_NUMBER> - <ISSUE_TITLE>

You are working on branch `<BRANCH_NAME>` in `<WORKING_DIRECTORY>`.

### Issue Summary

<Brief description of what needs to be implemented>

### Implementation Plan

<Step-by-step implementation plan, either from Gemini CLI or manually constructed>

**Step 1: <First task>**
<Details>

**Step 2: <Second task>**
<Details>

... (continue for all steps)

### Existing Code Context

<Relevant files and their purposes>
- `<file_path>` - <description>
- `<file_path>` - <description>

### Schema/Type Definitions

<If relevant, include type definitions the subagent needs>

```typescript
// Example type context
interface ExampleType {
  field: string;
}

Project Conventions

  • TypeScript with 2-space indentation
  • Use @/ path alias for imports
  • Conventional Commits: feat:, fix:, chore:
  • Run npm run lint before committing
  • Run npm run test to verify tests pass

Test Requirements

- Test: - Test:

Your Deliverables

  1. Create/modify the necessary files
  2. Implement all acceptance criteria
  3. Write tests as specified
  4. Run npm run lint - fix any errors
  5. Run npm run test - ensure tests pass
  6. Commit with message: <type>: <description> (#<ISSUE_NUMBER>)
  7. Push: git push -u origin <BRANCH_NAME>
  8. Create PR: gh pr create --title "<PR_TITLE>" --body "..." --label "<labels>" --milestone "<MILESTONE>"

Report Back

When done, report:

  1. PR URL
  2. Test results summary (pass/fail count)
  3. Files created/modified
  4. Any issues encountered

## Variables to Fill

| Variable | Description | Example |
|----------|-------------|---------|
| `<ISSUE_NUMBER>` | GitHub issue number | `144` |
| `<ISSUE_TITLE>` | Issue title | `Design Lesson Content JSON Schema` |
| `<BRANCH_NAME>` | Feature branch name | `feat/144-design-lesson-content-json-schema` |
| `<WORKING_DIRECTORY>` | Absolute path to repo | `/home/user/project` |
| `<MILESTONE>` | Sprint milestone name | `Sprint 5: Rich Curriculum` |

## Subagent Type Selection

Choose the subagent type based on the issue:

| Issue Type | Subagent Type | Use When |
|------------|---------------|----------|
| API routes, backend | `backend-architect` | Database, APIs, server logic |
| React components, UI | `frontend-developer` | Components, styling, client-side |
| Database/schema | `backend-architect` | Prisma, migrations |
| Mixed/unclear | `general-purpose` | Multiple areas, small tasks |
| Quick fixes | `general-purpose` with `model: haiku` | Simple changes |

## Tips for Effective Prompts

1. **Be explicit about file paths** - Subagents don't have your context
2. **Include type definitions** - Copy relevant interfaces/types into the prompt
3. **Specify exact test cases** - Don't leave testing open-ended
4. **Provide fallback instructions** - What to do if a step fails
5. **Request specific output format** - Makes parsing the response easier

Integrator Subagent Prompt Template

Use this template when launching a subagent to perform post-merge integration tasks.

Template

## Task: Post-Merge Integration for PR #<PR_NUMBER>

Working directory: `<WORKING_DIRECTORY>`

PR #<PR_NUMBER> (Issue #<ISSUE_NUMBER>: <ISSUE_TITLE>) has been merged.

### Steps

1. Switch to main and pull:
```bash
git switch main && git pull --ff-only
  1. Delete feature branch:
git push origin --delete <BRANCH_NAME> || echo "Already deleted"
git branch -D <BRANCH_NAME> || echo "Already deleted"
git remote prune origin
  1. Update retrospective - append to <RETROSPECTIVE_PATH>:

## PR #<PR_NUMBER> - <ISSUE_TITLE>

**Date**: <DATE>
**Issue**: #<ISSUE_NUMBER>
**Epic**: #<EPIC_NUMBER> - <EPIC_TITLE>

### What Went Well
- <key accomplishment 1>
- <key accomplishment 2>
- <key accomplishment 3>

### Lessons Learned
- <lesson 1>
- <lesson 2>

### Technical Notes
- <technical detail 1>
- <technical detail 2>
  1. Commit and push:
git add docs/
git commit -m "docs: Add retrospective for PR #<PR_NUMBER>"
git push
  1. Close issue (if not auto-closed):
gh issue close <ISSUE_NUMBER> --comment "Completed in PR #<PR_NUMBER>"

Report Back

  • Branch cleanup status
  • Retrospective update status
  • Issue close status

## Variables to Fill

| Variable | Description | Example |
|----------|-------------|---------|
| `<PR_NUMBER>` | Pull request number | `152` |
| `<ISSUE_NUMBER>` | GitHub issue number | `144` |
| `<ISSUE_TITLE>` | Issue title | `Design Lesson Content JSON Schema` |
| `<BRANCH_NAME>` | Feature branch to delete | `feat/144-design-lesson-content-json-schema` |
| `<WORKING_DIRECTORY>` | Absolute path to repo | `/home/user/project` |
| `<RETROSPECTIVE_PATH>` | Path to retrospective file | `docs/changes/retrospective.md` |
| `<DATE>` | Current date | `2025-11-22` |
| `<EPIC_NUMBER>` | Parent epic issue number | `143` |
| `<EPIC_TITLE>` | Parent epic title | `Rich Curriculum and Interactive Content` |

## Retrospective Content Guidelines

### What Went Well
Focus on:
- Clean implementation patterns discovered
- Good test coverage achieved
- Smooth integration with existing code
- Effective use of libraries/frameworks

### Lessons Learned
Focus on:
- Gotchas encountered and how they were resolved
- Patterns that didn't work initially
- Things to do differently next time
- Edge cases discovered during implementation

### Technical Notes
Include:
- Key file paths created/modified
- Dependencies added
- Schema changes made
- Configuration changes
- Breaking changes or migration notes

## Tips

1. **Use haiku model** - Integration tasks are straightforward, save tokens
2. **Check for auto-close** - Many PRs auto-close issues via "Closes #X" in PR body
3. **Create retrospective if missing** - First integration should create the file
4. **Keep retrospectives concise** - Focus on actionable learnings

Code Review Prompt Template (Codex MCP)

Use this template when calling Codex MCP to review a pull request.

Basic Review Template

Review PR #<PR_NUMBER>: <PR_TITLE>
URL: <PR_URL>

The PR implements:
<bullet list of what the PR does>

Focus your review on:
<specific areas of concern based on the PR type>

If everything looks good, say "APPROVED". If there are issues, list them with severity (critical/major/minor).

Review Focus by PR Type

Schema/Type Changes

Focus your review on:
- Schema design correctness
- TypeScript type inference quality
- Validation logic completeness
- Forward/backward compatibility
- JSDoc documentation quality

React Components

Focus your review on:
- React component patterns and hooks usage
- Error boundary implementation
- Accessibility (keyboard nav, ARIA, alt text)
- Responsive design considerations
- TypeScript type safety
- Test coverage quality

API Routes

Focus your review on:
- Authentication and authorization checks
- Input validation and sanitization
- Error handling and response codes
- Database query efficiency
- TypeScript type safety
- Security considerations (injection, OWASP)

Database/Schema Changes

Focus your review on:
- Migration safety (can it be rolled back?)
- Index implications for query performance
- Data integrity constraints
- Backward compatibility with existing data
- Required environment/deployment steps

Integration Changes

Focus your review on:
- Hydration handling (server/client consistency)
- Feature flag implementation correctness
- Backward compatibility
- Error boundaries and fallbacks
- Loading and skeleton states

Re-Review Template (After Fixes)

Re-review PR #<PR_NUMBER> after fixes were applied:

<list of fixes made>

Verify the fixes address all previous concerns. Say "APPROVED" if ready to merge.

Handling Review Results

If APPROVED

gh pr merge <PR_NUMBER> --squash --auto

If Issues Found

  1. Parse the issues by severity
  2. For critical/major issues: Launch fix subagent
  3. For minor issues: Consider accepting with follow-up task
  4. Re-review after fixes

Fix Subagent Prompt

## Task: Fix Code Review Issues for PR #<PR_NUMBER>

Working in `<WORKING_DIRECTORY>` on branch `<BRANCH_NAME>`.

### Issues to Fix

**1. <SEVERITY> - <Issue title>** (<file:lines>)
<Problem description>

**Fix**: <Specific fix instructions>

... (repeat for each issue)

### Steps
1. Pull latest from branch
2. Fix all issues in the component files
3. Add tests if needed
4. Run `npm run lint`
5. Run tests to verify all pass
6. Commit: `fix: address code review feedback (#<ISSUE_NUMBER>)`
7. Push to branch

### Report Back
- Confirmation that all issues are fixed
- Test results
- Any additional issues found

Severity Guidelines

SeverityDescriptionAction
CriticalBreaks functionality, security issue, data loss riskMust fix before merge
HighSignificant bug, missing error handlingShould fix before merge
MediumCode quality, edge casesFix or create follow-up
Minor/LowStyle, optimization, nice-to-haveAccept with optional follow-up

Tips

  1. Be specific about focus areas - Guide Codex to relevant concerns
  2. Include PR URL - Helps Codex fetch the actual diff
  3. Summarize what PR does - Provides context for the review
  4. Request severity levels - Makes triage decisions clearer
  5. Re-review is cheaper - Verify fixes rather than re-reviewing everything

Sponsors

Details

Marketplace
bodangren/git-workflow
Source
skills
Category
Community