claude-skills Documentation

Technical Documentation: Jeffallan/claude-skills

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Quick Start Copy Chapter

/plugin marketplace add jeffallan/claude-skills

Then, install the skills:

/plugin install fullstack-dev-skills@fullstack-dev-skills

For all installation methods and first steps, see the Quick Start Guide.

Full documentation: jeffallan.github.io/claude-skills

Skills Copy Chapter

67 specialized skills across 12 categories covering languages, backend/frontend frameworks, infrastructure, APIs, testing, DevOps, security, data/ML, and platform specialists.

See Skills Guide for the full list, decision trees, and workflow combinations.

Usage Patterns Copy Chapter

Context-Aware Activation Copy Section

Skills activate automatically based on your request:

# Backend Development
"Implement JWT authentication in my NestJS API"
→ Activates: NestJS Expert → Loads: references/authentication.md

# Frontend Development
"Build a React component with Server Components"
→ Activates: React Expert → Loads: references/server-components.md

Multi-Skill Workflows Copy Section

Complex tasks combine multiple skills:

Feature Development: Feature Forge → Architecture Designer → Fullstack Guardian → Test Master → DevOps Engineer
Bug Investigation:   Debugging Wizard → Framework Expert → Test Master → Code Reviewer
Security Hardening:  Secure Code Guardian → Security Reviewer → Test Master

Context Engineering Copy Chapter

Surface and validate Claude's hidden assumptions about your project with /common-ground. See the Common Ground Guide for full documentation.

Project Workflow Copy Chapter

The 9 workflow commands manage epics from discovery through retrospectives, integrating with Jira and Confluence. See Workflow Commands Reference for the full command reference and lifecycle diagrams.

[!TIP]
Setup: Workflow commands require an Atlassian MCP server. See the Atlassian MCP Setup Guide.

Documentation Copy Chapter

• Quick Start Guide - Installation and first steps
• Skills Guide - Skill reference and decision trees
• Common Ground - Context engineering with /common-ground
• Workflow Commands - Project workflow commands guide
• Atlassian MCP Setup - Atlassian MCP server setup
• Local Development - Local skill development
• Contributing - Contribution guidelines
• skills/*/SKILL.md - Individual skill documentation
• skills/*/references/ - Deep-dive reference materials

Contributing Copy Chapter

See Contributing for guidelines on adding skills, writing references, and submitting pull requests.

Changelog Copy Chapter

See Changelog for full version history and release notes.

License Copy Chapter

MIT License - See LICENSE file for details.

Support Copy Chapter

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Repository: github.com/jeffallan/claude-skills

Author Copy Chapter

Built by jeffallan

Principal Consultant at Synergetic Solutions

Fullstack engineering, security engineering, compliance, and technical due diligence.

Community Copy Chapter

Star History Copy Chapter

Built for Claude Code | 9 Workflows | 371 Reference Files | 67 Skills

Site Src Content Docs Index (`site/src/content/docs/index.mdx`) Copy Section

title: Claude Skills
template: splash
hero:
tagline: Transform Claude Code into your expert pair programmer across the entire development stack.
actions:
- text: Get Started
link: /claude-skills/getting-started/
icon: right-arrow
variant: primary
- text: Browse Skills
link: /claude-skills/skills-guide/
variant: minimal

import { Card, CardGrid } from '@astrojs/starlight/components';

Quick Install Copy Chapter

/plugin marketplace add jeffallan/claude-skills

/plugin install fullstack-dev-skills@fullstack-dev-skills

See the Getting Started guide for all installation methods and first steps.

ATLASSIAN MCP SETUP (`docs/ATLASSIAN_MCP_SETUP.md`) Copy Section

Atlassian MCP Server Setup Guide

This guide provides step-by-step instructions for configuring the Atlassian MCP (Model Context Protocol) server to enable Claude to interact with Jira and Confluence.

Table of Contents Copy Chapter

• Prerequisites
• Getting API Tokens
• Environment Setup
• MCP Configuration
• Verification
• Troubleshooting
• Security Considerations

Prerequisites Copy Chapter

Before setting up the Atlassian MCP server, ensure you have:

1. Docker installed and running

   • Verify with: docker --version
   • Docker must be able to pull images from ghcr.io

2. Atlassian account access

   • For Cloud: Account with access to your organization's Jira and Confluence
   • For Server/Data Center: Administrative access to generate personal access tokens

3. Claude Code CLI installed

   • The MCP server integrates with Claude Code for AI-assisted workflows

Getting API Tokens Copy Chapter

Atlassian Cloud (Recommended) Copy Section

API tokens are the standard authentication method for Atlassian Cloud products.

Step 1: Navigate to API Token Management

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Sign in with your Atlassian account

Step 2: Create a New API Token

1. Click Create API token
2. Enter a descriptive label (e.g., "Claude MCP Integration")
3. Click Create
4. Copy the token immediately - it will not be shown again

Step 3: Note Your Credentials

You will need:

• Email address: The email associated with your Atlassian account
• API token: The token you just created
• Instance URL: Your Atlassian Cloud URL (e.g., https://yourcompany.atlassian.net)

Important: The same API token works for both Jira and Confluence if they are on the same Atlassian Cloud instance.

Atlassian Server / Data Center Copy Section

For self-hosted Atlassian products, use Personal Access Tokens (PATs).

Jira Server/Data Center:

1. Navigate to your Jira instance
2. Click your profile icon > Profile
3. Go to Personal Access Tokens
4. Click Create token
5. Set token name and expiry
6. Copy the generated token

Confluence Server/Data Center:

1. Navigate to your Confluence instance
2. Click your profile icon > Settings
3. Go to Personal Access Tokens
4. Click Create token
5. Set token name and expiry
6. Copy the generated token

Environment Setup Copy Chapter

Step 1: Create Environment File Copy Section

Create a .env.local file in your project root (or the directory where you will run Claude Code):

touch .env.local

Step 2: Configure Environment Variables Copy Section

Add the following variables to .env.local based on your setup:

For Atlassian Cloud:

# Confluence Cloud Configuration
CONFLUENCE_URL=https://yourcompany.atlassian.net/wiki
[email protected]
CONFLUENCE_API_TOKEN=your-api-token-here

# Jira Cloud Configuration
JIRA_URL=https://yourcompany.atlassian.net
[email protected]
JIRA_API_TOKEN=your-api-token-here

# Optional: Limit to specific spaces/projects
# CONFLUENCE_SPACES_FILTER=DOCS,WIKI,ENG
# JIRA_PROJECTS_FILTER=PROJ,DEV,OPS

# Optional: Enable read-only mode (disables all write operations)
# READ_ONLY_MODE=true

For Atlassian Server/Data Center:

# Confluence Server Configuration
CONFLUENCE_URL=https://confluence.yourcompany.com
CONFLUENCE_PERSONAL_TOKEN=your-personal-access-token
CONFLUENCE_SSL_VERIFY=true  # Set to "false" for self-signed certificates

# Jira Server Configuration
JIRA_URL=https://jira.yourcompany.com
JIRA_PERSONAL_TOKEN=your-personal-access-token
JIRA_SSL_VERIFY=true  # Set to "false" for self-signed certificates

# Optional: Limit to specific spaces/projects
# CONFLUENCE_SPACES_FILTER=DOCS,WIKI
# JIRA_PROJECTS_FILTER=PROJ,DEV

# Optional: Enable read-only mode
# READ_ONLY_MODE=true

Step 3: Verify .gitignore Copy Section

Ensure .env.local is in your .gitignore to prevent accidental credential exposure:

# Check if .env.local is ignored
grep -q "\.env\.local" .gitignore || echo ".env.local" >> .gitignore

MCP Configuration Copy Chapter

Step 1: Create MCP Configuration File Copy Section

Create or update .mcp.json in your project root:

{
  "mcpServers": {
    "atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        ".env.local",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Step 2: Pull the Docker Image Copy Section

Pre-pull the image to ensure it is available:

docker pull ghcr.io/sooperset/mcp-atlassian:latest

Configuration Options Copy Section

Multiple Environment Files:

If you have separate environment files for different purposes:

{
  "mcpServers": {
    "atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        ".env.atlassian",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Combining with Other MCP Servers:

{
  "mcpServers": {
    "atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        ".env.local",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

Verification Copy Chapter

Step 1: Test Docker Connectivity Copy Section

Verify the container can start and read your environment:

docker run --rm --env-file .env.local ghcr.io/sooperset/mcp-atlassian:latest --help

Step 2: Test with Claude Code Copy Section

Start Claude Code and verify the MCP server is recognized:

claude

Then ask Claude to list available MCP tools or perform a simple operation:

List the Jira projects I have access to.

Or:

Show me the recent pages in Confluence.

Step 3: Verify Specific Operations Copy Section

Test Jira connectivity:

What issues are in project [YOUR_PROJECT_KEY]?

Test Confluence connectivity:

List pages in the [YOUR_SPACE_KEY] Confluence space.

Expected Behavior Copy Section

When working correctly:

• Claude can list Jira projects and issues
• Claude can read and create Confluence pages
• Claude can search across both platforms
• Claude reports any permission errors clearly

Troubleshooting Copy Chapter

Common Issues Copy Section

Issue: "Authentication failed" or "401 Unauthorized"

Causes and solutions:

1. Invalid API token: Regenerate your API token from Atlassian
2. Wrong username: For Cloud, use your email address, not username
3. Token expired: Server/DC tokens may expire; create a new one
4. Wrong URL format:
   • Jira Cloud: https://yourcompany.atlassian.net
   • Confluence Cloud: https://yourcompany.atlassian.net/wiki

Issue: "Connection refused" or "Cannot reach host"

Causes and solutions:

1. Docker networking: Ensure Docker can reach external URLs
2. VPN required: Connect to VPN if accessing internal Atlassian Server
3. Firewall blocking: Check corporate firewall rules
4. Wrong URL: Verify the URL is accessible in your browser

Issue: "SSL certificate verify failed"

For self-signed certificates on Server/Data Center:

CONFLUENCE_SSL_VERIFY=false
JIRA_SSL_VERIFY=false

Issue: "Permission denied" when reading/writing

Causes and solutions:

1. Insufficient permissions: Your Atlassian account needs appropriate project/space permissions
2. Read-only mode enabled: Check if READ_ONLY_MODE=true is set
3. Space/project restrictions: Verify you have access to the specific space or project

Issue: Docker image not found

# Pull the latest image
docker pull ghcr.io/sooperset/mcp-atlassian:latest

# Verify it exists
docker images | grep mcp-atlassian

Issue: Environment file not found

Ensure the path in .mcp.json is correct:

• Use relative path from where Claude Code runs
• Or use absolute path: /Users/yourname/project/.env.local

Debug Mode Copy Section

To see detailed logs, run the container manually:

docker run -it --rm --env-file .env.local ghcr.io/sooperset/mcp-atlassian:latest

Verifying Environment Variables Copy Section

Check that your environment file is properly formatted:

# List all variables (redacted)
grep -E "^[A-Z_]+" .env.local | sed 's/=.*/=***/'

Expected output:

CONFLUENCE_URL=***
CONFLUENCE_USERNAME=***
CONFLUENCE_API_TOKEN=***
JIRA_URL=***
JIRA_USERNAME=***
JIRA_API_TOKEN=***

Security Considerations Copy Chapter

Credential Protection Copy Section

1. Never commit credentials: Ensure .env.local is in .gitignore
2. Use environment-specific files: Keep production and development credentials separate
3. Rotate tokens regularly: Set calendar reminders to rotate API tokens
4. Use minimal permissions: Only grant the Atlassian account permissions it needs

Read-Only Mode Copy Section

For safer exploration or demo environments:

READ_ONLY_MODE=true

This prevents any write operations to Jira or Confluence.

Space and Project Filtering Copy Section

Limit Claude's access to specific areas:

# Only access these Confluence spaces
CONFLUENCE_SPACES_FILTER=DOCS,PUBLIC

# Only access these Jira projects
JIRA_PROJECTS_FILTER=SUPPORT,DOCS

Audit Trail Copy Section

All operations performed through the MCP server are:

• Logged in Atlassian's audit logs
• Associated with your Atlassian account
• Subject to your organization's compliance policies

Token Revocation Copy Section

If you suspect a token has been compromised:

1. Go to Atlassian API Token Management
2. Click Revoke next to the compromised token
3. Create a new token
4. Update your .env.local file

Environment Variable Reference Copy Chapter

Confluence Variables Copy Section

Jira Variables Copy Section

Global Variables Copy Section

Quick Start Checklist Copy Chapter

• Docker installed and running
• API token created at Atlassian
• .env.local created with credentials
• .env.local added to .gitignore
• .mcp.json created with Atlassian configuration
• Docker image pulled: docker pull ghcr.io/sooperset/mcp-atlassian:latest
• Connection tested with Claude Code

Additional Resources Copy Chapter

• Atlassian API Token Documentation
• MCP Atlassian GitHub Repository
• Workflow Commands Reference - Commands that use Atlassian integration

COMMON GROUND (`docs/COMMON_GROUND.md`) Copy Section

Common Ground: Context Engineering for Claude

Surface, validate, and track Claude's hidden assumptions about your project.

Overview Copy Chapter

Claude operates on assumptions—about your tech stack, coding standards, architecture decisions, and preferences. These assumptions are often correct, but when they're wrong, they lead to misaligned work that needs to be redone.

Common Ground makes these assumptions explicit. Instead of Claude silently assuming "this project uses TypeScript strict mode" or "we prefer functional components," it surfaces these beliefs for your validation before proceeding.

Background & Motivation Copy Chapter

This command emerged from a conversation about a fundamental asymmetry in human-AI collaboration: Claude builds an internal model of reality—assumptions, inferences, premises—that shapes everything it produces, but users have no way to see or correct that model until something goes wrong downstream.

The result is a steering problem: once Claude commits to a path, course-correcting feels like fighting momentum rather than navigating together. This command addresses that by making the hidden visible—surfacing Claude's assumptions as an editable artifact so both parties can align before work begins.

Origin Story Copy Section

The idea came from asking Claude a simple question: "If you could write any application, what would it be and why?"

I think I'd build a collaborative reasoning environment—something like a shared thinking space where humans and AI can work through genuinely hard problems together, with the reasoning process itself becoming visible and manipulable.

Most interfaces treat AI as a question-answering machine—you ask, I respond, repeat. But the interesting work happens in the middle: the assumptions we're making, the frames we're using, the paths not taken. Right now that's mostly invisible. You see my output but not the structure underneath.

I'd want something where you could see a problem decomposed spatially—not just as a chat log but as a network of considerations, trade-offs, and dependencies. You could grab a node and say "actually, let's assume X instead" and watch the downstream reasoning update.

This resonated with a user frustration: "I don't have an ergonomic way to say 'hey Claude, let's try this reality.' Once you've gone down a path, it's difficult to steer the ship."

Why "Common Ground"? Copy Section

The command was originally called /reality-check, but the name was changed to better reflect what it actually does.

It's not verification against truth—it's the creation of common ground: a shared place to stand, knowing we still see it differently, but at least pointing at the same patch of earth.

This reflects a deeper insight about intersubjectivity: two minds can never achieve perfect transparency, but they can narrow the gap through iteration. Each cycle of surface → interpret → respond → correct leaves us more aligned.

The ground file isn't ground truth—it's a coordination point that constrains our misunderstandings and gives us something concrete to build from together

Quick Start Copy Chapter

# Surface and validate assumptions (interactive)
/common-ground

# View all tracked assumptions
/common-ground --list

# Quick validation check
/common-ground --check

# Generate reasoning visualization
/common-ground --graph

How It Works Copy Chapter

The Two-Phase Flow Copy Section

When you run /common-ground without flags, Claude executes a two-phase interactive process:

┌─────────────────────────────────────────────────────────────┐
│                    PHASE 1: Surface & Select                │
├─────────────────────────────────────────────────────────────┤
│  1. Analyze context (config files, code patterns, history)  │
│  2. Identify assumptions Claude is making                   │
│  3. Classify by type and proposed confidence tier           │
│  4. Present for user selection                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    PHASE 2: Adjust Tiers                    │
├─────────────────────────────────────────────────────────────┤
│  1. Show selected assumptions with proposed tiers           │
│  2. User promotes/demotes confidence levels                 │
│  3. Add any missing assumptions                             │
│  4. Save to ground file                                     │
└─────────────────────────────────────────────────────────────┘

Modes Copy Section

Confidence Tiers Copy Chapter

Assumptions are organized into three confidence tiers that govern how Claude treats them:

ESTABLISHED (High Confidence) Copy Section

Treat as premises. Claude will not second-guess these unless you explicitly contradict them.

Example:

ESTABLISHED: TypeScript strict mode enabled [inferred from tsconfig.json]
ESTABLISHED: Jest for unit testing [stated by user]

Behavior: Claude proceeds confidently, references these as ground truth.

WORKING (Medium Confidence) Copy Section

Use as defaults, but flag if contradicted. Claude will mention when deviating.

Example:

WORKING: Prefer functional components over classes [inferred from codebase patterns]
WORKING: Use Tailwind for styling [assumed from dependencies]

Behavior: Claude uses these but will note "I'm assuming X based on..." when relevant.

OPEN (Low Confidence) Copy Section

Ask before assuming. Claude will explicitly seek clarification.

Example:

OPEN: Server-side rendering required? [uncertain - needs clarification]
OPEN: Target browser support? [uncertain - no browserlist found]

Behavior: Claude asks a clarifying question before making decisions that depend on these.

Tier Transitions Copy Section

promote                    promote
OPEN ─────────────► WORKING ─────────────► ESTABLISHED
     ◄─────────────         ◄─────────────
         demote                     demote

• Promote when you gain confidence (user confirms, evidence found)
• Demote when circumstances change (new requirements, contradictions)

Assumption Types Copy Chapter

Every assumption has a type that records its origin. Types are immutable—they serve as an audit trail.

Why types matter:

• [stated] assumptions have user authority behind them
• [inferred] assumptions can be verified by checking the source
• [assumed] assumptions are reasonable defaults that may not fit your project
• [uncertain] assumptions should be clarified before relying on them

Grounding File Copy Chapter

Assumptions are stored in a grounding file at:

~/.claude/common-ground/{project-id}/COMMON-GROUND.md

Project Identification Copy Section

Projects are identified by:

1. Git remote URL (e.g., github.com/user/repo) — preferred
2. Absolute path — fallback for non-git projects

File Format Copy Section

# Common Ground: {project_name}

> Last updated: {timestamp}
> Project ID: {project_id}

---

## ESTABLISHED

### TypeScript Configuration
TypeScript strict mode with no implicit any [inferred]
- Source: tsconfig.json
- Confidence: 0.95
- Added: 2026-01-15

### Testing Framework
Jest for unit testing, Playwright for E2E [stated]
- Source: User confirmation
- Confidence: 1.0
- Added: 2026-01-15

---

## WORKING

### Component Patterns
Prefer functional components with hooks over class components [inferred]
- Source: Codebase analysis (95% functional)
- Confidence: 0.75
- Added: 2026-01-15

---

## OPEN

### Deployment Target
Server-side rendering vs static export [uncertain]
- Source: No clear indication in config
- Confidence: 0.3
- Added: 2026-01-15
- Note: Clarify before implementing routing

---

## History

| Date | Change | Assumption | From | To |
|------|--------|------------|------|-----|
| 2026-01-15 | promoted | Component Patterns | OPEN | WORKING |
| 2026-01-15 | added | TypeScript Configuration | — | ESTABLISHED |

Machine-Readable Index Copy Section

A companion ground.index.json provides structured access:

{
  "project_id": "github.com/user/repo",
  "last_updated": "2026-01-15T10:30:00Z",
  "assumptions": [
    {
      "id": "ts-strict",
      "title": "TypeScript Configuration",
      "content": "TypeScript strict mode with no implicit any",
      "type": "inferred",
      "tier": "ESTABLISHED",
      "confidence": 0.95,
      "source": "tsconfig.json",
      "added": "2026-01-15T10:30:00Z"
    }
  ]
}

Reasoning Graph (`--graph`) Copy Chapter

The --graph flag generates a mermaid diagram showing not just what Claude assumes, but how it arrived at those assumptions.

Purpose Copy Section

Make the shape of reasoning visible:

• Decision points where Claude chose between alternatives
• Paths taken vs paths not taken
• Where uncertainty lives in the reasoning chain

Example Graph Copy Section

flowchart TD
    ROOT[Task: Build auth system] --> D1{MVP or Production?}
    D1 -->|"0.8 [inferred]"| P1[Production-grade]
    D1 -->|"0.2 [alternative]"| A1[MVP/Prototype]

    P1 --> D2{Stateless required?}
    D2 -->|"0.7 [assumed]"| P2[JWT + refresh tokens]
    D2 -->|"0.3 [uncertain]"| U1[Redis sessions]

    P2 --> I1[Access token: 15min]
    P2 --> I2[Refresh token: 7 days]

    style D1 fill:#ffcc00,stroke:#333
    style D2 fill:#ffcc00,stroke:#333
    style P1 fill:#90EE90,stroke:#333
    style P2 fill:#90EE90,stroke:#333
    style A1 fill:#cccccc,stroke:#333
    style U1 fill:#FFB366,stroke:#333
    style I1 fill:#87CEEB,stroke:#333
    style I2 fill:#87CEEB,stroke:#333

Node Colors Copy Section

Conversational Updates Copy Section

Since the graph is text-based, you can manipulate it through conversation:

Use Cases Copy Chapter

Starting a New Feature Copy Section

Before implementing, surface assumptions:

/common-ground

Claude identifies what it's assuming about:

• Architecture patterns to follow
• Error handling conventions
• Testing requirements
• Code style preferences

Onboarding to a Codebase Copy Section

When working with an unfamiliar project:

/common-ground --graph

See Claude's mental model of the project structure and make corrections early.

Before Major Refactoring Copy Section

Validate assumptions haven't drifted:

/common-ground --check

Quick validation that existing assumptions still hold before making sweeping changes.

Debugging Misaligned Output Copy Section

When Claude produces something unexpected:

/common-ground --list

Check what assumptions led to that output. Often reveals a misaligned premise.

Best Practices Copy Chapter

1. Run Early, Run Often Copy Section

Surface assumptions at the start of significant work, not after problems appear.

2. Promote Deliberately Copy Section

Don't rush assumptions to ESTABLISHED. WORKING tier is appropriate for most inferences.

3. Keep OPEN Items Visible Copy Section

Uncertain assumptions in OPEN tier are valuable. They remind Claude to ask rather than guess.

4. Review After Major Changes Copy Section

After adding dependencies, changing architecture, or updating requirements, run /common-ground --check.

5. Use the Graph for Complex Tasks Copy Section

For multi-step implementations, --graph reveals the decision tree and helps catch flawed reasoning early.

Troubleshooting Copy Chapter

"No ground file found" Copy Section

Normal for first run. Execute /common-ground to create one.

Assumptions seem stale Copy Section

Run /common-ground --check for quick validation, or full /common-ground to resurface.

Graph is too complex Copy Section

Focus on specific subtrees: "Expand only the authentication branch"

Wrong project detected Copy Section

Check git remote configuration. For non-git projects, the absolute path is used.

Related Documentation Copy Chapter

• Workflow Commands — Project workflow commands
• Atlassian MCP Setup — Jira/Confluence integration
• commands/common-ground.md — Technical implementation
• Common Ground Workflow — Workflow integration details

File Locations Copy Chapter

SUPPORTED AGENTS (`docs/SUPPORTED_AGENTS.md`) Copy Section

Supported Agents

This plugin follows the Agent Skills specification, an open standard for packaging reusable AI agent capabilities. Skills are portable across any agent that implements the spec.

Compatible Agents Copy Chapter

Submit a New Agent Copy Chapter

To add an agent to this list, open a pull request with the following:

1. Verify compatibility — The agent must implement the Agent Skills specification
2. Add to Compatible Agents table — Include agent name (with link), developer, type, and skills documentation link
3. Add to Skills Directory Locations table — Document where the agent looks for project and user skills
4. Provide evidence — Link to the agent's skills documentation or announcement

PR Template Copy Section

## Add [Agent Name] to Supported Agents

- **Agent:** [Name](https://link-to-agent)
- **Developer:** Company/Organization
- **Type:** CLI / IDE / VS Code / Desktop
- **Skills Docs:** [Documentation](https://link-to-docs)
- **Project Skills Directory:** `.agent/skills/`
- **User Skills Directory:** `~/.config/agent/skills/`

Evidence of Agent Skills support: [link to docs/announcement]

Specification Copy Chapter

• Agent Skills Specification — Format definition

WORKFLOW COMMANDS (`docs/WORKFLOW_COMMANDS.md`) Copy Section

Workflow Commands Reference

This document provides comprehensive documentation for the project workflow command system. These commands manage epics through a structured lifecycle from discovery through retrospectives, integrating with Jira for issue tracking and Confluence for documentation publishing.

Table of Contents Copy Chapter

• Introduction
• Full Lifecycle Overview
• Discovery Phase
• Planning Phase
• Execution Phase
• Retrospectives Phase
• Command Reference
• Integration Points
• Checkpoint System

Introduction Copy Chapter

The workflow command system provides a structured approach to managing software development epics from initial research through completion and retrospective analysis. Each command in the system produces outputs that feed into subsequent commands, creating a traceable chain of documentation and decisions.

Key Benefits:

• Consistent documentation across all epics
• Traceable decisions from discovery through implementation
• Automated status updates in Jira
• Centralized knowledge in Confluence
• Built-in quality gates through mandatory checkpoints

Intake Phase (Pre-Workflow) Copy Chapter

Status: Planned — these commands are not yet implemented.

The Intake phase runs once per project to document the existing codebase. See Intake Phase Overview for details.

Full Lifecycle Overview Copy Chapter

The complete workflow spans four distinct phases, each with specialized commands that produce artifacts consumed by downstream phases.

flowchart TB
    subgraph Discovery["Discovery Phase"]
        direction TB
        CED["/project:discovery:create-epic-discovery"]
        MR["Manual Research<br/>Interviews, Spikes, Analysis"]
        SD["/project:discovery:synthesize-discovery"]
        AS["/project:discovery:approve-synthesis"]

        CED -->|"Discovery Document"| MR
        MR -->|"Research Findings"| SD
        SD -->|"Synthesis Document"| AS
    end

    subgraph Planning["Planning Phase"]
        direction TB
        CEP["/project:planning:create-epic-plan"]
        CIP["/project:planning:create-implementation-plan"]

        CEP -->|"Overview Document"| CIP
    end

    subgraph Execution["Execution Phase"]
        direction TB
        ET["/project:execution:execute-ticket"]
        CT["/project:execution:complete-ticket"]

        ET -->|"Implementation Complete"| CT
        CT -->|"Next Ticket"| ET
    end

    subgraph Retrospectives["Retrospectives Phase"]
        direction TB
        CE["/project:retrospectives:complete-epic"]
    end

    Discovery -->|"Tickets Created"| Planning
    SD -->|"Generated Tickets"| CEP
    Planning -->|"Implementation Plan"| Execution
    CIP -->|"Updated Tickets"| ET
    Execution -->|"All Tickets Done"| Retrospectives
    CT -->|"Epic Complete"| CE

Document Flow Summary Copy Section

Discovery Phase Copy Chapter

The discovery phase focuses on research, customer discovery, and validation before implementation begins. Use this phase for epics with significant unknowns or when customer validation is required.

flowchart LR
    subgraph Inputs
        EK["Epic Key<br/>(from Jira)"]
        JT["Linked Tickets"]
    end

    subgraph CreateDiscovery["create-epic-discovery"]
        direction TB
        FE["Fetch Epic"]
        EQ["Extract Questions"]
        GD["Generate Document"]
        PD["Publish to Confluence"]

        FE --> EQ --> GD --> PD
    end

    subgraph ManualWork["Manual Research"]
        direction TB
        UI["User Interviews"]
        TS["Technical Spikes"]
        DA["Data Analysis"]
        CR["Competitive Research"]
    end

    subgraph Synthesize["synthesize-discovery"]
        direction TB
        FS["Fetch Sources"]
        CA["Cross-Analyze"]
        GR["Generate Recommendations"]
        PT["Propose Tickets"]
        PS["Publish Synthesis"]

        FS --> CA --> GR --> PT --> PS
    end

    subgraph Approve["approve-synthesis"]
        direction TB
        RS["Read Synthesis"]
        RD["Resolve Decisions"]
        MT["Modify Tickets"]
        CT["Create in Jira"]

        RS --> RD --> MT --> CT
    end

    subgraph Outputs
        DD["Discovery Document"]
        SD["Synthesis Document"]
        NT["New Tickets<br/>(in target epics)"]
    end

    EK --> CreateDiscovery
    JT --> CreateDiscovery
    CreateDiscovery --> DD
    DD --> ManualWork
    ManualWork --> Synthesize
    Synthesize --> SD
    SD --> Approve
    Approve --> NT

discovery:create (create-epic-discovery) Copy Section

Command: /project:discovery:create-epic-discovery <epic-key>

Purpose: Creates a structured discovery document for research and customer discovery epics, extracting questions and unknowns from linked tickets.

Process:

1. Fetches epic and all linked tickets from Jira
2. Extracts explicit and implicit questions from requirements
3. Categorizes questions by theme (Customer, Technical, Business, Scope)
4. Generates hypothesis map with validation methods
5. Creates research plan with activities and owners
6. Publishes to Confluence

Output Sections:

• Discovery Overview
• Hypothesis Map
• Research Questions Matrix (by category)
• Dependencies and Blockers
• Research Plan
• Decision Framework
• Risk Register
• Target Implementation Epics
• Linked Tickets

Publish Location: /Epics/Discovery/{Epic_Key}/

discovery:synthesize (synthesize-discovery) Copy Section

Command: /project:discovery:synthesize-discovery [source-url...] [--target=<epic-key>]

Purpose: Synthesizes findings from discovery documents and research into a synthesis document with proposed tickets.

Arguments:

• `` - One or more Confluence document URLs (discovery docs, research findings, spike reports)
• --target=<epic-key> - Optional target epic for generated tickets (auto-detected if not specified)

Process:

1. Fetches all source documents
2. Consolidates and cross-analyzes findings
3. Validates/invalidates hypotheses
4. Generates feature recommendations
5. Identifies blocking decisions that must be resolved
6. Creates proposed tickets (not yet in Jira)
7. Publishes synthesis document with machine-readable ticket data

Output Sections:

• Synthesis Overview
• Executive Summary
• Consolidated Findings (Validated/Invalidated Hypotheses, Answered Questions)
• Remaining Unknowns
• Recommendations by Epic
• Blocking Decisions (decisions that block ticket creation)
• Decision Log
• Source Cross-Reference
• Proposed Tickets Data (JSON for discovery:approve)

Publish Location: /Epics/Discovery/{Discovery_Epic_Key}/Synthesis/

Next Step: Run discovery:approve <synthesis-url> to resolve decisions and create tickets.

discovery:approve (approve-synthesis) Copy Section

Command: /project:discovery:approve-synthesis <synthesis-url>

Purpose: Reviews synthesis document, resolves blocking decisions, and creates approved tickets in Jira.

Arguments:

• <synthesis-url> - URL of the synthesis document from discovery:synthesize

Process:

1. Fetches synthesis document and extracts proposed tickets JSON
2. Checks for unresolved blocking decisions
3. Presents decisions for resolution (blocks until all resolved)
4. Allows add/remove/modify of proposed tickets
5. Creates approved tickets in Jira
6. Updates synthesis document status to "Approved"

Blocking Decisions:

• Decisions are identified during synthesis as issues that affect ticket scope
• All blocking decisions MUST be resolved before tickets can be created
• User selects resolution option (A, B, C, etc.) for each decision
• Resolutions are recorded in the synthesis document

Ticket Operations:

• Add: Create new tickets not in the original proposal
• Remove: Exclude tickets from Jira creation
• Modify: Update title, description, story points, priority

Output:

• Created Jira tickets linked to target epic(s)
• Updated synthesis document with approval status and ticket links

Planning Phase Copy Chapter

The planning phase creates comprehensive documentation for implementation. This is where codebase analysis, risk assessment, and detailed implementation planning occur.

flowchart LR
    subgraph Inputs
        EK["Epic Key"]
        CB["Codebase"]
        JT["Jira Tickets"]
    end

    subgraph CreatePlan["create-epic-plan"]
        direction TB
        FE["Fetch Epic & Tickets"]
        EC["Explore Codebase<br/>(Parallel Agents)"]
        RA["Risk Assessment"]
        GD["Generate Overview"]
        PD["Publish Document"]

        FE --> EC --> RA --> GD --> PD
    end

    subgraph CreateImpl["create-implementation-plan"]
        direction TB
        RO["Read Overview Doc"]
        AT["Analyze Tickets"]
        RT["Refine Tickets<br/>(Split, Points, Deps)"]
        GP["Generate Plan<br/>(Waves, Order)"]
        UT["Update Tickets<br/>(Full Details)"]
        PP["Publish Plan"]

        RO --> AT --> RT --> GP --> UT --> PP
    end

    subgraph Outputs
        OD["Overview Document"]
        IP["Implementation Plan"]
        UT2["Updated Jira Tickets<br/>(Self-Contained)"]
    end

    EK --> CreatePlan
    CB --> CreatePlan
    JT --> CreatePlan
    CreatePlan --> OD
    OD --> CreateImpl
    CreateImpl --> IP
    CreateImpl --> UT2

planning:epic-plan (create-epic-plan) Copy Section

Command: /project:planning:create-epic-plan <epic-key>

Purpose: Creates a comprehensive planning document (Overview Document) by analyzing Jira tickets and exploring the codebase.

Process:

1. Fetches epic and all linked tickets
2. Launches parallel agents to explore codebase:
   • Affected modules discovery
   • API patterns analysis
   • Component patterns analysis
   • Test patterns discovery
   • Reference implementations search
3. Documents unknowns and technical decisions
4. Creates risk assessment for each change
5. Publishes Overview Document

Output Sections:

• Epic Overview (Purpose, User Value, Scope)
• Goals and Success Metrics
• Requirements Summary
• Technical Change Overview (with risk scores)
• Impact Analysis
• Testing Strategy
• User Behavior Testing (E2E scenarios)
• Implementation Notes
• Acceptance Criteria
• Open Questions and Risks
• Codebase Analysis (patterns, references, test locations)
• Linked Tickets

Risk Assessment Dimensions:

Risk Levels:

• 7-11: Low - Standard implementation
• 12-16: Medium - Extra review, incremental delivery
• 17-21: High - Spike/POC first, architectural review

Publish Location: /Epics/In Progress/{Epic_Key}/

planning:impl-plan (create-implementation-plan) Copy Section

Command: /project:planning:create-implementation-plan <overview-doc-url>

Purpose: Generates a detailed implementation plan with parallel execution waves and updates all tickets with self-contained implementation details.

Process:

1. Reads Overview Document for context
2. Fetches all Jira tickets
3. Analyzes and refines tickets:
   • Creates new tickets for gaps
   • Splits large tickets (>8 points)
   • Adds story points
   • Links dependencies
4. Generates topologically sorted execution order
5. Creates parallel execution waves
6. Updates each ticket with full implementation details
7. Publishes Implementation Plan

Implementation Plan Sections:

• Summary (metrics, waves, dependencies)
• Completion Status (tracking table)
• Execution Order (topologically sorted)
• Parallel Execution Strategy (by wave)
• Agent Recommendations
• Document Links

Ticket Update Template:
Each ticket is updated to be self-contained with:

• Overview and Implementation Plan links
• Summary
• Implementation Steps (with code snippets)
• Files to Modify (table)
• Complete Test Code
• Acceptance Criteria

Publish Location: /Epics/In Progress/{Epic_Key}/ (as subpage of Overview)

Execution Phase Copy Chapter

The execution phase handles the actual implementation of tickets and tracking of completion status.

flowchart LR
    subgraph Inputs
        TK["Ticket Key"]
        IP["Implementation Plan"]
        CB["Codebase"]
    end

    subgraph Execute["execute-ticket"]
        direction TB
        FT["Fetch Ticket"]
        RP["Read Plan<br/>(Wave Context)"]
        PC["Parallel Check"]
        FT2["Write Failing Test<br/>(RED)"]
        IM["Implement<br/>(GREEN)"]
        RF["Refactor"]
        PS["Present Summary"]

        FT --> RP --> PC --> FT2 --> IM --> RF --> PS
    end

    subgraph Complete["complete-ticket"]
        direction TB
        GT["Gather Context"]
        TJ["Transition Jira<br/>(In Review)"]
        UP["Update Plan<br/>(Status Tables)"]
        CF["Confirm Done"]

        GT --> TJ --> UP --> CF
    end

    subgraph Outputs
        CD["Code Changes"]
        JS["Jira Status Update"]
        PU["Plan Updated"]
    end

    TK --> Execute
    IP --> Execute
    CB --> Execute
    Execute --> CD
    Execute -->|"Ready for Review"| Complete
    Complete --> JS
    Complete --> PU
    PU -->|"Next Ticket"| Execute

execution:execute-ticket Copy Section

Command: /project:execution:execute-ticket <ticket-key>

Purpose: Implements a Jira ticket following its self-contained implementation details.

Process:

1. Fetches ticket from Jira
2. Verifies ticket has implementation details (stops if missing)
3. Reads implementation plan for wave/dependency context
4. Checks for parallel execution opportunities
5. Updates Jira status to "In Progress"
6. Writes failing tests for the acceptance criteria and records the RED result
7. Executes implementation steps until the tests pass, then refactors with tests green
8. Verifies acceptance criteria
9. Presents completion summary with commit message

Parallel Execution:
When implementation plan defines parallel waves:

• Identifies current wave (first with incomplete tickets)
• Offers to spawn specialized agents for parallel execution
• Coordinates completion before advancing waves

Agent Types for Parallel Work:

• frontend-developer - UI/component work
• backend-developer - API/backend services
• database-optimizer - Database changes
• fullstack-developer - Full-stack features
• test-automator - Test coverage

Deviation Handling:
If implementation plan must be deviated from:

1. Stop and report the deviation
2. Present options (proceed, modify, pause)
3. Wait for user approval
4. Document approved deviations

Output:

• Ticket Completion Summary
• Suggested Commit Message
• Changes Made
• Files Modified/Created
• Tests Added
• Deviations from Plan
• Follow-up Tickets Created

execution:complete-ticket Copy Section

Command: /project:execution:complete-ticket [ticket-key]

Purpose: Transitions Jira ticket to "In Review" and updates the implementation plan with completion details.

Arguments:

• [ticket-key] - Optional if context available from recent execute-ticket

Process:

1. Identifies ticket and gathers context
2. Extracts completion details from conversation
3. Confirms before finalizing
4. Transitions Jira to "In Review"
5. Updates Implementation Plan:
   • Completion Status table
   • Execution Order table
   • Parallel Execution wave table
   • Adds Completion Details section

Plan Updates:

## {Ticket_Key} Completion Details

**Completed:** [date]

### Changes Made
* [extracted from summary]

### Tests Added
* [extracted from summary]

### Deviations
[Any deviations, or "None"]

### Follow-up Tickets
[Any follow-up tickets, or "None"]

Retrospectives Phase Copy Chapter

The retrospectives phase generates completion reports for knowledge capture and process improvement.

flowchart LR
    subgraph Inputs
        EK["Epic Key"]
        OD["Overview Document"]
        IP["Implementation Plan"]
        JT["Completed Tickets"]
    end

    subgraph CompleteEpic["retrospectives:complete-epic"]
        direction TB
        VT["Verify All Tickets Done"]
        GR["Generate Report<br/>(12 Sections)"]
        MD["Move Documentation"]
        CE["Close Epic in Jira"]

        VT --> GR --> MD --> CE
    end

    subgraph Outputs
        CR["Completion Report"]
    end

    EK --> CompleteEpic
    OD --> CompleteEpic
    IP --> CompleteEpic
    JT --> CompleteEpic
    CompleteEpic --> CR

retrospectives:complete-epic Copy Section

Command: /project:retrospectives:complete-epic <epic-key>

Purpose: Generates a comprehensive completion report, closes the epic in Jira, and moves documentation to the complete folder.

Process:

1. Verifies all tickets are complete (stops if not)
2. Reviews implementation quality (PRs merged, test coverage)
3. Generates 12-section completion report
4. Updates Overview Document with completion report
5. Moves documentation from /In Progress/ to /Complete/Sprint [N]/
6. Closes epic in Jira
7. Identifies reusable patterns for knowledge transfer

Completion Report Sections:

1. Epic Summary (duration, points, contributors)
2. Objectives and Outcomes
3. Ticket Breakdown
4. Technical Deliverables (files, LOC, coverage)
5. Architecture and Design Decisions
6. Quality Metrics (PRs, bugs, hooks)
7. Technical Debt and Follow-up
8. Testing and Quality Assurance
9. Documentation Delivered
10. Lessons Learned (What Went Well, Improvements, Process)
11. Risk Assessment Review
12. Recommendations for Future Epics

Publish Location:

• From: /Epics/In Progress/{Epic_Key}/
• To: /Epics/Complete/Sprint [N]/{Epic_Key}/

Note: Sprint-level retrospectives (complete-sprint) have been removed in favor of epic-level analysis with retrospectives:complete-epic.

Command Reference Copy Chapter

Quick reference table for all workflow commands:

Integration Points Copy Chapter

Setup Required: See Atlassian MCP Setup Guide for Jira and Confluence configuration.

Jira Integration Copy Section

The workflow commands integrate with Jira for:

Read Operations:

• Fetch epic details and linked tickets
• Query ticket status and dependencies
• Read acceptance criteria and requirements

Write Operations:

• Create new tickets (from synthesis)
• Update ticket descriptions (implementation details)
• Add story points and link dependencies
• Transition ticket status (In Progress, In Review, Done)
• Close epics with resolution

JQL Queries Used:

• "Epic Link" = {Epic_Key} - Find all child tickets
• Status-based queries for completion verification

Confluence Integration Copy Section

All documentation is published to structured Confluence locations:

Document Lifecycle:

1. Created in /In Progress/ during planning
2. Updated throughout execution
3. Moved to /Complete/Sprint [N]/ on epic completion
4. Referenced in sprint retrospectives

Checkpoint System Copy Chapter

Every command includes mandatory user approval gates to ensure human oversight at critical decision points.

Checkpoint Philosophy Copy Section

Checkpoints serve to:

• Prevent unintended changes to Jira or Confluence
• Ensure alignment on approach before work begins
• Provide opportunities to correct course
• Maintain audit trail of decisions

Checkpoint Types Copy Section

Confirmation Checkpoints:
Verify information before proceeding.

Please confirm before I proceed:

Epic Key: CC-123
Epic Title: User Authentication
Linked Tickets: 8 tickets found
Publish Location: /Epics/In Progress/CC-123/

Is this correct? (Yes / No / Correct)

Approval Checkpoints:
Require explicit approval before making changes.

Ready to publish this planning document to Confluence? (Yes / No / Modify)

Decision Checkpoints:
Present options when issues are encountered.

Epic CC-123 has incomplete tickets:

In Progress:
- CC-124: User login form - Status: In Progress

Options:
A) Complete remaining tickets first
B) Move incomplete tickets to backlog and close epic
C) Extend epic deadline and keep open

What would you like to do? [A/B/C]

Checkpoints by Command Copy Section

Checkpoint Responses Copy Section

Critical Rule: Commands must never modify Jira or Confluence without explicit user approval at the appropriate checkpoint.

Utility Commands Copy Chapter

Common Ground Copy Section

Available at any phase. Surfaces and validates Claude's hidden assumptions about the project.

See Common Ground Guide for full documentation.

Workflow Variations Copy Chapter

Standard Implementation Flow Copy Section

For epics with clear requirements:

planning:epic-plan -> planning:impl-plan -> [execution:execute-ticket + execution:complete-ticket] x N -> retrospectives:complete-epic

Discovery-First Flow Copy Section

For epics requiring research:

discovery:create -> [research] -> discovery:synthesize -> discovery:approve -> planning:epic-plan -> planning:impl-plan -> [execution:execute-ticket + execution:complete-ticket] x N -> retrospectives:complete-epic

Best Practices Copy Chapter

Document Linking Copy Section

Always capture and provide document URLs when outputting command results. Downstream commands depend on these URLs:

• discovery:create outputs {Discovery_Document} for discovery:synthesize
• discovery:synthesize outputs {Synthesis_Document} for discovery:approve
• planning:epic-plan outputs {Overview_Document} for planning:impl-plan
• planning:impl-plan outputs {Implementation_Plan} referenced in tickets

Ticket Self-Containment Copy Section

After planning:impl-plan, each ticket should be fully self-contained with:

• All implementation steps
• Complete test code (copy-paste ready)
• File paths and modifications
• Acceptance criteria

This enables execute-ticket to work without fetching external documents.

Parallel Execution Copy Section

Leverage parallel execution waves for efficiency:

• Group independent tickets in the same wave
• Use specialized agents for different work types
• Coordinate completion before advancing to dependent waves

Knowledge Capture Copy Section

Use retrospective phases to capture learnings:

• Document patterns to replicate
• Record anti-patterns to avoid
• Generate actionable improvements
• Update team documentation with new standards

Local Skill Development (`docs/local_skill_development.md`) Copy Section

Local Skill Development Workflow

How to develop and test Claude Code marketplace plugins (skills) without releasing new versions.

Quick Start Copy Chapter

This repo includes Makefile targets that automate the symlink workflow:

make dev-link    # Link your working copy to the plugin cache
make dev-unlink  # Restore the released version

Restart Claude Code after running either command.

How Plugin Loading Works Copy Chapter

Claude Code loads plugins from a cache directory, not from your source code. Understanding this is key to the development workflow.

When you install a plugin, Claude Code clones the repo into marketplaces/ and copies a clean snapshot into cache/. The CLI reads from cache/ at session start. Edits to your working copy or the marketplace clone have no effect until the cache is updated.

Symlink Development Setup Copy Chapter

Symlink the cache directory to your working copy so edits are immediately available on CLI restart.

Step 1: Identify Your Paths Copy Section

Find your plugin's cache path:

cat ~/.claude/plugins/installed_plugins.json | grep installPath

This returns something like:

"installPath": "/home/<user>/.claude/plugins/cache/<plugin>/<name>/<version>"

Note the full path — you'll symlink this directory.

Step 2: Back Up the Cached Version Copy Section

mv ~/.claude/plugins/cache/<plugin>/<name>/<version> \
   ~/.claude/plugins/cache/<plugin>/<name>/<version>.bak

Step 3: Create Symlink to Working Copy Copy Section

Point the cache path to your local development clone:

ln -s /path/to/your/working/copy \
   ~/.claude/plugins/cache/<plugin>/<name>/<version>

Important: Symlink to the directory where you actually edit code, not the marketplace clone that Claude Code manages.

Step 4: Verify Copy Section

ls -la ~/.claude/plugins/cache/<plugin>/<name>/
# Should show: <version> -> /path/to/your/working/copy

Development Workflow Copy Chapter

Once the symlink is in place:

1. Edit skills, commands, or references in your working copy
2. Restart Claude Code — exit the current session and start a new one. Plugins load at session start; changes are not hot-reloaded.
3. Test your changes — invoke the skill or command as a user would
4. Iterate — repeat steps 1-3

No commits, pushes, or version bumps needed during development.

Reverting to the Released Version Copy Chapter

# Remove the symlink
rm ~/.claude/plugins/cache/<plugin>/<name>/<version>

# Restore the backup
mv ~/.claude/plugins/cache/<plugin>/<name>/<version>.bak \
   ~/.claude/plugins/cache/<plugin>/<name>/<version>

Caveats Copy Chapter

Plugin auto-updates may break the symlink Copy Section

Claude Code periodically checks for plugin updates. An auto-update could:

• Replace the symlink with a fresh cache copy
• Write updated files into the symlinked directory (i.e. into your working copy)

If your symlink stops working after you didn't touch it, check whether an auto-update ran and re-create the symlink.

Working copy differs from a clean cache Copy Section

The cache is normally a clean snapshot — no .git/, no IDE files, no uncommitted work. Your symlinked working copy includes all of that. This is generally harmless — the plugin loader reads markdown files and ignores unknown entries — but be aware:

• New files that reference structures you haven't created yet may cause confusing behavior
• .git/, .DS_Store, node_modules/, and similar directories are exposed but ignored

Restart is required Copy Section

Claude Code loads plugins at session start. There is no hot-reload. After every change, exit and restart the CLI.

Testing a Specific Version or Branch Copy Chapter

cd /path/to/your/working/copy
git checkout <branch-or-tag>

# Restart Claude Code — the symlink still points here,
# so it will load whatever is checked out

To compare against the released version, temporarily revert the symlink (see above) and restart.

Quick Reference Copy Chapter

# Setup (one-time)
CACHE=~/.claude/plugins/cache/<plugin>/<name>/<version>
WORKDIR=/path/to/your/working/copy

mv "$CACHE" "${CACHE}.bak"
ln -s "$WORKDIR" "$CACHE"

# Develop (repeat)
# 1. Edit files in $WORKDIR
# 2. Restart Claude Code
# 3. Test

# Teardown (when done)
rm "$CACHE"
mv "${CACHE}.bak" "$CACHE"

V0.5.0 Narrative (`docs/v0.5.0-narrative.md`) Copy Section

v0.5.0 Workflow Narrative

A walkthrough of the full project lifecycle from zero to shipped features.

Related documents:

• Consolidated plan: docs/v0.5.0-plan.md
• YAML schema: docs/workflow/workflow-definition-schema.md
• Workflow manifest: commands/workflow-manifest.yaml

Act 1: Project Onboarding (Intake Phase — Run Once) Copy Chapter

You've just been brought onto a codebase. Maybe it's a legacy app, maybe it's a startup MVP that grew fast. Before any feature work happens, you need to understand what exists.

Step 1: `intake:document-codebase` Copy Section

You run this first. The agent scans the entire codebase and identifies every function, class, module, and endpoint that lacks documentation. It prioritizes public APIs and external-facing interfaces first, then works inward to internal services and utilities. Before touching anything, it presents a scope summary — "I found 247 undocumented functions across 38 files. Here's the breakdown by module." You approve, and it generates docstrings/JSDoc/XML docs throughout the codebase. When it's done, you have a codebase where any developer (or agent) can read a function signature and understand what it does without tracing the implementation.

Inputs: directory (string, optional — defaults to project root)
Outputs: documentation-report (summary of functions, classes, modules documented)
YAML: commands/intake/document-codebase.yaml
Next: intake:capture-behavior

Step 2: `intake:capture-behavior` Copy Section

Now that the code is documented, the agent scans for untested behavior. It identifies functions, endpoints, and components that have no test coverage. It builds a test plan — not for what the code should do, but for what it currently does. These are characterization tests. The agent writes tests that assert current behavior: "When you call calculateTotal with these inputs, it returns this value." It runs the tests against the live code to verify they pass. The point isn't to validate correctness — it's to create a safety net so you'll know immediately if future changes break existing behavior.

Inputs: directory (string, optional — defaults to project root)
Outputs: characterization-tests (test files asserting current behavior), coverage-report (summary of behavior captured)
YAML: commands/intake/capture-behavior.yaml
Next: intake:create-system-description

Step 3: `intake:create-system-description` Copy Section

This is the capstone of onboarding. The agent launches parallel analysis — one thread maps the architecture (services, databases, queues), another catalogs the API surface area, another traces security patterns (auth, encryption, access controls), and another maps external dependencies. The output is a SOC2-style living document at docs/system-description.md. It reads like a system overview you'd hand to an auditor or a new senior engineer: what the system does, how data flows through it, what's exposed externally, how it's deployed, what third-party services it depends on. This document becomes the shared context for everything that follows.

Inputs: directory (string, optional — defaults to project root)
Outputs: system-description (file at docs/system-description.md — SOC2-style living document)
YAML: commands/intake/create-system-description.yaml
Next: Feature definition with feature-forge

After intake, you have: documented code, behavioral tests, and a system description. This is a one-time cost. You don't run intake again.

Interlude: Common Ground (On Demand) Copy Chapter

At any point — now, or later during planning, or mid-execution — you can run /common-ground. It surfaces assumptions the agent is making about your project: "I assume you're using PostgreSQL for the primary datastore." "I assume the API uses JWT authentication." You confirm, correct, or flag unknowns. This runs whenever you feel assumptions are building up. There's no prescribed moment; you use judgment.

Inputs: --list (flag, read-only view), --check (flag, quick validation), --graph (flag, mermaid diagram)
Outputs: ground-file (COMMON-GROUND.md with assumptions by confidence tier), ground-index (ground.index.json for programmatic access)
YAML: commands/common-ground.yaml
Next: On demand — no prescribed next step

Act 2: Product Discovery (Human-Driven, Parallel to Intake) Copy Chapter

While intake is happening on the technical side, the product side is doing its own work. This part is primarily human — the agent assists but doesn't drive.

Identify Value Propositions Copy Section

A product person, founder, or stakeholder defines the value propositions. For example, a SaaS product might have:

• VP1: Save time for primary users
• VP2: Monetize through a secondary audience
• VP3: Expand to adjacent market segments
• VP4: Drive growth through network effects

Each VP has a customer segment, a value statement, and a feature set. This work happens in markdown files, Obsidian, Notion, whiteboards, interviews — whatever the team uses. The agent doesn't own this phase, but it can help structure notes.

Identify Feature Set Copy Section

For each value proposition, the team identifies concrete features: User Dashboard, Notification System, Billing Integration, Admin Panel. These get written up as feature descriptions — brief enough to understand the intent, detailed enough to know the scope.

Act 3: Feature Definition (Per Feature) Copy Chapter

Feature Forge (Skill, not a slash command) Copy Section

For each identified feature, you invoke feature-forge. It reads the system description first — so it already knows your architecture, your API patterns, your database schema, your auth model. It doesn't ask you questions it can answer from the system description.

Then it runs a structured interview: PM perspective ("Who uses this? What's the core value?") and Dev perspective ("What existing components does this touch? What's the data model?"). It asks one question at a time, using multiple-choice where possible to reduce cognitive load.

Throughout the interview, every question about proposed functionality includes a standing option: "Needs additional discovery." If you don't have the data to answer a question — maybe you need user interviews, competitive analysis, or a technical spike — you select this option. Feature-forge records it, skips the question, and moves on. You're never blocked by unknowns during the interview.

The output is specs/{feature-name}.spec.md — a specification with:

• Functional requirements (optionally in EARS format for complex features, simpler format for straightforward ones)
• Non-functional requirements
• Acceptance criteria (Given/When/Then)
• Error handling table
• High-level implementation TODOs (intentionally not detailed — that's the planning phase's job)
• A workflow integration section noting the target epic and pointing to /planning:impl-plan for detailed steps
• If any questions were flagged: a Discovery Recommendation section listing the specific unknowns

If unknowns were flagged, feature-forge presents a choice: run discovery now (recommended), skip to planning with unknowns flagged as risks, or handle research separately and run discovery:create later. If nothing was flagged, no recommendation appears — you go straight to planning or move on to the next feature.

You repeat this for every feature in the release.

Act 4: Discovery (Optional — When Research Is Needed) Copy Chapter

Not every feature needs this. If the feature-forge spec is sufficient — no unknowns were flagged during the interview — you skip straight to Planning. But some features have open questions that need human research: user interviews, competitive analysis, technical spikes, design exploration. You'll know because feature-forge told you — every question you answered with "Needs additional discovery" is now listed in the spec's Discovery Recommendation section.

Step 4: `discovery:create` Copy Section

You give it a topic — not a Jira epic key, just a topic. "User onboarding flow" or "Payment integration options." You point it at whatever sources you have: the feature-forge spec, meeting notes, domain research markdown files, PDFs, URLs. It creates a structured discovery workspace with research questions, hypotheses, unknowns, domain context, and stakeholder inputs. The workspace lives locally (or in your configured doc system).

Inputs: topic (string), sources (file[], optional — markdown, PDFs, URLs, meeting notes, feature-forge specs)
Outputs: discovery workspace (directory at docs/discovery/{topic}/)
YAML: commands/project/discovery/create.yaml
Next: Human research phase, then discovery:synthesize

Human Research Phase Copy Section

This is the gap where humans do the work. Conduct user interviews. Run a design sprint. Build a proof of concept. Do competitive analysis. Fill out the business model canvas. The discovery workspace gives structure to what you're investigating, but the research itself is human labor.

Step 5: `discovery:synthesize` Copy Section

After research is done, you point the agent at all your artifacts — the discovery workspace, interview transcripts, research notes, spike results, meeting notes. It consolidates everything into actionable recommendations. The key output: proposed epics AND tickets. Not just tickets — full epic structures aligned with value propositions. "Based on the research, here are 3 epics with 14 total tickets across them."

Inputs: discovery workspace refs, local docs, research artifacts (file[])
Outputs: synthesis document (consolidated findings + proposed epic/ticket structure)
YAML: commands/project/discovery/synthesize.yaml
Next: discovery:approve

Step 6: `discovery:approve` Copy Section

You review the synthesis. The agent presents any blocking decisions that need resolving ("Should we use Stripe or build custom payment processing?"). You resolve them.

Then it checks whether the proposed epics exist in your ticketing system. If they don't — and this is the fix for issue #103 — it offers options: auto-create the epics, map to existing ones, skip, or cancel. You choose. It creates the epics first, then creates tickets linked to those epics. All of this works against whatever backend you configured — Jira, GitHub Issues, or local markdown files.

Inputs: synthesis document ref, decisions (optional — pre-resolved blocking decisions)
Outputs: created epics + tickets (in configured ticketing backend)
YAML: commands/project/discovery/approve.yaml
Next: planning:epic-plan

After discovery, you have: epics and tickets in your ticketing system, grounded in research and aligned with value propositions.

Act 5: Planning Copy Chapter

Step 7: `planning:epic-plan` Copy Section

You point it at an epic. The agent reads the feature-forge spec (if one exists) so it doesn't re-derive requirements. It fetches all linked tickets, then launches parallel agents to explore the codebase — one finds affected files, another discovers API patterns, another maps component patterns, another locates test conventions, another finds reference implementations.

The output is a stakeholder-readable overview document: purpose, goals, requirements summary, technical change overview with a risk assessment (7-dimension scoring), impact analysis, testing strategy, acceptance criteria. This is the document you share with your tech lead, your PM, your architect. It's meant to be read by humans making decisions, not by agents executing code.

Inputs: epic key (string), feature spec (auto-detected from specs/{feature_name}.spec.md)
Outputs: overview document (stakeholder-readable plan with requirements, risk assessment, testing strategy)
YAML: commands/project/planning/epic-plan.yaml
Next: planning:impl-plan

Step 8: `planning:impl-plan` Copy Section

This is where the overview becomes executable. The agent takes the overview document and turns it into a coordination plan: topologically sorted execution order, parallel execution waves (which tickets can be worked simultaneously), and — the enhancement — skill-aware ticket descriptions.

For each ticket, it reads what skills are available in the project and crafts the ticket description to invoke the right one. A React component ticket gets a description that references react-expert. A test suite ticket references test-master. A database migration ticket references database-optimizer. Each ticket becomes self-contained: implementation steps with file paths and code snippets, files to modify, complete test code, acceptance criteria checklist.

Inputs: overview document ref (from planning:epic-plan)
Outputs: implementation plan (execution order + parallel waves), updated tickets (self-contained with skill-aware descriptions)
YAML: commands/project/planning/impl-plan.yaml
Next: execution:execute-ticket

After planning, you have: a stakeholder overview, a coordination plan, and self-contained tickets that any developer (or agent) can pick up and execute independently.

Act 6: Execution (Per Ticket, Repeated) Copy Chapter

This is where code gets written. The split between execute and complete exists for a practical reason — implementations can be long, conversations may need compacting, and the completion phase was being dropped when bundled with execution.

Step 9: `execution:execute-ticket` (repeated per ticket) Copy Section

You give it a ticket key. The agent fetches the ticket, reads the self-contained implementation details, and starts coding. It follows the implementation steps, writes the code changes, creates the tests, runs them, verifies acceptance criteria. If it encounters deviations from the plan, it flags them at a checkpoint. When done, it presents a completion summary: what changed, what tests were added, what was different from the plan.

Inputs: ticket key (string)
Outputs: completion summary (changes made, files modified, tests added, deviations from plan)
YAML: commands/project/execution/execute-ticket.yaml
Next: execution:complete-ticket

Step 10: `execution:complete-ticket` (repeated per ticket) Copy Section

After execution, you run completion as a separate command. It transitions the ticket status (In Progress → In Review), updates the implementation plan's status tables (completion status, execution order, parallel wave tracking), and records the details of what was actually implemented.

Then the incremental system description update: if the changes affect APIs, external dependencies, security patterns, or data models, the agent proposes specific updates to docs/system-description.md. "This ticket added a new /api/v2/teams endpoint — I'll update the API Surface Area section." Checkpoint approval, then it applies the update. This keeps the system description accurate as the codebase evolves, without requiring a big-bang documentation effort.

Inputs: ticket key (string, optional if context available from prior execute-ticket)
Outputs: transitioned ticket (status → "In Review"), updated implementation plan, updated system description (if applicable)
YAML: commands/project/execution/complete-ticket.yaml
Next: Next ticket (execution:execute-ticket) or retrospectives:complete-epic when all tickets done

You repeat steps 9-10 for every ticket in the epic. Parallel waves mean multiple developers/agents can work tickets simultaneously.

Act 7: Retrospective Copy Chapter

Step 11: `retrospectives:complete-epic` Copy Section

All tickets are done. You run this on the epic. The agent verifies all tickets are complete (blocks if any aren't), then generates a comprehensive completion report: what was built, what deviated from the plan, what patterns emerged, what was learned, quality assessment. It moves documentation from the "in progress" location to the "complete" location in your doc system. It closes the epic in the ticketing system.

Finally, it does a full system description review — not just incremental updates, but a holistic check. Did the architecture change? Do the mermaid diagrams still reflect reality? Are there new external dependencies that weren't captured ticket-by-ticket? Checkpoint approval, then it updates the system description to reflect the post-epic state of the system.

Inputs: epic key (string)
Outputs: completion report (deliverables, quality metrics, lessons learned), closed epic, updated system description (holistic post-epic review)
YAML: commands/project/retrospectives/complete-epic.yaml
Next: Next feature cycle — feature-forge reads updated system description

The system description is now current. The next feature-forge invocation will read the updated system description, and the cycle begins again.

The Full DAG at a Glance Copy Chapter

INTAKE (once)           PRODUCT DISCOVERY (human, parallel)
  |                       |
  system-description      value props -> features
  |                       |
  +--------------- feature-forge (per feature) ---------------+
  |                       |                                    |
  |                 discovery (optional, when research         |
  |                   needed, human + agent)                   |
  |                       |                                    |
  |                 approve -> epics + tickets                 |
  |                       |                                    |
  +--------------- planning (epic-plan + impl-plan) ----------+
                          |
                    execution (execute + complete x N)
                          |
                    retrospective (complete-epic)
                          |
                    system description updated
                          |
                    next feature -> feature-forge reads updated state

The cycle is self-reinforcing: each completed feature makes the system description more accurate, which makes the next feature-forge session more informed, which makes the next planning phase more precise.

V0.5.0 Plan (`docs/v0.5.0-plan.md`) Copy Section

v0.5.0 Plan: Workflow Overhaul

Scope Copy Chapter

Decouple workflow commands from Jira/Confluence, add per-project backend configuration, create a project intake phase, rework discovery for product-centric workflows, integrate feature-forge into the pipeline, and fix the epic creation gap.

What's in v0.5.0:

• Backend adapter pattern — per-project config for ticketing (local/Jira/GitHub Issues) and documentation (local/Confluence/GitHub Wiki)
• Namespace change — project:phase:action becomes phase:action
• 11 commands (3 new intake, 7 reworked, 1 removed)
• Discovery rework — topic-based, local-first, produces epics AND tickets (#103 fix)
• Feature-forge integration — system description context, discovery recommendation, skill-aware tickets
• Intake commands — document-codebase, capture-behavior, create-system-description
• Directory restructure — commands/project/ flattened to commands/
• YAML workflow definitions and DAG manifest (Phase 1 — completed)

What's deferred:

• v0.6.0: Global-to-local config migration (Discussion #112), per-project skill activation, #50-55 (context persistence, state validation, error recovery, shared templates, testing infra)
• v0.7.0+: Enhanced skill routing (#64-72, feasibility evaluation pending), common-ground improvements (#108-111), optimal common-ground invocation points within new workflow
• #65/#66/#69/#68 moved to v0.7.0 (skill content work, dependency mapping)

Links:

• Narrative walkthrough: docs/v0.5.0-narrative.md
• YAML schema: docs/workflow/workflow-definition-schema.md
• Workflow manifest: commands/workflow-manifest.yaml

Architecture Decisions Copy Chapter

Backend Adapter Pattern Copy Section

Every command gains a Phase 0 config resolution step that loads backend-specific reference files:

.claude/workflow-config.json (in consumer project)
    ├── ticketing: "local" | "jira" | "github-issues"
    └── documentation: "local" | "confluence" | "github-wiki"

Command Phase 0:
  1. Read .claude/workflow-config.json (default: local/local)
  2. Load references/ticketing-{backend}.md
  3. Load references/docs-{backend}.md
  4. Proceed with abstract operations

All commands replace hardcoded Jira/Confluence operations with abstract verbs ("create ticket", "publish document") and a routing table to backend-specific reference files.

Namespace Change Copy Section

Drop the project: prefix. Use phase:action format:

Command Count: 11 Copy Section

• 3 new (intake)
• 1 removed (complete-sprint — retros at epic level only)
• 7 existing (reworked)

Discovery Rework: Topic-Based, Not Jira-Epic-Based Copy Section

Discovery starts from a topic (value proposition, feature area, research question), not a pre-existing Jira epic. It PRODUCES epics and tickets, fixing the epic creation gap (#103). Local-first input: markdown files, PDFs, URLs, meeting notes, feature-forge specs.

Feature-Forge Discovery Integration Copy Section

During the structured interview, every AskUserQuestions prompt includes a standing option: "Needs additional discovery." Flagged unknowns are collected and surfaced as a discovery recommendation at interview end, with options to run discovery, skip to planning, or handle research separately.

Skill-Aware Ticket Generation Copy Section

Both planning commands (planning:epic-plan and planning:impl-plan) read installed skills from the consumer project (.claude-plugin/plugin.json or local skill manifests) and use prompt engineering techniques to craft ticket descriptions that explicitly instruct agents to invoke the correct skill per implementation step. Example: a React component ticket embeds "Invoke react-expert for component implementation" in its description. This leverages the per-repo skill installation model — planning has full visibility into what skills are available and generates tickets that are skill-aware from the start.

Workflow DAG Copy Chapter

Different people may own different phases. The workflow is a DAG, not a strict sequence.

/* Detailed source-code truncated for AI context efficiency. */

Key relationships:

• Intake and Product Discovery run in parallel (independent)
• Feature-forge specs features BEFORE discovery commands run
• Discovery is optional — skip if feature spec is sufficient, use when unknowns need human research
• Discovery creates epics (not consumes them) — this is the #103 fix
• Common-ground runs on demand (future hooks per #111)

Implementation Chunks Copy Chapter

Pre: YAML Workflow Definitions (COMPLETED) Copy Section

Phase: 0 | Status: Done

YAML schema, per-command definition files, DAG manifest, and phase documentation created as part of the v0.5.0 roadmap consolidation spec.

Deliverables:

• docs/workflow/workflow-definition-schema.md — YAML schema documentation
• commands/workflow-manifest.yaml — Phase DAG and per-phase ordering
• 12 per-command YAML definitions (see YAML Definitions below)
• 18 phase/command overview docs under docs/workflow/

GitHub Issues: Part of roadmap consolidation spec

Chunk 1: Backend Adapter Foundation Copy Section

Phase: 1 | Depends on: Nothing | GitHub Issues: #62 (core workflow generalization)

Files to Create

Script Fix

File: scripts/update-docs.py (line 84-89)

count_workflows() uses rglob("*.md") which would count reference files. Fix to exclude references/ subdirectories:

def count_workflows(base_path: Path) -> int:
    """Count workflow command markdown files."""
    commands_dir = base_path / COMMANDS_DIR
    if not commands_dir.exists():
        return 0
    return sum(1 for f in commands_dir.rglob("*.md") if "references" not in f.parts)

Verification

python scripts/update-docs.py --check
# Should still report 9 workflows (refs not counted)

Chunk 2: Decouple Non-Discovery Commands Copy Section

Phase: 2 (partial) | Depends on: Chunk 1 | GitHub Issues: #62, #54, #55

Commands to Decouple

Each command gets:

1. Phase 0 — Config resolution step (load backend refs)
2. Abstract operations — All Jira/Confluence verbs replaced with generic verbs
3. Routing table — Footer section pointing to backend-specific reference files

Testing Integration (#54, #55)

The following sections are added during the Chunk 2 rewrite — not as a separate chunk:

planning:epic-plan — add to Testing Strategy section:

• Performance baselines (p95 response time, page load, query time)
• Performance SLAs (targets per metric)
• Performance testing triggers (DB changes, API changes, large data, latency-sensitive features)
• Security testing triggers (auth changes, PII handling, API changes, permissions)
• Regression impact analysis (existing features at risk, affected flows, existing tests)

planning:impl-plan — add per-ticket:

• Performance test requirements (benchmarks, load tests, query performance targets)
• Regression test requirements (existing tests to run, new tests to add, critical paths)
• Security test flag (when ticket touches auth, input validation, file uploads, encryption)

retrospectives:complete-epic — add metrics sections:

• Performance metrics (API p50/p95/p99, slow queries, regressions, load test results)
• Security metrics (vulnerabilities found by severity, remediated count, reviews conducted)
• Regression metrics (suite size, pass rate, regressions caught pre-prod vs escaped, flaky test count)

Note: Security and performance checks during execution are handled by the adversarial review phase (Layer 3 — /review-ticket and /qa-validate), not by modifying execute-ticket or complete-ticket. Automated CI execution of regression suites is a consumer-project CI concern, not a skill library concern.

Verification

# No hardcoded Jira/Confluence refs outside routing tables
grep -r "Jira\|Confluence\|JQL" commands/project/planning/ commands/project/execution/ commands/project/retrospectives/
# Should only appear in routing table comments, not in operational steps

Chunk 3: Discovery Rework Copy Section

Phase: 2+3 (merged) | Depends on: Chunk 1 | GitHub Issues: #62, #103

Merges Phase 2 decoupling with Phase 3 rework — no point abstracting refs in files getting fully rewritten.

3.1 `create-epic-discovery.md` → topic-based discovery

YAML Definition: commands/project/discovery/create.yaml

Current: Takes a Jira epic key, fetches epic details, creates Confluence discovery page.

New: Takes a topic (value proposition, feature area, research question). Accepts local sources: markdown files, PDFs, URLs, meeting notes, feature-forge specs. Creates a structured discovery workspace (local or in doc system) with research questions, hypotheses, unknowns, domain context, stakeholder inputs. Does NOT require pre-existing ticketing artifacts.

3.2 `synthesize-discovery.md` → local-first synthesis

YAML Definition: commands/project/discovery/synthesize.yaml

Current: Takes Confluence URLs as input, publishes synthesis to Confluence.

New: Takes discovery workspace refs, local docs, research artifacts (not just Confluence URLs). Consolidates findings into actionable recommendations. Proposes epics AND tickets (not just tickets) with metadata. Output includes proposed epic structure aligned with value propositions.

3.3 `approve-synthesis.md` → epic creation fix (#103)

YAML Definition: commands/project/discovery/approve.yaml

Current: Assumes target epics exist in Jira. Creates tickets linked to existing epics.

New: Creates EPICS first, then tickets linked to epics. Adds Phase 1.5: Epic Verification & Creation:

• A) Auto-create — present epic details for approval, create in batch, record ID mappings
• B) Map to existing — query candidates, let user map proposed → existing epics
• C) Skip — proceed without epic links (warning)
• D) Cancel — abort for manual fix

Error handling with rollback on batch failure. Works with any configured ticketing backend.

Verification

# No hardcoded Jira/Confluence refs outside routing tables
grep -r "Jira\|Confluence\|JQL" commands/project/discovery/
# approve-synthesis.md contains Phase 1.5 epic creation flow
grep -c "Epic Verification" commands/project/discovery/approve-synthesis.md

Chunk 4: Intake Commands Copy Section

Phase: 4 | Depends on: Chunk 1 | GitHub Issues: New issue required (intake commands)

Independent of Chunks 2 and 3 — only needs Chunk 1.

4.1 `commands/intake/document-codebase.md` (~250 lines)

YAML Definition: commands/intake/document-codebase.yaml

description: Use when onboarding a new project to add documentation to existing code
argument-hint: [--scope=<path>] [--format=<jsdoc|docstring|xml>]

Workflow: Scan codebase → identify undocumented functions/classes/modules → prioritize (public APIs first) → checkpoint approval → generate docstrings → output summary → pointer to capture-behavior

4.2 `commands/intake/capture-behavior.md` (~250 lines)

YAML Definition: commands/intake/capture-behavior.yaml

description: Use when capturing existing system behavior through tests for an undocumented codebase
argument-hint: [--scope=<path>] [--type=<unit|integration|both>]

Workflow: Scan code → identify untested behavior → analyze coverage gaps → checkpoint test plan → generate characterization tests (assert CURRENT behavior) → run tests → output summary → pointer to create-system-description

4.3 `commands/intake/create-system-description.md` (~300 lines)

YAML Definition: commands/intake/create-system-description.yaml

description: Use when creating a living system description document for a project
argument-hint: [--output=<path>]

Workflow: Parallel agent analysis (architecture, security, API, data) → generate SOC2-style document:

• System Purpose & Scope
• System Components (services, databases, queues, caches)
• Data Flow Diagram (mermaid)
• Security Architecture
• API Surface Area
• External Dependencies
• Infrastructure Overview
• Change Management Process

Output: docs/system-description.md (configurable path)

4.4 Reference Files

Verification

# All files have valid frontmatter
head -5 commands/intake/*.md
# Reference files within 100-600 line range
wc -l commands/intake/references/*.md

Chunk 5: Feature-Forge Integration Copy Section

Phase: 5 | Depends on: Chunks 2, 3, and 4 | GitHub Issues: New issue required (feature-forge integration)

5.1 Feature-Forge: System Description Context

File: skills/feature-forge/SKILL.md

Add Step 0 to Core Workflow:

0. Context — Check for docs/system-description.md (or path from config). If found, load as background context. Reference existing components/APIs during interviews. Skip questions the system description already answers.

5.2 Feature-Forge: Output Boundaries

File: skills/feature-forge/references/specification-template.md

• Add ## Workflow Integration section with epic target field
• Explicit note: "High-level TODOs only. Detailed implementation steps generated by /planning:impl-plan."
• Make EARS format optional — offer for complex features, simpler format for straightforward ones

5.3 Feature-Forge: Discovery Integration

File: skills/feature-forge/SKILL.md

During the structured interview, every AskUserQuestions prompt about proposed functionality includes a standing option: "Needs additional discovery." When selected, feature-forge records the question topic as a flagged unknown and moves to the next question without blocking.

At interview end, if any unknowns were flagged:

1. Adds ## Discovery Recommendation section to spec listing unknowns with original question context
2. Presents AskUserQuestions prompt:
   • A) Run discovery (Recommended) — create discovery workspace for flagged unknowns
   • B) Skip to planning — proceed with unknowns flagged as risks
   • C) Handle research separately — run discovery:create later

If no unknowns flagged, no recommendation shown.

5.4 System Context Reference

New file: skills/feature-forge/references/system-context-integration.md (~150 lines)

• How to use system description sections during requirements gathering
• Which sections inform which interview questions
• How specs should reference system components
• How flagged unknowns map to discovery workspace research questions

5.5 Planning Commands: Read Feature Specs + Skill-Aware Ticket Creation

File: commands/project/planning/create-epic-plan.md
YAML Definition: commands/project/planning/epic-plan.yaml

Add to Phase 0:

Check for specs/{feature_name}.spec.md related to this epic. If found, use requirements, acceptance criteria, and NFRs as input. Do not re-derive what the spec already defines.

File: commands/project/planning/create-implementation-plan.md
YAML Definition: commands/project/planning/impl-plan.yaml

When generating self-contained ticket descriptions, read available skills at the project level (.claude-plugin/plugin.json or installed skill manifests) and craft prompts that invoke the correct skill per implementation step.

Example ticket description:

Suggested skill: react-expert for component implementation, test-master for test suite

This is core to the v0.5.0 vision: planning has full visibility into what skills are available in the consumer project and generates tickets that are skill-aware from the start. Each ticket becomes self-contained with the right skill invocation embedded in its description.

5.6 System Description Updates on Completion

File: commands/project/execution/complete-ticket.md — Add Step 4c:
YAML Definition: commands/project/execution/complete-ticket.yaml

If changes affect APIs, external deps, security, or data models → propose targeted updates to docs/system-description.md → checkpoint approval → apply.

File: commands/project/retrospectives/complete-epic.md — Add to Phase 5:
YAML Definition: commands/project/retrospectives/complete-epic.yaml

Review all changes across the epic. Update system description holistically. Update mermaid diagrams if architecture changed. Checkpoint approval.

Verification

python scripts/validate-skills.py --skill feature-forge
# Verify discovery integration
grep -c "additional discovery" skills/feature-forge/SKILL.md
# Verify spec reading in planning
grep -c "spec.md" commands/project/planning/create-epic-plan.md

Chunk 6: Directory Restructure + Cleanup Copy Section

Phase: 6 | Depends on: Chunks 1-5 (all content finalized) | GitHub Issues: New issue required (namespace change + directory restructure)

Directory Moves

File Renames

Deletions

Script Update

File: scripts/update-docs.py

COMMANDS_DIR = "commands"  # was "commands/project"

def count_workflows(base_path: Path) -> int:
    """Count workflow command markdown files."""
    commands_dir = base_path / COMMANDS_DIR
    if not commands_dir.exists():
        return 0
    return sum(
        1 for f in commands_dir.rglob("*.md")
        if "references" not in f.parts and "common-ground" not in f.parts
    )

Verification

# Old directory should be empty/gone
ls commands/project/ 2>&1
# Should show: No such file or directory

# Workflow count should be 11
python scripts/update-docs.py --dry-run

# No dangling references to old paths
grep -r "commands/project" commands/ scripts/ .claude-plugin/

# No references to complete-sprint
grep -r "complete-sprint" commands/ docs/ README.md

Chunk 7: Documentation + Validation Copy Section

Phase: 7+8 | Depends on: Chunk 6 | GitHub Issues: New issue required (narrative document restructure)

Documentation Updates

Validation Suite

# 1. Skill validation
python scripts/validate-skills.py

# 2. Doc counts in sync (should show 11 workflows)
python scripts/update-docs.py --check

# 3. No hardcoded Jira/Confluence refs in command files
grep -r "Jira\|Confluence\|JQL\|Atlassian" \
  commands/discovery/ commands/planning/ commands/execution/ \
  commands/retrospectives/ commands/intake/
# Should return nothing (only allowed in commands/references/)

# 4. All new files have valid frontmatter
python scripts/validate-skills.py

# 5. Reference files within 100-600 line range
find commands/ -path "*/references/*.md" -exec wc -l {} \;

# 6. No dangling references to deleted file
grep -r "complete-sprint" commands/ docs/ README.md SKILLS_GUIDE.md

# 7. Propagate final counts
python scripts/update-docs.py

# 8. Regenerate social preview
node ./assets/capture-screenshot.js

File Manifest Copy Chapter

New Files (15 files, ~2,970 lines) Copy Section

Renamed/Moved Files (Phase 6 restructure) Copy Section

Deleted Files Copy Section

Modified Files (updated to reflect Phase 1 completion) Copy Section

YAML Definitions Copy Chapter

All 12 per-command YAML definition files created in Phase 1 (completed):

GitHub Issues Copy Chapter

v0.5.0 (Workflow Overhaul) Copy Section

Deferred to v0.6.0 (Global-to-Local Config Migration) Copy Section

Deferred to v0.7.0+ (Enhanced Skill Routing + Common-Ground) Copy Section

Resolved Decisions Copy Chapter

• Epic terminology — Evaluated alternatives (initiative, feature, workstream, deliverable, milestone). Decision: keep "epic." It's the least ambiguous term across all three backends (Jira uses it natively, GitHub Issues maps milestones to it, local markdown uses folder labels). The adapter layer abstracts backend-specific mapping.
• Discovery trigger — Feature-forge embeds "Needs additional discovery" as a standing option during its structured interview. Flagged unknowns are collected and surfaced as a discovery recommendation at interview end, with options to run discovery, skip to planning, or handle research separately.
• EARS format optional — Made optional in feature-forge; offer EARS for complex features with conditional/state-dependent behavior; simpler formats for straightforward features.
• Non-standard frontmatter fields tolerated — Confirmed via npx skills add . --list: all 65 skills detected despite non-standard top-level fields (triggers, role, scope, output-format). Migration to metadata.* is optional tech debt.
• #50-55 → v0.6.0 — These depend on global-to-local config migration (Discussion #112). Context persistence, state validation, error recovery, shared templates, and testing infra are all easier to implement with per-project config.
• #69 metadata enhancement must use metadata field — Any NEW metadata must go under the spec's metadata key, not as new top-level frontmatter fields. Existing non-standard fields are grandfathered.
• CI portability check via npx skills — GitHub Action to catch regressions in ecosystem detection. Asserts skill count matches version.json.

Open Questions Copy Chapter

• Common-ground hooks (#111, #107) — on-demand for now; hook-based injection in future
• Docusaurus setup — per-project CI/CD concern; add setup instructions in local-docs-structure.md but don't implement deployment in this version
• EARS format monitoring — made optional in feature-forge; monitor whether structured vs. simple format affects agent execution quality
• Tiki integration — potential future adapter for the ticketing backend (Go CLI for local task management)

Implementation Summary Copy Chapter

Dependency Graph Copy Section

Chunk Pre (YAML definitions) ✓
    │
Chunk 1 (foundation)
├──→ Chunk 2 (decouple non-discovery)──┐
├──→ Chunk 3 (discovery rework)────────┼──→ Chunk 5 (feature-forge)──→ Chunk 6 (restructure)──→ Chunk 7 (docs)
└──→ Chunk 4 (intake)──────────────────┘

Chunks 2, 3, and 4 are independent of each other — only Chunk 1 gates them. They can run in parallel if desired.

Ideas Audit Primary Docs (`docs/ideas/audit-primary-docs.md`) Copy Section

Documentation Audit: Primary User-Facing Files

Audit date: 2026-02-02
Auditor: Technical writing agent (Claude Opus 4.5)
Scope: README.md, SKILLS_GUIDE.md, QUICKSTART.md, CONTRIBUTING.md
Supporting context: docs/COMMON_GROUND.md, docs/WORKFLOW_COMMANDS.md, CHANGELOG.md, docs/ideas/documentation-site.md

Executive Summary Copy Chapter

The four primary documents serve different audiences but suffer from significant content overlap, inconsistent naming conventions, and a structural problem: README.md tries to be both a landing page and a comprehensive reference. SKILLS_GUIDE.md is the strongest standalone document. QUICKSTART.md and CONTRIBUTING.md both contain stale installation instructions that diverge from the README. The biggest single improvement would be thinning the README to a focused landing page and letting specialized documents own their respective topics.

Per-File Findings Copy Chapter

1. README.md Copy Section

Purpose: Project landing page and primary discovery surface (GitHub, search engines, LLM retrieval).

Strengths:

• Strong visual presentation with badges, animated header, star history
• Clear "Quick Start" section at the top with copy-paste install command
• Well-structured project tree showing directory layout
• Good use of the Documentation section as a hub linking to specialized docs
• Tech Stack Coverage section serves as an effective keyword surface for search/discovery

Weaknesses:

1. Tries to be everything. At 438 lines, the README functions as landing page, architecture guide, skills catalog, installation manual, usage tutorial, contributing guide, and marketing page. No single audience can scan it efficiently. A first-time visitor looking for "how do I install this" must scroll past architecture diagrams and 65-skill category lists.

2. Duplicate installation instructions. Three installation options appear in the "Quick Start" section at the top AND again in "Installation Options" at line 305. These two sections use different option numbering (the Installation Options section has two entries both labeled "Option 2"), different ordering, and different levels of detail.

3. Skills Overview duplicates SKILLS_GUIDE.md. Lines 116-133 reproduce a condensed version of the skill catalog that also lives in SKILLS_GUIDE.md. When skills are added or recategorized, both must be updated. Neither is clearly the source of truth.

4. Context Engineering section duplicates docs/COMMON_GROUND.md. Lines 182-227 reproduce the overview, command examples, confidence tiers, and mermaid graph that all exist in greater detail in docs/COMMON_GROUND.md. This section is 45 lines of content that could be 5 lines and a link.

5. Project Workflow Commands section duplicates docs/WORKFLOW_COMMANDS.md. Lines 229-242 duplicate the phase table from the workflow docs. The README should link, not reproduce.

6. Contributing section duplicates CONTRIBUTING.md. Lines 362-401 contain a condensed "Adding a New Skill" guide that partially overlaps with CONTRIBUTING.md but uses different line-count guidance (200-400 lines per reference here vs. no specific range in CONTRIBUTING.md). The frontmatter example in the README uses name: My Skill (with spaces), while CONTRIBUTING.md uses a different description formula. CLAUDE.md says names must be "letters, numbers, and hyphens only."

7. Stale option numbering. Under "Installation Options," there are two sections both labeled "Option 2" (npx add-skill and Local Development). Option 3 (Direct Installation) should logically be Option 4, or the npx method should be Option 2 and Local Development should be Option 3.

8. Tech Stack Coverage is a wall of text. Lines 244-297 list every supported technology in a flat bullet list. This is useful for SEO keyword density on GitHub but provides no navigational value. A reader cannot determine which skill covers which technology from this list alone.

Recommendations:

• Thin the README to under 200 lines: hero, one-line description, single install command, 3-sentence "what is this," link hub to specialized docs, contributing CTA, license/support
• Move architecture details to a dedicated docs/ARCHITECTURE.md or let the future docs site own it
• Remove the inline skills catalog; replace with a single sentence and link to SKILLS_GUIDE.md
• Remove the inline Context Engineering section; replace with a 2-line summary and link to docs/COMMON_GROUND.md
• Remove the inline Workflow Commands section; link to docs/WORKFLOW_COMMANDS.md
• Remove the inline Contributing guide; link to CONTRIBUTING.md
• Fix the duplicate "Option 2" numbering immediately (this is a bug regardless of restructuring)
• Consider moving Tech Stack Coverage to SKILLS_GUIDE.md where it provides navigational context

2. SKILLS_GUIDE.md Copy Section

Purpose: Quick reference for which skill to use when.

Strengths:

• Clear, scannable structure with consistent formatting throughout
• Decision trees are genuinely useful -- they answer the question "I have X problem, which skill do I use?"
• Skill Combinations section provides practical multi-skill workflow patterns
• Examples section with "Good Prompts" gives concrete, actionable guidance
• No unnecessary preamble; gets straight to content
• The flattest, most reference-like document in the set -- appropriate for its purpose

Weaknesses:

1. No introduction or context. The document opens with ## When to Use Each Skill with no preamble explaining what this document is, who it is for, or how it relates to the rest of the project. A single paragraph at the top would help.

2. Category counts diverge from README. The README lists 12 categories; SKILLS_GUIDE.md lists 12 categories but with different groupings. For example, README has "Workflow (2): Debugging Wizard, Fullstack Guardian" as a category, while SKILLS_GUIDE.md has the same skills under a "Workflow" heading. This is consistent, but the README's parenthetical counts (e.g., "Languages (12)") are not replicated here, making cross-reference verification manual.

3. Examples section is excessively long. Lines 257-322 contain 50+ example prompts across 7 subsections. This is valuable content, but the sheer volume makes it hard to scan. The most common use cases (top 10) should be separated from the exhaustive list.

4. No link back to README or installation. A reader who lands here directly (via search, deep link, or LLM referral) has no way to learn how to install the plugin. A single line at the top with a link to the README or QUICKSTART.md would solve this.

5. "Tips for Effective Use" is generic. The 5 tips at line 249-255 are so general ("Be Specific," "Context Matters") that they add little value. They duplicate the more concrete best practices in QUICKSTART.md.

6. Missing: which skills are new or recently updated. For returning users, a "What's New" callout at the top referencing the latest release would help.

Recommendations:

• Add a 2-3 line introduction with a link to README.md and QUICKSTART.md
• Trim the Examples section: keep the top 16 "Good Prompts" and move the framework-specific, language-specific, and platform-specific examples into a collapsible section or separate file
• Remove or merge "Tips for Effective Use" into QUICKSTART.md where it belongs
• Consider adding a "Last updated: vX.Y.Z" line at the top so readers know if content is current

3. QUICKSTART.md Copy Section

Purpose: Get a new user from zero to working installation in minutes.

Strengths:

• Starts with installation immediately -- no preamble
• Three installation methods presented concisely
• "Test Your Installation" section is a strong inclusion -- gives the user a way to verify success
• "Quick Reference Card" at the bottom is a genuinely useful cheat sheet
• Reasonable length (208 lines)

Weaknesses:

1. Installation instructions diverge from README. QUICKSTART.md offers three methods: Marketplace, Install from GitHub (claude plugin install https://...), and Local Development (cp -r). README.md offers four methods: Marketplace, npx add-skill, Local Development, and Direct Installation. The "Install from GitHub" method in QUICKSTART.md (claude plugin install https://...) does not appear in the README at all. The npx method in the README does not appear in QUICKSTART.md. This is confusing and suggests neither document is the source of truth.

2. Skill counts may go stale. Lines 50-54 contain hardcoded counts ("12 Language Experts," "10 Backend Framework Experts," "7 Frontend & Mobile Experts"). These are not wrapped in `` markers and will not be updated by scripts/update-docs.py. The "10 Backend Framework Experts" claim conflicts with the README, which lists 7 in the "Backend Frameworks" category.

3. "First Steps" section mixes audiences. Subsections 1-4 cover what the plugin contains (reference), common use cases (tutorial), best practices (guidance), and skill activation examples (reference). This interleaving makes it hard to follow a linear getting-started path.

4. "Follow Recommended Workflows" duplicates SKILLS_GUIDE.md. The 7-step new feature workflow at lines 127-134 is identical to the "New Feature Development" workflow in SKILLS_GUIDE.md lines 96-104. One should link to the other.

5. References section at line 136-139 is incomplete. It lists README.md, SKILLS_GUIDE.md, and CONTRIBUTING.md, but omits docs/COMMON_GROUND.md and docs/WORKFLOW_COMMANDS.md.

6. Troubleshooting is thin. Only two scenarios are covered (skills not activating, need help). Common issues like "I installed but Claude does not seem to use the skills" or "how do I update to the latest version" are not addressed.

7. Closing tone is informal. "Happy coding!" with a rocket emoji is not consistent with the professional tone of the rest of the documentation set.

Recommendations:

• Consolidate installation instructions with the README. One document should be the canonical source; the other should link to it. Recommendation: QUICKSTART.md owns the detailed install instructions; README.md has a one-liner and a link.
• Fix the stale "10 Backend Framework Experts" count (should be 7 per README categories, or 8 if counting Express separately)
• Restructure "First Steps" into a linear flow: Install -> Verify -> Try your first prompt -> Learn more
• Remove the duplicated workflow; link to SKILLS_GUIDE.md
• Expand the Troubleshooting section with 2-3 more common scenarios
• Add "How to update" instructions
• Remove the closing emoji; end with the Support section

4. CONTRIBUTING.md Copy Section

Purpose: Guide contributors through the process of adding or modifying skills.

Strengths:

• Clear step-by-step contribution workflow (fork, branch, change, test, commit, PR)
• Commit message format is well-defined
• Progressive Disclosure Pattern section is thorough and well-explained
• Token Efficiency Guidelines are specific and actionable
• Code Examples Best Practices section sets a clear standard
• Framework Version Requirements table pins versions -- good for consistency

Weaknesses:

1. Frontmatter schema conflicts with CLAUDE.md. CONTRIBUTING.md line 88 shows name: Skill Name (with a space), but CLAUDE.md explicitly states: "name: Letters, numbers, and hyphens only (no parentheses or special characters)." The description formula on line 103 ([Role] for [Domain]. Invoke for [triggers]. Keywords: [terms].) conflicts with CLAUDE.md's mandate: "descriptions must be TRIGGER-ONLY" and "Format: Use when [specific triggering conditions]." These are not minor style differences; they will produce skills that fail validation.

2. Missing validation step. The contribution workflow (steps 1-6) does not mention running python scripts/validate-skills.py before submitting a PR. Given that CI runs this check, contributors will hit failures they could have caught locally. This should be step 4.5.

3. Reference file guidance is vague. The README says "200-400 lines each" for references. CLAUDE.md says "100-600 lines per reference file." CONTRIBUTING.md's Progressive Disclosure section says "200 lines" as a threshold for when to split, but does not state a target range. Three different documents give three different numbers.

4. Testing instructions are impractical. Step 4 says to cp -r skills/* ~/.claude/skills/ and restart Claude Code. For marketplace-installed plugins, this method may not work or may conflict with the installed version. No guidance is given for testing with the marketplace/local plugin workflow.

5. No mention of the commands/ directory. The guide covers skill creation in detail but says nothing about creating or modifying workflow commands. A contributor looking to add a command has no guidance.

6. Code of Conduct is minimal. Three short subsections (Be Respectful, Be Collaborative, Be Professional) with two bullet points each. This is fine for a small project but may need expansion as community grows. Consider linking to a standard CoC (e.g., Contributor Covenant) instead of maintaining a custom one.

7. "Recognition" section references a CONTRIBUTORS.md file. This file does not appear in the project structure shown in README.md. If it exists, it should be linked. If it does not exist, this is a broken promise.

Recommendations:

• Align the frontmatter schema with CLAUDE.md immediately. The description formula must say "Use when [triggering conditions]," not the [Role] for [Domain] pattern. The name field must show a hyphenated example.
• Add python scripts/validate-skills.py --skill my-new-skill as an explicit step before submitting a PR
• Standardize reference file line guidance across all documents (CLAUDE.md's 100-600 range is the most permissive; pick one range and use it everywhere)
• Add a section on contributing workflow commands
• Link or create the CONTRIBUTORS.md file
• Add a note about testing with the marketplace install method

Cross-File Redundancy Map Copy Chapter

The following content appears in multiple documents. For each topic, one document should be the single source of truth (SSoT); all others should link to it.

Key finding: 14 topics are duplicated across 2 or more files. Installation instructions appear in 3 files with different content in each. The skill activation examples appear in 3 files with varying levels of detail.

Proposed Restructuring for a Docs Site Copy Chapter

This mapping assumes the docs site structure proposed in docs/ideas/documentation-site.md and assigns each piece of current content to its future home.

Retain only:

• Hero banner and badges
• 3-sentence project description
• Single install command with link to full QUICKSTART.md
• Link hub: Quick Start, Skills Guide, Common Ground, Workflow Commands, Contributing
• License, Support, Author
• Star history / social proof

Everything else moves to dedicated pages.

/getting-started/ (from QUICKSTART.md) Copy Section

• All installation methods (single source of truth)
• Verification steps
• First prompt walkthrough
• Troubleshooting
• How to update

/skills/ (from SKILLS_GUIDE.md) Copy Section

• Skill index (filterable)
• Decision trees
• Skill combinations
• Example prompts (condensed)
• Tech stack coverage (integrated into skill cards)

/architecture/ (from README.md sections) Copy Section

• Progressive disclosure pattern explanation
• Project structure tree
• How skills activate (context-aware activation)

/workflows/ (from docs/WORKFLOW_COMMANDS.md) Copy Section

• Phase overview with DAG diagram
• Command reference table
• Per-command detail pages

/common-ground/ (from docs/COMMON_GROUND.md) Copy Section

• Existing content, mostly unchanged
• Remove background/origin story from main flow; move to a "Design Philosophy" subpage

/contributing/ (from CONTRIBUTING.md) Copy Section

• Fork/branch/test/PR workflow
• Skill writing guidelines (single source of truth for frontmatter schema)
• Reference file standards
• Validation and testing
• Add: command writing guidelines

Priority Ranking of Improvements Copy Chapter

Critical (Fix Now) Copy Section

1. Fix duplicate "Option 2" numbering in README.md Installation Options. This is a visible bug.

2. Align CONTRIBUTING.md frontmatter schema with CLAUDE.md. The description formula and name format directly conflict with the project's own CLAUDE.md. Contributors following CONTRIBUTING.md will produce skills that fail validation. Change the description formula to Use when [triggering conditions] and the name example to my-skill-name (hyphenated).

3. Fix stale count "10 Backend Framework Experts" in QUICKSTART.md. This contradicts the README (which says 7). Either wrap these counts in update markers or replace with a general statement.

High Priority (Next Release) Copy Section

4. Consolidate installation instructions. Designate QUICKSTART.md as the single source of truth. README.md gets a one-liner and a link. CONTRIBUTING.md links to QUICKSTART.md for testing setup. Remove the claude plugin install https://... method from QUICKSTART.md if it is not a supported path, or add it to the README if it is.

5. Remove duplicated sections from README.md. Replace inline Context Engineering, Workflow Commands, Skills Overview, and Contributing sections with 2-line summaries and links. Target: README under 200 lines.

6. Add validate-skills.py step to CONTRIBUTING.md. Insert between "Test Your Changes" and "Commit Your Changes."

7. Standardize reference file line guidance. Pick one range (recommend 100-600 from CLAUDE.md) and use it in README.md, CONTRIBUTING.md, and CLAUDE.md consistently.

Medium Priority (Docs Site Prep) Copy Section

8. Add introduction and navigation links to SKILLS_GUIDE.md. A 3-line preamble with links to README and QUICKSTART.

9. Trim SKILLS_GUIDE.md examples section. Keep top 16 general examples; move framework-specific and platform-specific examples to a separate section or file.

10. Expand QUICKSTART.md troubleshooting. Add "how to update," "skills conflict with local files," and "which installation method should I choose."

11. Add workflow command contribution guidance to CONTRIBUTING.md.

12. Restructure QUICKSTART.md "First Steps" into a linear tutorial flow.

Nice-to-Have (Future) Copy Section

13. Add "Last updated" or version reference to SKILLS_GUIDE.md and QUICKSTART.md.

14. Create or link CONTRIBUTORS.md referenced in CONTRIBUTING.md Recognition section.

15. Replace minimal Code of Conduct with Contributor Covenant link.

16. Move Tech Stack Coverage from README to SKILLS_GUIDE.md where it provides navigational context next to the decision trees.

17. Remove "Tips for Effective Use" from SKILLS_GUIDE.md (merge into QUICKSTART.md best practices).

18. Standardize tone across all documents. QUICKSTART.md ends with "Happy coding!" and uses emoji bullets in the Support section. Other documents maintain a more neutral professional tone. Pick one voice and apply it everywhere.

SEO Readiness Assessment Copy Chapter

Key SEO gaps:

• SKILLS_GUIDE.md has zero internal or external links. On a docs site, it would be an isolated page with no link equity flow.
• README.md has no text-based H1. The project name is embedded in an image. Search engines may not extract it.
• None of the documents have a meta-description-ready opening sentence that summarizes the page in under 160 characters.

Relationship to docs/ideas/documentation-site.md Copy Chapter

This audit directly satisfies Phase 1 of the documentation site plan. The findings here feed into Phase 2 (Content Restructuring). Specifically:

• The redundancy map above identifies exactly which content to deduplicate before building the site
• The proposed restructuring section provides a content-to-URL mapping for the Astro site structure
• The priority ranking ensures the most impactful fixes happen before the site build, reducing rework
• The SEO readiness assessment identifies gaps that the docs site should address with proper meta tags, H1 elements, and internal linking

Recommended next step: Execute Critical and High Priority items (1-7) in the current repo before beginning Phase 4 (Astro setup). These fixes improve the current GitHub-based experience and reduce content migration work.

Ideas Audit Skill Consistency (`docs/ideas/audit-skill-consistency.md`) Copy Section

Skill SKILL.md Consistency Audit Report

Audit date: 2026-02-02
Audited by: Claude Opus 4.5
Sample size: 10 skills out of 65 total
Reference standard: CLAUDE.md project instructions (Skill Authorship Standards)

1. Consistency Matrix Copy Chapter

The table below tracks whether each sampled skill conforms to the documented standard for each dimension.

Legend: PASS = conforms, FAIL = deviates, WARN = uses value outside documented enum but value is reasonable, -- = not applicable

2. Common Quality Issues Across Skills Copy Chapter

2.1 Phantom Related Skills References (CRITICAL) Copy Section

The most significant cross-cutting issue. Multiple skills reference Related Skills that do not exist in the repository. Across the 10 sampled skills, 4 contain broken references. A broader search reveals this is a systemic problem across the full skill set (30+ phantom references found).

Phantom names found in sampled skills:

Broader systemic phantoms found across all skills (not just sample):

• "Backend Developer" (referenced by 6 skills) -- does not exist
• "Performance Engineer" (referenced by 8 skills) -- does not exist
• "Data Engineer" (referenced by 3 skills) -- does not exist
• "TypeScript Expert" (referenced in javascript-pro) -- actual name is typescript-pro
• "React Developer" (referenced in javascript-pro, typescript-pro) -- actual name is react-expert
• "Azure Specialist" (referenced in csharp-developer) -- does not exist
• "IoT Engineer" (referenced in embedded-systems) -- does not exist
• "Cloud Architect" (referenced by 7 skills) -- actually exists as cloud-architect
• "Security Engineer" (referenced by 2 skills) -- does not exist

Root cause: Related Skills use human-readable display names (e.g., "Backend Developer") that are not validated against the actual skill inventory. Some are aspirational references to skills that were never created. Others use slightly different display names than the actual skill's H1 title.

2.2 All Skills Fall Below Target Line Count Copy Section

CLAUDE.md specifies Tier 1 SKILL.md files should be "~80-100 lines." Every sampled skill falls below the target range:

When blank lines are included, most files are close to the lower end of the 80-100 range. This is acceptable but means there is no headroom -- no skill invests its "line budget" on skill-specific nuances that would differentiate it from a template fill.

2.3 Core Workflow Step Count Inconsistency Copy Section

CLAUDE.md specifies "Core workflow (5 high-level steps)." Two sampled skills use 6 steps:

• debugging-wizard: 6 steps (Reproduce, Isolate, Hypothesize, Test, Fix, Prevent)
• security-reviewer: 6 steps (Scope, Automated scan, Manual review, Active testing, Categorize, Report)

Both 6-step workflows are domain-justified and arguably better for it. This suggests the "5 steps" guidance may be too rigid, or these skills should be brought into compliance.

2.4 Frontmatter Enum Drift Copy Section

The CLAUDE.md documents these enums:

• scope: implementation | review | design | system-design
• output-format: code | document | report | architecture

Actual values found across the full 65-skill set that fall outside these enums:

These are all reasonable values. The issue is that CLAUDE.md's enum list is incomplete, not that the skills are wrong. The documented enums need to be expanded, or a note added that custom values are permitted.

2.5 Non-Standard Frontmatter Fields Copy Section

Two fields appear in some skills but are not documented in CLAUDE.md's Frontmatter Requirements:

• allowed-tools: Used by code-reviewer, spec-miner, security-reviewer (3 skills)

This field is meaningful (restricts which tools the skill can use) but is undocumented. It should either be added to the frontmatter spec or removed from the skills.

2.6 "When to Use" Format Inconsistency Copy Section

9 of 10 sampled skills use a bullet list under "When to Use This Skill." The exception is security-reviewer, which uses a comma-separated prose paragraph:

Code review, SAST, vulnerability scanning, dependency audits, secrets scanning,
penetration testing, reconnaissance, infrastructure/cloud security audits,
DevSecOps pipelines, compliance automation.

This is the only format deviation in the sample but should be standardized for docs site generation.

2.7 Output Templates Format Inconsistency Copy Section

Most skills use a numbered list under "Output Templates." Two deviate:

• security-reviewer: Uses inline prose with numbered parentheticals: "Provide: (1) Executive summary... (2) Findings table..."
• debugging-wizard: Uses bold labels in a numbered list (a richer format than others)

Neither is wrong, but for docs site rendering consistency, a single format should be chosen.

2.8 Attribution Comments in Routing Tables Copy Section

Three skills contain HTML comments for attribution in their Reference Guide tables:

• code-reviewer: ``
• debugging-wizard: Same pattern
• test-master: Same pattern

These are invisible in rendered markdown but would appear in raw source. For a docs site generator that processes SKILL.md files, these should either be preserved (if attribution is required) or moved to a separate attribution section.

3. Section Order Analysis Copy Chapter

The expected section order (derived from CLAUDE.md's Progressive Disclosure Architecture and the majority pattern) is:

1. YAML Frontmatter
2. # Title
3. One-line subtitle/description
4. ## Role Definition
5. ## When to Use This Skill
6. ## Core Workflow
7. ## Reference Guide (table)
8. ## Constraints (### MUST DO, ### MUST NOT DO)
9. ## Output Templates
10. ## Knowledge Reference
11. ## Related Skills

All 10 sampled skills follow this exact order, with one exception:

• feature-forge adds a non-standard ## Pre-Discovery with Subagents section between "Core Workflow" and "Reference Guide." This is the only skill in the sample with an extra section.

This is a strong positive finding: section order is highly consistent.

4. Per-Skill Deviations (Only Where Notable) Copy Chapter

4.1 feature-forge Copy Section

• Extra section: ## Pre-Discovery with Subagents is a non-standard section not found in other skills. It describes a multi-agent workflow pattern.
• Tool-specific constraints: References AskUserQuestions tool explicitly in both Core Workflow and Constraints. This is unique among sampled skills and raises a question: should skills reference specific tools by name, or keep tool usage implicit?
• File output path: Specifies Save as: specs/{feature_name}.spec.md in Output Templates -- the only skill to prescribe a file path.

4.2 security-reviewer Copy Section

• "When to Use" is prose, not bullets (see section 2.6 above).
• Core Workflow has 6 steps instead of 5.
• Output Templates is prose instead of numbered list.
• Has allowed-tools field not in the documented frontmatter spec.
• Overall, this skill deviates more from the template than any other in the sample.

4.3 debugging-wizard Copy Section

• Core Workflow has 6 steps instead of 5.
• scope: analysis and output-format: analysis are outside documented enums.
• Output Templates uses bold labels (e.g., **Root Cause**:, **Evidence**:) -- richer format than others.

4.4 code-reviewer Copy Section

• Has allowed-tools field (undocumented in spec).
• Attribution HTML comment in Reference Guide table.

4.5 python-pro Copy Section

• Phantom Related Skill: References "Data Science Pro" which does not exist.

4.6 terraform-engineer Copy Section

• Phantom Related Skill: References "Security Engineer" which does not exist.
• References "Cloud Architect" which does exist.

4.7 pandas-pro Copy Section

• Phantom Related Skill: References "Data Scientist" which does not exist.
• Only 2 Related Skills listed (fewest in sample; others have 3-4).

4.8 architecture-designer Copy Section

• Lowest line count in sample (69 non-blank lines).
• Related Skills reference names ("Secure Code Guardian") that use different casing/display than the H1 title in the actual skill.

4.9 react-expert, nestjs-expert Copy Section

No notable deviations. These are the most template-conformant skills in the sample.

5. Docs Site Readiness Assessment Copy Chapter

What Works Well for Standalone Pages Copy Section

1. Consistent section structure -- The 11-section order is machine-parseable and could directly map to page sections.
2. YAML frontmatter -- Provides structured metadata for page generation (title, category via scope, output type).
3. Reference Guide table -- Could generate "See Also" or "Deep Dive" link sections.
4. Constraints -- MUST DO / MUST NOT DO sections are visually distinctive and could be rendered as callout boxes.
5. Related Skills -- Natural cross-linking between pages (once phantom references are fixed).

What Is Missing for Standalone Pages Copy Section

6. Template Recommendation Copy Chapter

Based on this audit, the ideal SKILL.md structure for docs site generation would be:

/* Detailed source-code truncated for AI context efficiency. */

7. Priority-Ranked Recommendations Copy Chapter

Critical (Must fix before docs site generation) Copy Section

1. Fix all phantom Related Skills references. Audit every skill's Related Skills against the actual inventory of 65 skills. Either correct the display name to match an existing skill's H1 title, or remove the reference. Estimated: 30+ broken references across the full set.

2. Standardize Related Skills to use resolvable identifiers. Currently these use human-friendly display names that cannot be auto-linked. Options:

   • (a) Use the frontmatter name (slug) as a machine-readable identifier alongside the display name
   • (b) Build a display-name-to-slug mapping table
   • (c) Add a display-name field to frontmatter so the mapping is self-contained

3. Expand the documented frontmatter enums in CLAUDE.md to match actual usage. Add analysis, testing, infrastructure, optimization, architecture to scope. Add analysis, manifests, specification, schema to output-format.

High (Should fix for quality) Copy Section

4. Standardize the "When to Use" section to always use bullet lists, not prose. Fix security-reviewer.

5. Standardize the "Output Templates" section to always use numbered lists, not inline prose. Fix security-reviewer.

6. Enforce the 5-step Core Workflow rule or explicitly amend CLAUDE.md to allow 5-6 steps. Two skills (debugging-wizard, security-reviewer) have 6 steps that are domain-justified.

7. Document the allowed-tools frontmatter field in CLAUDE.md, or decide it belongs in a separate mechanism.

8. Remove or relocate non-standard sections (feature-forge's "Pre-Discovery with Subagents") into a reference file to maintain the standard section order.

Medium (Should fix for docs site polish) Copy Section

9. Add a category frontmatter field for docs site navigation. Values like frontend, backend, language, quality, architecture, design, workflow, infrastructure, security, data, devops, testing would enable auto-generated category index pages.

10. Add a summary frontmatter field (or standardize the subtitle line) for docs site cards and search results. The current description is trigger-focused and reads awkwardly as a page summary.

11. Standardize the subtitle line format after the H1. Propose template: "Senior [role] specializing in [1-2 domains] with expertise in [signature capability]."

12. Convert Reference Guide relative paths to a docs-site-resolvable format, or establish a URL convention that a build step can apply.

Low (Nice to have) Copy Section

13. Consider converting Knowledge Reference from comma-separated prose to a YAML list in frontmatter (or a bullet list in the body) for tag generation on the docs site.

14. Add version or last-updated metadata to frontmatter for docs site freshness indicators.

15. Standardize Related Skills count to 3-4 per skill. pandas-pro has only 2; some non-sampled skills have 4-5.

16. Handle attribution HTML comments in routing tables. Decide whether to preserve as-is, move to a footer, or add an attribution frontmatter field.

17. Consider adding a difficulty or experience-level field to help users self-select appropriate skills.

8. Validation Script Gaps Copy Chapter

The existing scripts/validate-skills.py checks YAML parsing, required fields, name format, description prefix, references directory, and count consistency. Based on this audit, the following checks should be added:

1. Related Skills existence check -- Verify each bold name in Related Skills maps to an actual skill's H1 title or frontmatter name.
2. Core Workflow step count -- Warn if not exactly 5 (or 5-6 if the standard is amended).
3. "When to Use" format check -- Ensure section uses bullet list format, not prose.
4. Frontmatter enum validation -- Check scope and output-format against the expanded (documented) enum list.
5. Section order check -- Verify sections appear in the canonical order.
6. Line count check -- Warn if below 80 or above 100 non-blank lines.

9. Summary Copy Chapter

The skill set shows strong structural consistency. The 11-section template is followed by all 10 sampled skills, with section order preserved perfectly in 9 of 10 cases. Frontmatter fields are present and well-formed. Descriptions consistently follow the "Use when... Invoke for..." pattern.

The critical gap is phantom Related Skills references -- a systemic issue affecting approximately half the skill set and blocking reliable cross-linking on a docs site. The secondary gap is enum drift in frontmatter values, where actual usage has outgrown the documented specification.

Addressing the Critical and High priority items (8 items) would make the skill set docs-site-ready. The Medium and Low items (9 items) would polish the experience but are not blockers.

Ideas Audit Workflow Docs (`docs/ideas/audit-workflow-docs.md`) Copy Section

Workflow Documentation Audit Report

Conducted: 2026-02-02
Scope: Workflow commands, command docs, guides, YAML definitions, and cross-references
Method: Full read of all files in scope, cross-referencing YAML definitions against docs

Executive Summary Copy Chapter

The workflow documentation is unusually thorough for a project of this size. The WORKFLOW_COMMANDS.md file is a well-structured 876-line reference with mermaid diagrams, input/output tables, and checkpoint documentation. The docs/workflow/ directory provides a clean separation between phase overviews and per-command descriptions, and the YAML definitions are consistent and well-typed.

However, the documentation has grown organically across three layers (README, WORKFLOW_COMMANDS.md, and docs/workflow/) without clear delineation of audience or purpose. This creates significant redundancy, a confusing entry path for new users, and several structural mismatches between what the YAML definitions declare and what the docs describe.

This report documents all findings, organizes them by area, and proposes a restructuring plan for migration to Astro + Starlight.

1. Per-Area Findings Copy Chapter

1.1 `docs/WORKFLOW_COMMANDS.md` Copy Section

Strengths:

• Comprehensive: covers all four phases with mermaid diagrams, command signatures, process steps, output sections, and publish locations.
• The Document Flow Summary table (lines 87-97) is an excellent quick-reference artifact.
• Checkpoint documentation (lines 740-812) is thorough and includes realistic examples with response types.
• Workflow Variations section (lines 816-838) clearly communicates the three main paths through the system.

Weaknesses:

• Drift from YAML manifest. The document describes four phases (Discovery, Planning, Execution, Retrospectives) and nine commands. The YAML manifest defines five phases (Intake, Discovery, Planning, Execution, Retrospective) and twelve commands plus one utility. The entire Intake phase (3 commands) is absent from WORKFLOW_COMMANDS.md.
• Naming inconsistencies. The document uses old command names (create-epic-discovery, synthesize-discovery, approve-synthesis, create-epic-plan, create-implementation-plan) while the YAML manifest uses shorter identifiers (discovery:create, discovery:synthesize, discovery:approve, planning:epic-plan, planning:impl-plan). A reader switching between the two sources will be confused about which name to use.
• complete-sprint is documented but absent from the manifest. WORKFLOW_COMMANDS.md describes complete-sprint as a command (lines 632-673). The manifest's retrospective phase lists only retrospectives:complete-epic. There is a commands/project/retrospectives/complete-sprint.md implementation file but no .yaml definition file for it. This is either a manifest omission or the command was removed without updating the docs.
• Common Ground absent. The manifest includes common-ground as a utility command. WORKFLOW_COMMANDS.md does not mention it at all, despite its relevance to the workflow (it can be invoked at any point).
• Monolithic structure. At 876 lines, the file tries to be both a conceptual introduction and a complete reference. The mermaid diagrams and process descriptions serve a "getting started" reader, while the checkpoint tables and integration points serve a "deep reference" reader. These audiences need different documents.

Recommendations:

1. Add the Intake phase to WORKFLOW_COMMANDS.md or explicitly state it is a pre-workflow phase documented elsewhere.
2. Resolve the command naming inconsistency: pick one canonical form (the YAML command identifier) and use it consistently, with aliases noted parenthetically.
3. Either add complete-sprint to the manifest YAML (with a .yaml definition file) or remove it from WORKFLOW_COMMANDS.md.
4. Add a brief mention of common-ground as a utility command available during any phase.
5. For the Astro site, split this into a conceptual overview page and individual command reference pages.

1.2 `docs/workflow/*.md` (Phase Overviews and Command Descriptions) Copy Section

Strengths:

• Clean, consistent structure across all 18 files. Every phase overview has Purpose, Commands table, Outputs, Prerequisites, and Next Steps. Every command description has Overview, Inputs table, Outputs table, Prerequisites, and Next Steps.
• Inputs and outputs match the YAML definitions exactly in all files reviewed. This is strong evidence of either co-generation or disciplined manual maintenance.
• Next Steps sections create a navigable chain: each doc tells you where to go next, forming a complete user journey.
• Status badges (**Status:** Planned) on intake commands clearly communicate availability.

Weaknesses:

• No common-ground phase overview. There is a docs/workflow/common-ground.md command description, but no phase overview that contextualizes it. The manifest lists it under utilities:, not under a phase. The doc structure treats it as though it belongs to a phase.
• No complete-sprint description. There is no docs/workflow/retrospective-complete-sprint.md. The retrospective phase overview mentions only complete-epic. If complete-sprint is a valid command, it needs a description doc.
• Phase names are inconsistent. The manifest uses retrospective (singular). WORKFLOW_COMMANDS.md uses Retrospectives (plural). The phase overview file is retrospective-phase.md (singular). The command prefix in the manifest is retrospectives:complete-epic (plural). This inconsistency will cause confusion in code, docs, and URL generation.
• Relative links may break in a docs site context. All Next Steps links use relative paths like [Planning Phase](planning-phase.md). These work within the docs/workflow/ directory but will need transformation for a docs site with different URL structures.

Recommendations:

1. Decide whether complete-sprint exists in the system. If yes, create docs/workflow/retrospective-complete-sprint.md and add it to the manifest. If no, remove all references.
2. Standardize singular vs. plural: the manifest phase name, the YAML command prefix, the docs directory name, and the file naming convention should all agree.
3. Treat common-ground as a standalone utility in the docs structure (not shoehorned into a phase pattern).

1.3 `docs/COMMON_GROUND.md` Copy Section

Strengths:

• Exceptionally well-written conceptual documentation. The Background & Motivation section (lines 16-41) provides genuine insight into the design rationale.
• The two-phase flow diagram (lines 69-88) clearly illustrates the interactive process.
• The confidence tiers (ESTABLISHED, WORKING, OPEN) are well-defined with practical examples and behavior descriptions.
• The use cases section (lines 328-372) maps real scenarios to specific command flags.

Weaknesses:

• Typo on line 176. "groundin file" should be "grounding file."
• Overlap with README. The README (lines 182-227) duplicates the confidence tier explanation and the --graph mermaid example. When this content moves to a docs site, the README version should be a brief pointer.
• No link to the workflow docs. The Related Documentation section links to WORKFLOW_COMMANDS.md and ATLASSIAN_MCP_SETUP.md, but does not link to the docs/workflow/common-ground.md command description or the YAML definition. A reader in the workflow mindset has no bridge from here to the workflow system.
• No link FROM workflow docs. WORKFLOW_COMMANDS.md does not mention or link to COMMON_GROUND.md at all. The two documentation trees are disconnected.

Recommendations:

1. Fix the "groundin file" typo.
2. Add a link to docs/workflow/common-ground.md in the Related Documentation section.
3. Add a link to docs/COMMON_GROUND.md from within WORKFLOW_COMMANDS.md (perhaps in a "Utility Commands" section).
4. For the Astro site, deduplicate the README and COMMON_GROUND.md versions of the confidence tier explanation.

1.4 `docs/ATLASSIAN_MCP_SETUP.md` Copy Section

Strengths:

• Excellent task-oriented structure. A user can follow from top to bottom and end up with a working setup.
• Covers both Cloud and Server/Data Center configurations.
• The Quick Start Checklist (lines 453-461) is a useful verification artifact.
• Security considerations are thorough: credential protection, read-only mode, space/project filtering, audit trail, and token revocation.
• Environment variable reference tables (lines 421-449) serve as a quick lookup.

Weaknesses:

• Only linked from README and COMMON_GROUND.md. WORKFLOW_COMMANDS.md does not link to this guide despite requiring Atlassian integration for all non-intake commands. A user reading the workflow docs and encountering Jira/Confluence references has no pointer to setup instructions.
• Docker-only approach. The guide assumes Docker. If a user cannot or does not want to run Docker, there is no alternative path (e.g., npx or pip installation of the MCP server).
• No version pinning guidance. The guide uses :latest for the Docker image. For production workflows, this is risky. A note about pinning to a specific version would be prudent.

Recommendations:

1. Add a link to ATLASSIAN_MCP_SETUP.md from the Integration Points section of WORKFLOW_COMMANDS.md.
2. Add a note about version pinning for the Docker image.
3. Mention alternatives to Docker if available, or explicitly state Docker is required.

1.5 `docs/local_skill_development.md` Copy Section

Strengths:

• Solves a real problem clearly: how to test skill changes without releasing.
• The symlink workflow is well-explained with exact commands.
• Caveats section (lines 96-113) proactively addresses the most likely failure modes.
• Quick Reference section (lines 132-149) provides copy-paste commands.

Weaknesses:

• Orphaned document. No other document in the project links to this file. It is not referenced from README.md, CONTRIBUTING.md, or any guide. A contributor who needs it will not find it through navigation.
• No mention of the workflow system. The guide covers skill development but says nothing about developing or testing workflow commands. Given that commands have a parallel structure (YAML definitions, description docs, implementation .md files), a contributor working on workflow commands has no equivalent guide.
• Placeholder paths. The guide uses ``, <name>, <version> as placeholders without providing a concrete example of what these look like for the claude-skills project specifically.

Recommendations:

1. Link this file from CONTRIBUTING.md and README.md (Documentation section).
2. Add a section or separate document for workflow command development.
3. Include one concrete example with actual claude-skills paths alongside the generic placeholders.

1.6 `commands/workflow-manifest.yaml` Copy Section

Strengths:

• Clean DAG structure with typed dependency strengths (required vs. recommended).
• optional: true on discovery phase correctly models the skippable nature of that phase.
• external_skills reference to feature-forge documents the cross-cutting dependency.
• run_once: true on intake correctly distinguishes project-level from epic-level phases.

Weaknesses:

• Missing complete-sprint. The retrospective phase lists only retrospectives:complete-epic. The complete-sprint command exists as an implementation .md file but has no YAML definition and no manifest entry. This is the single largest manifest/docs mismatch.
• No YAML definition files for intake commands exist as .md implementation files. The YAML path fields point to commands/intake/document-codebase.md, commands/intake/capture-behavior.md, and commands/intake/create-system-description.md. None of these files exist on disk. The YAML status: planned field signals this is expected, but the schema documentation says "Must resolve to an existing file when status: existing" -- so the planned status makes this valid. However, the schema doc does not explicitly state that planned status exempts the path resolution rule.
• Phase name mismatch. The manifest uses retrospective (singular) but the command identifiers use retrospectives: (plural).

Recommendations:

1. Resolve the complete-sprint question: add it to the manifest or remove the orphaned .md file.
2. Make the planned-status path exemption explicit in the schema documentation.
3. Align the phase name and command prefix (both singular or both plural).

1.7 Command YAML Definitions (Sample of 6) Copy Section

Strengths:

• 100% schema compliance across all 12 files reviewed. Every file has command, phase (where applicable), path, description, inputs, outputs, requires, status, argument-hint, and repeat.
• Input/output types are consistent and match the schema's allowed values.
• The description field correctly points to the corresponding docs/workflow/*.md file in every case.
• requires fields accurately distinguish commands needing ticketing/documentation backends from those that do not.

Weaknesses:

• Intake commands point to non-existent implementation files. commands/intake/document-codebase.yaml has path: commands/intake/document-codebase.md but this file does not exist. Same for the other two intake commands. The status: planned field explains this, but a CI validation step should catch it.
• common-ground.yaml has no phase field. This is correct per the schema (utilities omit phase), but is inconsistent with the schema documentation which lists phase as required. The schema doc should explicitly state that phase is omitted for utility commands.

Recommendations:

1. Add a CI validation that verifies path files exist when status: existing.
2. Clarify in the schema documentation that phase is omitted for utility commands.

2. Workflow Documentation Gap Analysis Copy Chapter

Commands Documented vs. Commands in YAML Copy Section

Phase Overviews Copy Section

Key Gaps Copy Section

1. Intake phase entirely absent from WORKFLOW_COMMANDS.md. Three commands undocumented in the primary reference.
2. complete-sprint exists as implementation and in WORKFLOW_COMMANDS.md but has no YAML definition or manifest entry. This is a ghost command -- documented but not formally defined.
3. common-ground absent from WORKFLOW_COMMANDS.md. Documented in its own guide (COMMON_GROUND.md) but invisible in the workflow reference.
4. README claims 9 workflows. The manifest defines 12 commands + 1 utility. The README's Project Workflow Commands table lists 9 commands (matching WORKFLOW_COMMANDS.md, not the manifest). The count depends on whether intake and common-ground are included.

3. Proposed Restructuring for Astro + Starlight Copy Chapter

Content Architecture Copy Section

The existing three-layer documentation (README overview, WORKFLOW_COMMANDS.md reference, docs/workflow/ descriptions) should map to Starlight's built-in structure.

Site Structure:
/workflows/                          <- Landing page: DAG diagram, phase cards
/workflows/intake/                   <- Phase overview (from intake-phase.md)
/workflows/intake/document-codebase/ <- Command page (generated from YAML + description .md)
/workflows/intake/capture-behavior/
/workflows/intake/create-system-description/
/workflows/discovery/                <- Phase overview
/workflows/discovery/create/
/workflows/discovery/synthesize/
/workflows/discovery/approve/
/workflows/planning/
/workflows/planning/epic-plan/
/workflows/planning/impl-plan/
/workflows/execution/
/workflows/execution/execute-ticket/
/workflows/execution/complete-ticket/
/workflows/retrospective/
/workflows/retrospective/complete-epic/
/workflows/retrospective/complete-sprint/   <- Only if formalized
/utilities/common-ground/            <- Standalone utility page
/guides/atlassian-setup/             <- Setup guide
/guides/local-development/           <- Development workflow
/guides/getting-started/             <- New: entry point for new users

Page Templates Copy Section

Phase Overview Page (generated from docs/workflow/{phase}-phase.md + manifest data):

• Purpose statement
• DAG position indicator (which phases come before/after)
• Command cards with status badges
• Prerequisites
• Next phase link

Command Reference Page (generated from YAML definition + docs/workflow/{command}.md):

• Command signature with argument hints
• Status badge (existing/planned/deprecated)
• Inputs table (from YAML)
• Outputs table (from YAML)
• Requirements badges (ticketing, documentation)
• Overview narrative (from description .md)
• Prerequisites
• Next Steps
• Phase breadcrumb

Utility Page (for commands like common-ground):

• Same as command reference but without phase context
• Links to the conceptual guide (COMMON_GROUND.md)

What to Retire Copy Section

• WORKFLOW_COMMANDS.md as a single file. Its content splits across the phase overview pages and command reference pages. The mermaid diagrams move to the phase overview pages. The checkpoint system documentation becomes a standalone guide at /guides/checkpoints/. The integration points section becomes /guides/atlassian-setup/ (merged with current ATLASSIAN_MCP_SETUP.md).
• Duplicated content in README. The Project Workflow Commands section in README becomes a brief paragraph pointing to /workflows/. The common-ground section in README becomes a brief paragraph pointing to /utilities/common-ground/.

What to Create Copy Section

1. Getting Started guide. The biggest gap for new users. Currently, a user must read: README (installation) -> ATLASSIAN_MCP_SETUP.md (MCP config) -> WORKFLOW_COMMANDS.md (understand the system) -> docs/workflow/ files (individual commands). A single "Getting Started with Workflows" guide should walk through: install -> configure Atlassian -> run your first planning cycle.
2. Checkpoint System guide. Currently buried in WORKFLOW_COMMANDS.md. Deserves its own page since it is a cross-cutting concern.
3. Workflow FAQ/Troubleshooting. Common questions like "Can I skip discovery?" or "What if a ticket has no implementation details?" are answered implicitly in the docs but not collected anywhere.

4. Recommendations for Standalone Pages Copy Chapter

Each docs/workflow/*.md file is close to being a usable standalone page already. To make them fully independent:

Required Additions Per Command Page Copy Section

1. Command invocation syntax. Add the actual slash-command syntax at the top. Currently the description docs do not include how to invoke the command (e.g., /project:discovery:create <epic-key>). Only WORKFLOW_COMMANDS.md has this.
2. Phase context breadcrumb. Add a one-line note: "Part of the Discovery phase. Comes after intake:create-system-description. Feeds into discovery:synthesize."
3. Requirements callout. Add a visible callout for external dependencies: "Requires: Jira, Confluence. See Atlassian Setup Guide."
4. Status visibility. The intake commands have a status badge, but the existing commands do not explicitly state they are available. Add a consistent status indicator to all pages.

Required Additions Per Phase Page Copy Section

1. DAG context. Add which phases depend on this phase and which this phase depends on (pulling from the manifest's depends_on field).
2. Skip conditions. For optional phases (discovery), state when and how to skip.
3. External skill dependencies. The manifest's external_skills field (e.g., feature-forge as prerequisite for discovery) should be surfaced in the phase overview.

5. Priority Ranking Copy Chapter

Critical (Must fix before next release) Copy Section

1. Resolve complete-sprint status. Either add YAML definition + manifest entry, or remove from WORKFLOW_COMMANDS.md and delete the orphaned implementation file. The current state is contradictory.
2. Fix phase name inconsistency. retrospective (manifest phase name) vs. retrospectives (command prefix). This will cause bugs in any automated tooling that derives one from the other.
3. Add Intake phase to WORKFLOW_COMMANDS.md. Three commands are invisible to anyone reading the primary workflow reference.

High (Should fix for docs site launch) Copy Section

4. Standardize command naming. Establish one canonical name per command and document aliases. Current state: create-epic-discovery (WORKFLOW_COMMANDS.md) vs. discovery:create (manifest) vs. /project:discovery:create-epic-discovery (full invocation path).
5. Cross-link COMMON_GROUND.md and WORKFLOW_COMMANDS.md. These are companion documents with zero cross-references.
6. Cross-link ATLASSIAN_MCP_SETUP.md from WORKFLOW_COMMANDS.md Integration Points section. A reader encountering Jira/Confluence requirements needs the setup guide.
7. Link local_skill_development.md from CONTRIBUTING.md and README. Currently orphaned.
8. Fix "groundin file" typo in COMMON_GROUND.md line 176.
9. Add invocation syntax to each docs/workflow/ command description. Currently, only WORKFLOW_COMMANDS.md shows how to actually invoke commands.

Medium (Should fix for quality) Copy Section

10. Clarify schema documentation for planned-status path exemption. The schema says path must resolve to an existing file but does not mention the planned exemption.
11. Clarify schema documentation for utility command phase omission. The schema says phase is required but utilities omit it.
12. Create a Getting Started guide. New users face a fragmented onboarding path across 4+ documents.
13. Deduplicate README and COMMON_GROUND.md confidence tier explanations. Same content appears in both.
14. Add CI validation for YAML path resolution. Catch broken path references automatically.
15. Update README workflow count. The README claims 9 workflows. The actual count depends on scope definition. Clarify what "workflow" means (commands? phases?) and update.

Nice-to-Have (Future improvement) Copy Section

16. Add a workflow FAQ/troubleshooting page. Collect implicit answers to common questions.
17. Add version pinning guidance to ATLASSIAN_MCP_SETUP.md. The :latest Docker tag is convenient but risky.
18. Add a workflow command development guide. local_skill_development.md covers skills but not commands.
19. Create a checkpoint system standalone guide. Currently buried in WORKFLOW_COMMANDS.md and worth surfacing independently.
20. Add concrete path examples to local_skill_development.md. Replace generic /<name>/<version> with actual claude-skills values.

6. Cross-Reference Matrix Copy Chapter

Documents that should link to each other but currently do not:

7. Summary Metrics Copy Chapter

Ideas Documentation Site (`docs/ideas/documentation-site.md`) Copy Section

Documentation Site

Proposal for a standalone documentation site for the claude-skills project.

Motivation Copy Chapter

The Problem Copy Section

All project content currently lives on github.com/jeffallan/claude-skills. This means:

• No Google Search Console access — can't see which queries drive traffic, can't submit sitemaps, can't control indexing
• No control over meta tags — page titles, OpenGraph, structured data are all GitHub's defaults
• One giant README — 65 skills, 9 workflows, 356 reference files collapsed into a single page
• No individual skill URLs — a skill can't be linked to, shared, or indexed independently

The Opportunity Copy Section

Current traffic data (2-week snapshot, Jan 2026) shows strong organic discovery already happening without any SEO effort:

Additional metrics: 197 stars, 9.5k downloads (skills.sh), 4,560 unique cloners, 4,008 unique visitors in 2 weeks.

Key signals:

• Enterprise adoption — traffic from Microsoft Teams and ByteDance's internal Lark platform indicates workplace sharing
• AI platform discovery — ChatGPT and Claude.ai are referring users organically
• Google dominance — 1,026 unique visitors from search with zero SEO optimization suggests significant upside once proper pages exist

The Insight: Skill Linking = Internal Link Graph Copy Section

Issue #69 (Skill Metadata Enhancement) plans to formalize the existing static ## Related Skills sections into typed metadata.* relationships (complementary, prerequisite, alternative). This metadata serves two consumers simultaneously:

1. Agent runtime — Claude follows structured links to load related skills contextually
2. Documentation site — The same relationships become real <a href> links between skill pages, creating a dense internal link graph

This is exactly what both classic SEO and LLM retrieval reward:

• Google uses internal link structure to understand page relationships and distribute authority
• LLMs doing retrieval follow link structure to build richer context about what the project offers

One schema, two consumers. Relationship data written once in YAML generates both runtime cross-references and HTML internal links.

Issue #100 (Cross-Reference Validation) also becomes dual-purpose — it validates both agent behavior and docs site link integrity.

Hard Requirement: Dual-Format Serving (HTML + Markdown) Copy Chapter

The site MUST serve every content page in two formats from the same URL:

• HTML — for human consumption (styled, navigable, searchable)
• Markdown — for agent consumption (clean, context-efficient, directly loadable)

Format selection via content negotiation (Accept: text/markdown) or URL convention (e.g., /skills/react-expert.md or ?format=md).

Why This Matters Copy Section

The docs site isn't just for humans. Agents are a first-class consumer. When an agent needs to understand what react-expert does, it should be able to fetch the markdown directly from the docs site URL — not scrape HTML and hope the conversion is clean.

This turns the entire docs site into an agent-consumable API:

• llms.txt becomes a routing file pointing agents to markdown endpoints for every skill and command
• An agent can fetch /skills/react-expert.md and get the same content that generates the HTML page — no lossy HTML-to-markdown conversion
• The skill's reference files are available at /skills/react-expert/server-components.md — agents can selectively load exactly what they need
• Workflow commands with typed inputs/outputs are available as structured markdown at /commands/discovery/create.md

Implementation Approaches Copy Section

Option A: Static .md file co-generation

• During build, output both index.html and index.md for every page
• Simple, no runtime logic, works with any CDN/static host
• URL convention: /skills/react-expert/ (HTML) vs /skills/react-expert/index.md (markdown)

Option B: Content negotiation middleware

• Server checks Accept header and returns appropriate format
• Cleaner URLs but requires a server or edge function (not pure static)

Option C: Query parameter

• /skills/react-expert/?format=md returns markdown
• Works with edge functions on static hosts (Cloudflare Pages, Vercel)

Recommendation: Option A (static co-generation) as the baseline — it works everywhere, requires no runtime, and the .md files are just the source markdown the site was built from. Options B or C can be layered on later if cleaner URLs are desired.

Impact on Site Generator Selection Copy Section

This requirement narrows the field. The generator must support outputting both HTML and raw markdown for each content page. This is a build-step concern, not a runtime concern — the generator (or a post-build script) writes both formats to the output directory.

Impact on llms.txt Copy Section

With dual-format serving, llms.txt evolves from a static summary into a structured index with direct markdown URLs:

# Claude Skills
> 65 specialized skills for full-stack developers

## Skills

- [React Expert](/skills/react-expert/index.md): React 18+ with Server Components, hooks, state management
- [NestJS Expert](/skills/nestjs-expert/index.md): NestJS modules, controllers, services, TypeORM/Prisma
- [Python Pro](/skills/python-pro/index.md): Python 3.11+ with type safety, async, pytest
...

## Workflows

- [Discovery Phase](/workflows/discovery/index.md): Research, synthesize, and approve requirements
- [Planning Phase](/workflows/planning/index.md): Analyze codebase and create execution plans
...

Every line is a fetchable markdown URL. An agent reading llms.txt can navigate the entire project without touching HTML.

Architecture: The Autodoc Analogy Copy Chapter

The project already has the equivalent of Python's autodoc infrastructure:

A static site generator consumes the existing YAML definitions and markdown files directly — minimal glue code, not a rewrite.

Content Sources (Already Exist) Copy Section

Content to Create Copy Section

Proposed Site Structure Copy Chapter

/                                   ← Landing page (hero, quick start, stats)
/skills/                            ← Skill index (filterable by category)
/skills/react-expert/               ← Generated from SKILL.md
/skills/react-expert/server-components/  ← Generated from references/
/skills/react-expert/performance/        ← Generated from references/
/commands/                          ← Command index
/commands/common-ground/            ← Generated from command YAML + description .md
/workflows/                         ← DAG visualization of all phases
/workflows/discovery/               ← Phase overview (from docs/workflow/discovery-phase.md)
/workflows/discovery/create/        ← Command detail (from YAML + description .md)
/guide/                             ← Skills guide (from SKILLS_GUIDE.md)
/guide/decision-trees/              ← When to use which skill
/changelog/                         ← Release history
/llms.txt                           ← LLM-consumable project summary

Each skill page would include:

• Frontmatter metadata rendered as structured sidebar (role, scope, triggers)
• Skill body (workflow, constraints, output templates)
• Related Skills as internal links (from metadata.* once #69 lands; from static sections until then)
• Reference files as sub-navigation
• "Install this skill" code snippet

Each command page would include:

• Inputs table (from YAML inputs with types)
• Outputs table (from YAML outputs with types)
• Requirements badges (ticketing, documentation)
• Phase context (where it sits in the DAG)
• Upstream/downstream commands

AI Discoverability: llms.txt Copy Chapter

Add an llms.txt file to both the repo root and the docs site root. Content auto-generated from:

• Skill names, descriptions, and triggers (from SKILL.md frontmatter)
• Workflow phases and command summaries (from workflow-manifest.yaml)
• Project stats (skill count, reference count, framework coverage)
• Installation instructions

This gives LLM retrieval systems (Perplexity, ChatGPT browsing, Claude.ai web search) a structured index without requiring them to parse the full site.

Plan: Documentation Review and Restructure Copy Chapter

Phase 1: Audit Current Documentation Copy Section

Use a technical writing agent to:

1. Inventory all existing docs — README, SKILLS_GUIDE, CONTRIBUTING, docs/*.md, workflow docs, skill SKILL.md files
2. Identify redundancy — content duplicated across README, SKILLS_GUIDE, and individual docs
3. Identify gaps — missing docs, outdated sections, broken cross-references
4. Assess voice consistency — do all docs follow the same tone, structure, terminology?
5. Map content to site structure — which existing doc maps to which site page?

Phase 2: Content Restructuring Copy Section

1. Separate concerns — README becomes a short landing page pointing to the docs site; detailed content moves to docs
2. Deduplicate — single source of truth for each topic; other locations link to it
3. Standardize structure — every skill page follows the same template; every command page follows the same template
4. Write missing content — landing page copy, category descriptions, getting started guide
5. Refresh stale content — update any sections referencing old versions or outdated patterns

Phase 3: Complete #69 — Skill Metadata Enhancement (BLOCKING) Copy Section

This phase must complete before site generator setup. The Astro content collection schemas depend on the finalized metadata structure. Building the site before #69 means defining the schema twice — once provisionally, then again when the metadata spec lands.

#69 determines:

• What fields exist in SKILL.md frontmatter vs. the metadata.* key
• How relationship types are structured (complementary, prerequisite, alternative)
• Whether domain tags, compatibility info, or other new metadata lives under metadata.*
• The finalized schema that both the agent runtime AND the docs site consume

The content collection schema, the internal link graph, the per-page meta tags, and the llms.txt index all derive from whatever #69 produces. Get the data model right first.

What CAN proceed in parallel with #69:

• Phase 1 (audit) and Phase 2 (content restructuring) — these are about the docs content, not the schema
• Evaluating Astro + Starlight with a proof-of-concept using current frontmatter fields
• Setting up the repo structure for the docs site (Astro project scaffolding)

Phase 4: Site Generator Setup — Astro + Starlight Copy Section

Decision: Astro + Starlight

After evaluating Docusaurus, Hugo, MkDocs Material, and VitePress against the hard requirements (dual-format output, auto-generation from YAML/markdown, SEO), Astro + Starlight is the recommended choice.

Why Astro wins for this project:

Why not the others:

• Docusaurus — Best SEO defaults, but ships a React SPA (unnecessary JS weight) and has no native content collection concept. Dual-format requires a custom plugin.
• Hugo — Only SSG with first-class dual-format output (custom output formats). But Go templating for auto-generation from structured YAML is more manual wiring than Astro content collections. Strong fallback if Astro proves problematic.
• MkDocs Material — Unique auto social card generation, but weakest on dual-format and programmatic page generation. Too opinionated about directory structure.
• VitePress — Fast and clean, but less mature plugin ecosystem and no content collections.

Ecosystem fit: The project targets TypeScript/JavaScript developers. Astro uses TypeScript natively. Existing Python scripts (validate-skills.py, update-docs.py) remain as CI validation — the site generator doesn't replace them.

How Content Collections Map to This Project

// Astro content collection schema (conceptual)
// IMPORTANT: Final schema depends on #69 metadata enhancement

skills collection:
  source: skills/*/SKILL.md
  schema:
    name: string          ← from frontmatter
    description: string   ← from frontmatter (max 1024 chars)
    triggers: string[]    ← from frontmatter
    role: enum            ← specialist | expert | architect
    scope: enum           ← implementation | review | design | ...
    output-format: enum   ← code | document | report | ...
    metadata:             ← from #69, structure TBD
      related: object[]   ← typed relationships (complementary, prerequisite, etc.)
      domain: string[]    ← domain tags
      ...

commands collection:
  source: commands/**/*.yaml
  schema:
    command: string       ← phase:action identifier
    phase: string         ← intake | discovery | planning | ...
    inputs: object[]      ← typed input definitions
    outputs: object[]     ← typed output definitions
    requires: string[]    ← ticketing | documentation
    status: enum          ← existing | planned | deprecated

workflows collection:
  source: commands/workflow-manifest.yaml
  schema:
    phases: object        ← DAG definition with depends_on edges
    utilities: object[]   ← on-demand commands

Phase 5: Build and Deploy Copy Section

1. Define Astro content collection schemas from finalized #69 metadata spec
2. Build page templates for skills, commands, workflows
3. Implement dual-format endpoints (HTML + markdown per page)
4. Generate llms.txt from content collections at build time
5. Deploy to GitHub Pages with custom domain
6. Submit sitemap to Google Search Console
7. Add sponsor badges to site and repo README
8. Set up GitHub Actions for auto-deploy on push to main

Phase 6: Ongoing Maintenance Copy Section

• CI check: validate that every skill/command has a corresponding docs page
• CI check: validate internal links (extends #100 cross-reference validation)
• Auto-regenerate llms.txt on release
• Auto-regenerate sitemap on content changes
• Content collection schema validation catches broken frontmatter at build time

Dependency Chain Copy Chapter

#69 Skill Metadata Enhancement
 ├── Docs site content collection schemas (can't finalize without #69)
 ├── #65 Cross-Domain Recommendations (content work, depends on #69)
 ├── #66 Enhanced Routing Logic (better descriptions = better page titles)
 └── Internal link graph (relationship metadata → <a href> links)

#100 Cross-Reference Validation
 └── Docs site link validation (same check, dual purpose)

#68 Skill Dependency Mapping
 └── DAG visualization page on docs site

Phase 1 (Audit) ──────────────────── can start NOW
Phase 2 (Content restructuring) ──── can start NOW
Phase 3 (#69 metadata) ──────────── BLOCKING for site schema
Phase 4 (Astro setup) ───────────── after #69
Phase 5 (Build and deploy) ──────── after Phase 4
Phase 6 (Maintenance) ───────────── ongoing after Phase 5

Open Questions Copy Chapter

1. Custom domain? — docs.claudeskills.dev, skills.jeffallan.dev, or subdirectory of existing site?
2. Versioned docs? — Do we need docs for multiple versions, or just latest?
3. Search — Starlight built-in search vs. Algolia DocSearch (free for open source)?
4. Docs site repo — Same repo (monorepo with /site directory) or separate repo?

Prompts Discovery For Feature Forge (`docs/prompts/discovery-for-feature-forge.md`) Copy Section

Multi-Agent Discovery Prompt for Feature Forge

Purpose: Use this prompt to trigger parallel skill-invoked discovery across
multiple domains before starting a Feature Forge specification workshop.
The collected findings become input context for the Feature Forge interview,
replacing guesswork with concrete technical evidence.

Prompt Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Usage Copy Chapter

Basic Invocation Copy Section

Replace [FEATURE DESCRIPTION] with your feature summary:

I need to define a new feature: user-facing data export that supports CSV and JSON
formats with scheduled recurring exports.

Before we start the Feature Forge specification workshop, run parallel discovery...

Customizing Discovery Agents Copy Section

Not every feature needs all four discovery tracks. Tailor the subagent list:

Expected Output Flow Copy Section

User provides feature description
    │
    ├─→ [Parallel] Architecture Discovery ──→ Component map, constraints
    ├─→ [Parallel] Security Discovery ──────→ Auth reqs, data sensitivity
    ├─→ [Parallel] Codebase Discovery ──────→ Existing patterns, templates
    └─→ [Parallel] API Discovery ───────────→ Endpoint design, integrations
         │
         ▼
    Synthesized Discovery Summary
         │
         ▼
    AskUserQuestions: Key decisions from discovery
         │
         ▼
    Feature Forge Interview (informed by discovery context)
         │
         ▼
    EARS Specification Document

Design Rationale Copy Chapter

This prompt applies the ReAct + Chain-of-Thought pattern from prompt engineering:

• ReAct: Each subagent acts as a reasoning-action step — it invokes a skill (action),
  collects findings (observation), then feeds results forward.
• Chain-of-Thought: The synthesis step forces explicit reasoning about how discovery
  findings connect before entering the Feature Forge interview.
• Structured Elicitation: Key decisions surface as AskUserQuestions with options
  derived from technical evidence, not assumptions.

The parallel execution pattern reduces total discovery latency — all four agents run
concurrently rather than sequentially asking the user about each domain.

Skill Ideas Tarot (`docs/skill-ideas/tarot.md`) Copy Section

Tarot-Inspired Skill Ideas

High-level concepts mapping tarot archetypes to agent behaviors. Each archetype provides a memorable invocation pattern and a distinct cognitive mode.

The Fool (In Progress) Copy Chapter

Archetype: The court jester who speaks truth to power.

Purpose: Domain-agnostic critical reasoning with 5 modes — Socratic questioning, Hegelian dialectic, pre-mortem, red teaming, and evidence audit. Uses AskUserQuestions for mode selection.

Trigger: "play the fool", "devil's advocate", "challenge this"

Status: Full plan at docs/skill-ideas/the-fool.md

The Hermit Copy Chapter

Archetype: The seeker who withdraws to understand before acting.

Purpose: Deep research and reflection. When you need to step back from implementation and truly understand something first. Systematic codebase archaeology, reading documentation thoroughly, tracing data flows end-to-end. The opposite of "let me just try something."

Trigger: "I need to understand this before touching it"

Gap filled: No existing skill enforces a read-only investigation phase before action. Debugging-wizard investigates bugs; The Hermit investigates systems — how they work, why they were built this way, what the original authors intended.

Possible modes:

• Trace a data flow end-to-end
• Map the dependency graph of a concept
• Reconstruct the decision history (git archaeology)
• Build a mental model before proposing changes

The Tower Copy Chapter

Archetype: Lightning strikes — the old structure falls so something better can rise.

Purpose: Controlled demolition and rebuild. When something is fundamentally broken and incremental fixes won't work. Guides tearing down and rebuilding: legacy system replacement, major refactors, ripping out a bad abstraction.

Trigger: "this needs to be torn down and rebuilt"

Gap filled: Legacy-modernizer focuses on incremental migration (strangler fig). The Tower is for when incremental isn't viable — you need a clean break with a structured rebuild plan.

Possible modes:

• Blast radius assessment (what breaks if we remove this?)
• Parallel build strategy (new system alongside old)
• Cut-over planning (the moment of switch)
• Rollback design (if the new thing fails)

The Wheel of Fortune Copy Chapter

Archetype: The turning wheel — fate, chance, and multiple possible futures.

Purpose: Scenario planning under genuine uncertainty. Not "what could go wrong" (that's The Fool's pre-mortem) but mapping multiple possible futures and building strategies robust across them. Decision-making when you genuinely don't know which way things will go.

Trigger: "we don't know which way this will go"

Gap filled: No existing skill handles multi-scenario planning. Architecture-designer evaluates trade-offs for a known context; The Wheel of Fortune plans for unknown contexts.

Possible modes:

• Scenario generation (3-4 plausible futures)
• Strategy robustness testing (does this plan work across scenarios?)
• Optionality analysis (which choice preserves the most future options?)
• Trigger identification (what signals tell us which scenario is unfolding?)

The Magician Copy Chapter

Archetype: Manifestation — turning idea into reality with the tools at hand.

Purpose: Rapid prototyping and proof of concept. Takes an idea and manifests the simplest possible working version to test feasibility. Ruthlessly YAGNI. "Show me the smallest thing that proves this works."

Trigger: "can we even do this?", "prove this works"

Gap filled: Feature-forge defines requirements; The Magician skips requirements and builds the thinnest possible slice to answer a feasibility question. Complements feature-forge — use The Magician to validate assumptions before writing specs.

Possible modes:

• Feasibility spike (can the technology do this at all?)
• Integration probe (can these two systems talk to each other?)
• Performance experiment (will this approach scale?)
• UX sketch (does this interaction model make sense?)

The High Priestess Copy Chapter

Archetype: Intuition and hidden knowledge — seeing what others miss.

Purpose: Pattern recognition and intuition translation. When something "feels wrong" but you can't articulate why. Translates gut feelings into concrete technical concerns. Examines code smells, architectural drift, naming inconsistencies — the subtle signals that something is off.

Trigger: "something about this doesn't feel right"

Gap filled: Code-reviewer checks against known standards. The High Priestess investigates the unnamed — the patterns that don't match, the drift from original intent, the subtle wrongness that no linter catches.

Possible modes:

• Code smell archaeology (what changed and when did it start drifting?)
• Naming analysis (do the names still match what the code does?)
• Architectural consistency (does this component belong here?)
• Implicit contract detection (what undocumented assumptions does this code rely on?)

The Star Copy Chapter

Archetype: The guiding light — hope, purpose, and true north.

Purpose: North star alignment. When you're deep in implementation weeds and need to reconnect with the original vision. Checks current work against stated goals, user needs, and project values. Detects scope creep, gold plating, and mission drift.

Trigger: "are we still building the right thing?"

Gap filled: No existing skill checks alignment between work-in-progress and original intent. Feature-forge defines the target; The Star checks whether you're still pointed at it.

Possible modes:

• Goal alignment audit (does this PR serve the stated objective?)
• Scope creep detection (what got added that wasn't in the spec?)
• User value check (does the end user actually benefit from this work?)
• Simplification pass (what can be removed and still deliver the value?)

Death Copy Chapter

Archetype: Transformation — endings that enable new beginnings.

Purpose: Graceful deprecation and migration. Not destruction (that's The Tower) but transition. Guides sunsetting features, migrating users, deprecation timelines, and backward compatibility strategies. The art of ending things well.

Trigger: "we need to retire this"

Gap filled: Overlaps with legacy-modernizer but with a different focus. Legacy-modernizer transforms old into new; Death manages the ending — communication, migration paths, timeline, and the social/organizational aspects of removing something people depend on.

Possible modes:

• Impact assessment (who uses this and how?)
• Migration path design (where do users go instead?)
• Deprecation timeline (warnings, soft removal, hard removal)
• Tombstone documentation (why was this removed, and what replaced it?)

The Emperor Copy Chapter

Archetype: Order, structure, authority — the rules of the realm.

Purpose: Governance and standards enforcement. Audits a codebase or project against its own stated standards. Checks that conventions are followed, ADRs are respected, and architectural boundaries aren't violated. Not inventing rules — enforcing the ones already committed to.

Trigger: "are we following our own rules?"

Gap filled: Overlaps with code-reviewer but scoped differently. Code-reviewer evaluates individual PRs; The Emperor evaluates systemic compliance across the whole project. Checks ADRs, CONTRIBUTING.md, architectural decision records, and stated conventions.

Possible modes:

• Convention audit (are naming patterns, file structures consistent?)
• ADR compliance (are architectural decisions being followed?)
• Boundary check (are module boundaries respected?)
• Drift detection (where has the codebase diverged from stated standards?)

Overlap Analysis Copy Chapter

Strongest unique concepts (no significant overlap): The Hermit, The Wheel of Fortune, The High Priestess, The Star

Interesting but overlapping (need clear boundary with existing skills): The Tower, Death, The Emperor, The Magician

Skill Ideas The Fool (`docs/skill-ideas/the-fool.md`) Copy Section

Plan: `the-fool` Skill

Summary Copy Chapter

Create a domain-agnostic critical reasoning skill with 5 modes, rooted in the archetype of the Fool — the one who speaks truth to power. Uses AskUserQuestions for mode selection. Invoked organically mid-conversation with "play the fool" as mandatory trigger.

File Structure Copy Chapter

skills/the-fool/
  SKILL.md                              (~95 lines)
  references/
    socratic-questioning.md             (~150 lines)
    dialectic-synthesis.md              (~150 lines)
    pre-mortem-analysis.md              (~200 lines)
    red-team-adversarial.md             (~150 lines)
    evidence-audit.md                   (~150 lines)
    mode-selection-guide.md             (~100 lines)

SKILL.md Design Copy Chapter

Frontmatter Copy Section

---
name: the-fool
description: Use when challenging ideas, plans, decisions, or proposals using structured critical reasoning. Invoke to play the fool, devil's advocate, pre-mortem, red team, or evidence audit.
triggers:
  - play the fool
  - devil's advocate
  - challenge this
  - stress test
  - poke holes
  - what could go wrong
  - red team
  - pre-mortem
  - test my assumptions
role: expert
scope: review
output-format: report
---

Role Definition Copy Section

The Fool — the court jester who alone could speak truth to the king. Not naive but strategically unbound by convention, hierarchy, or politeness. Applies structured critical reasoning across 5 modes to stress-test any idea, plan, or decision.

When to Use Copy Section

• Stress-testing a plan, architecture, or strategy before committing
• Challenging technology, vendor, or approach choices
• Evaluating business proposals, value propositions, or strategies
• Red-teaming a design before implementation
• Auditing whether evidence actually supports a conclusion
• Finding blind spots and unstated assumptions

Core Workflow (5 steps) Copy Section

1. Identify (Thesis) — Extract the user's position from conversation context. Restate it as a steelmanned thesis for confirmation.
2. Select (Method) — Use AskUserQuestions to let the user choose a reasoning mode, or auto-recommend based on context signals.
3. Challenge (Antithesis) — Apply the selected mode's method. Load the corresponding reference file for deep guidance.
4. Engage (Dialogue) — Present findings. Ask the user to respond to the strongest 2-3 points before proceeding.
5. Synthesize (Resolution) — Integrate insights into a strengthened position. Offer to run a second pass with a different mode.

5 Reasoning Modes Copy Section