<skill_flows>

## Purpose

Define how Teddy discovers, matches, and enforces skill dependencies across the development loop. Skill flows bridge the gap between available custom skills (`~/.claude/commands/`) and project needs, ensuring the right skills are used at the right time without manual tracking.

## The 3-Layer Model

Skill flows operate through three layers that progressively narrow available skills to confirmed project dependencies:

```text
Layer 1: DISCOVERY          Layer 2: MATCHING           Layer 3: CONFIRMATION
┌──────────────────┐       ┌──────────────────┐       ┌──────────────────┐
│                  │       │                  │       │                  │
│  Scan            │       │  Compare skill   │       │  Present each    │
│  ~/.claude/      │──────►│  frontmatter     │──────►│  match for user  │
│  commands/       │       │  against project  │       │  [y] [n] [a]    │
│                  │       │  context          │       │                  │
│  Read frontmatter│       │  Assign           │       │  Record accepted │
│  Categorize      │       │  confidence       │       │  Track rejected  │
│                  │       │  levels           │       │  Write FLOWS.md  │
└──────────────────┘       └──────────────────┘       └──────────────────┘
     All skills              Filtered + ranked          User-approved only
```

- **Discovery** scans the filesystem and extracts metadata — no judgment applied
- **Matching** compares skill metadata against PROJECT.md, ROADMAP.md, and existing FLOWS.md
- **Confirmation** requires explicit user approval before any skill becomes a project dependency

## Priority Levels

| Priority | Meaning | At PLAN | At APPLY | At UNIFY |
|----------|---------|---------|----------|----------|
| `required` | Must be used for relevant work types | Auto-included in `<skills>` section | **Blocks** execution if missing from plan | Warns if not found in execution logs |
| `recommended` | Should be used unless good reason not to | Suggested in `<skills>` section | Warns but does not block | Notes absence in audit |
| `optional` | Available if team decides to use | Listed as available, not auto-included | No enforcement | No enforcement |

## Enforcement Hierarchy

Skill flows are configured once and enforced throughout the loop:

```text
/teddy:flows                    ← Configure skill dependencies
    │
    ▼
/teddy:plan                     ← detect_required_skills reads FLOWS.md
    │                              Suggests skills for <skills> section
    │                              Runs between design_team_composition
    │                              and create_plan steps
    ▼
/teddy:apply                    ← verify_required_skills reads PLAN.md <skills>
    │                              Blocks if required skills missing
    │                              Priority: blocking (before team spawn)
    ▼
/teddy:unify                    ← audit_skill_usage cross-references
                                   FLOWS.md + PLAN.md with execution
                                   Warns but does not block merge
```

### At PLAN (`detect_required_skills` step)

Reads `.teddy/FLOWS.md` and analyzes plan tasks to suggest relevant skills:

1. Load all `required` and `recommended` skills from FLOWS.md
2. Match skill work types against plan task domains (e.g., "backend" skills for API tasks)
3. Check phase overrides for current phase
4. Generate `<skills>` section for the plan with matched skills
5. Present suggestions to user during plan review

**Placement:** Runs between `design_team_composition` and `create_plan` steps so skills inform task creation.

### At APPLY (`verify_required_skills` step)

Reads `PLAN.md` `<skills>` section and validates before spawning the team:

1. Parse `<skills>` section from the plan
2. For each `required` skill: verify it's listed with clear usage instructions
3. If any required skill is missing: **block execution** and prompt user to update plan
4. For `recommended` skills: warn if missing but allow proceed

**Priority:** `blocking` — runs before team creation. No team spawns until required skills are accounted for.

### At UNIFY (`audit_skill_usage` step)

Cross-references FLOWS.md + PLAN.md with actual execution results:

1. Read FLOWS.md required/recommended skills
2. Read PLAN.md `<skills>` section
3. Check execution artifacts for evidence of skill usage
4. Generate audit report: used, unused, missing
5. **Warn but do not block** — UNIFY should not fail due to skill issues

## FLOWS.md Format

The `.teddy/FLOWS.md` file is the persistent configuration generated by `/teddy:flows`. Structure:

```markdown
# Flows: {project_name}

## Discovered Skills
| Skill | Description | Category | Source |

## Project Mappings
| Work Type | Skill | Priority | Trigger | Confidence | Confirmed |

## Rejected Suggestions
| Skill | Reason Suggested | Reason Rejected | Date |

## Phase Overrides
| Phase | Additional Skills | Notes |

## Verification Checklist
- [ ] Required skills for phase [N] configured
- [ ] All required skills present in PLAN.md <skills>

## Amendment History
| Date | Change | Reason |
```

See @templates/FLOWS.md for the full template with field documentation.

## The `<skills>` Section in PLAN.md

Plans that use skill flows include a `<skills>` section listing active skills for that plan:

```xml
<skills>

## Required Skills
| Skill | Work Type | Usage | Trigger |
|-------|-----------|-------|---------|
| my-api-skill | backend | Apply to all API route tasks | always |
| test-patterns | testing | Use for test file generation | always |

## Recommended Skills
| Skill | Work Type | Usage | Trigger |
|-------|-----------|-------|---------|
| code-review | quality | Run before marking tasks complete | manual |

## Notes
- Skills sourced from .teddy/FLOWS.md (configured via /teddy:flows)
- Required skills must be present — apply will block if missing
- Recommended skills are suggested but not enforced

</skills>
```

This section is added by the `detect_required_skills` step during PLAN and verified by `verify_required_skills` during APPLY.

## Confidence Levels

Confidence levels are assigned during the matching layer and influence suggestion priority:

| Level | Criteria | Example | Default Priority |
|-------|----------|---------|-----------------|
| **HIGH** | Direct keyword match between skill description and project stack/goals | Skill mentions "React" and PROJECT.md lists React in stack | `required` |
| **MEDIUM** | Category match — skill category aligns with project work types | Skill is "testing" category and ROADMAP.md has test phases | `recommended` |
| **LOW** | Indirect or tangential match | Skill mentions "security" and project has auth features | `optional` |
| **SKIP** | Previously rejected by user in FLOWS.md | Recorded in Rejected Suggestions table | Not suggested |

Confidence is a suggestion — the user's confirmation decision overrides it.

## Rejected Suggestions

When a user rejects a skill during confirmation:

1. The skill is recorded in FLOWS.md `## Rejected Suggestions` with the rejection reason
2. On subsequent runs, matching assigns SKIP confidence to rejected skills
3. Rejected skills are **never re-suggested** automatically
4. To reconsider a rejected skill, the user must manually add it via `/teddy:flows add`

This prevents suggestion fatigue and respects user decisions.

## Anti-Patterns

| Anti-Pattern | Problem | Fix |
|-------------|---------|-----|
| Marking all skills as `required` | Blocks execution unnecessarily | Reserve `required` for truly essential skills |
| No phase overrides | Same skills enforced for design and testing phases | Configure phase-specific overrides for specialized work |
| Ignoring LOW confidence matches | May miss useful skills | Review all suggestions, not just HIGH confidence |
| Re-running full /teddy:flows every phase | Overwrites manual adjustments | Use `/teddy:flows add` or `/teddy:flows audit` for incremental changes |
| Skipping audit before UNIFY | Missing skills not caught until review | Always run `/teddy:flows audit` or let UNIFY's audit step catch issues |
| Including skill implementation details | Security risk — exposes custom prompts | Only frontmatter/metadata is read and stored |

</skill_flows>