feat: add /gap-analysis and /plan commands with /implement plan detection

# Plan: `/gap-analysis` + `/plan` Commands + `/implement` Plan Detection

## Context

Analysis of 20+ Alefy v17 sessions revealed two critical workflow gaps:

1. **Gap analysis was manual and iterative** — 10 sessions, 81 gaps, 15 convergence rounds. The same 7 checks were run manually each time. This is the highest-ROI automation target.
2. **Architectural issues were caught too late** — N+1 queries, 346-line handlers, sequential API calls only surfaced in post-implementation code review. A design review gate before coding would shift quality left.

The solution restructures the DevFlow pipeline:

```
/specify → /gap-analysis (iterative) → /plan (with design review) → /implement (autonomous)
```

All human decisions are front-loaded. `/implement` becomes fire-and-forget.

---

## Overview: 3 Changes

| Change | Type | Purpose |
|--------|------|---------|
| `/gap-analysis` | New command + plugin | Cross-artifact spec consistency (standalone, iterative) |
| `/plan` | New command + plugin | Explore + plan + design review + user approval → stored artifact |
| `/implement` mod | Phase 1.25 addition | Detect pre-approved plan → skip explore/plan phases |

---

## 1. `/gap-analysis` Command

### Plugin: `devflow-gap-analysis`

**Agents**: git, gap-checker (NEW), synthesizer
**Skills**: gap-analysis (NEW), github-patterns, docs-framework

### Command Flow (5 phases)

```
Phase 0: Gather    → Git agent fetches all issues (bodies + comments) + read spec doc
Phase 1: Analyze   → 3-4 gap-checker agents in PARALLEL (by focus area)
Phase 2: Synthesize → Synthesizer (mode: gap-analysis) → readiness score + deduplication
Phase 3: Report    → Present gaps, AskUserQuestion for CRITICAL/HIGH decisions
Phase 4: Resolve   → Apply approved fixes (update issues/spec via Git agent)
```

### Gap-Checker Agent Focus Areas (parallel)

| Agent | Check Layers | What It Catches |
|-------|-------------|-----------------|
| Consistency | Contradiction detection + comment drift | Conflicting statements across issues; stale comments contradicting bodies |
| Completeness | Completeness validation + AC testability | Missing schemas, undefined edge cases, vague acceptance criteria |
| Scope | Ownership clarity + dependency mapping | Same feature in N issues, implicit dependencies not declared |
| Alignment (DEEP only) | Codebase alignment | Spec assumptions that don't match actual code |

### Key Design Decisions (from session insights)

- **Iterative convergence**: `--prior` flag accepts path to prior report. Skips resolved gaps. Tracks convergence history across runs.
- **Convergence signal**: 3 consecutive runs with <2 new CRITICAL gaps = "implementation ready"
- **Options-based resolution**: CRITICAL/HIGH gaps presented with 2-4 options + tradeoffs (most effective pattern from sessions)
- **Evidence-required**: Iron Law — every gap must cite specific text from specific artifacts. No speculation.
- **Follow-up friendly**: Deferred items become follow-up issues via Git agent, not ignored
- **Readiness score**: `100 - (CRITICAL×15) - (HIGH×8) - (MEDIUM×3) - (LOW×1)`. Score 90+ = ready.

### Usage

```
/gap-analysis --issues 42,43,44
/gap-analysis --issues 42,43,44 --spec docs/v17-spec.md
/gap-analysis --issues 42,43,44 --depth DEEP
/gap-analysis --issues 42,43,44 --prior .docs/gap-analysis/2026-03-10_42-44.md
```

### Output Artifact

`.docs/gap-analysis/{YYYY-MM-DD_HHMM}_{issue-range}.md` — structured report with gap table, decision log, convergence history, follow-up issues created.

---

## 2. `/plan` Command

### Plugin: `devflow-plan`

**Agents**: git, skimmer, synthesizer, design-reviewer (NEW)
**Skills**: agent-teams, design-review (NEW), implementation-patterns

### Command Flow (9 phases)

```
Phase 1: Resolve Task  → Git agent fetches issue (if #number), or use description
Phase 2: Orient        → Skimmer agent
Phase 3: Explore       → 4 Explore agents (PARALLEL) — same as /implement
Phase 4: Synthesize    → Synthesizer (mode: exploration)
Phase 5: Plan          → 3 Plan agents (PARALLEL) — same as /implement
Phase 6: Synthesize    → Synthesizer (mode: planning → execution strategy)
Phase 7: Design Review → Design Reviewer agent (NEW)
Phase 8: User Gate     → AskUserQuestion: Approve / Approve with notes / Revise / Cancel
Phase 9: Store Plan    → Write to .docs/plans/{issue-number}-{slug}.md
```

Phases 2-6 are extracted from `/implement` phases 1.5-5 (identical logic).
Phase 7 is new. Phase 8-9 are new.

### Design Reviewer Agent

Critiques the implementation plan for 6 architectural risk categories:

| Check | Red Flag | From Session Insight |
|-------|----------|---------------------|
| Query cardinality | "for each X, fetch Y" patterns | N+1 Middesk calls caught in review, not planning |
| Function size | Single step spanning 5+ operations | 346-line createEntity handler |
| Parallelism | Sequential steps with no data dependency | Sequential Firestore reads that could be parallel |
| Error handling | State mutation without rollback plan | Reorder failure handling was underspecified |
| Caching | Same data read in multiple steps | Redundant auth/tenant reads |
| Decomposition | Step touching 3+ layers | Mixed API + DB + UI concerns |

**Verdict**: APPROVED or CONCERNS (with specific flags referencing plan steps)

### Plan Artifact Format

Stored at `.docs/plans/{issue-number}-{slug}.md`:

```markdown
# Implementation Plan: #{number} — {title}

## Metadata
- Issue: #{number}
- Created: {timestamp}
- Status: APPROVED
- Design Review: PASSED | PASSED_WITH_NOTES

## Execution Strategy
{SINGLE_CODER | SEQUENTIAL_CODERS | PARALLEL_CODERS}

## Subtask Breakdown
### Phase 1: {description}
- Domain: {backend|frontend|tests|fullstack}
- Files: ...
- Steps: ...

## Patterns & Integration Points
## Reusable Code
## Design Review Notes
## User Notes
```

### Usage

```
/plan #42
/plan "implement JWT auth"
```

### Key Design Decisions

- **Max 2 revision cycles** — if user selects "Revise", re-runs phases 5-7 with feedback. After 2 revisions, suggests running `/implement` directly.
- **No branch creation** — `/plan` doesn't create branches or write code. That's `/implement`'s job.
- **Plan files are project-scoped** — stored in `.docs/plans/`, not branch-scoped, since plans exist before branches.

---

## 3. `/implement` Modifications

### New Phase 1.25: Plan Detection

Insert after Phase 1 (Git Setup), before Phase 1.5 (Orient):

```
Phase 1.25: Plan Detection
  1. If ISSUE_NUMBER available: Glob .docs/plans/{ISSUE_NUMBER}-*.md
  2. If description only: Glob .docs/plans/{slug}*.md
  3. If match found:
     a. Read plan file
     b. Verify Status: APPROVED
     c. Extract: execution strategy, subtask breakdown, patterns, AC
     d. Report: "Pre-approved plan detected. Skipping exploration/planning."
     e. Skip directly to Phase 6 (Code)
  4. If no match: continue to Phase 1.5 as normal (backward compatible)
```

This makes `/implement` **backward compatible** — works exactly as before without a plan, but skips exploration/planning when one exists.

---

## 4. Edge Cases & Side Effects

### Plan Staleness
If a plan was created days/weeks ago but the codebase changed, it could be stale.
- **Solution**: In `/implement` Phase 1.25, check plan's `Created` timestamp. If >48h old, warn: "Plan created {N} days ago. Codebase may have changed. Proceed or re-plan?"
- Display `git log --oneline --since="{plan_date}"` count to show how many commits happened since.

### Plan Overwrite
Running `/plan #42` when `.docs/plans/42-*.md` already exists.
- **Solution**: Warn the user via AskUserQuestion: "Existing plan found for #42 (created {date}). Overwrite or cancel?"

### Gap ID Stability (Convergence Tracking)
Gaps need stable IDs across iterative runs so `--prior` can track which are resolved vs new.
- **Solution**: Gap ID = deterministic hash of `{check_layer}_{sorted_issue_numbers}_{normalized_key_phrase}` (first 8 chars of SHA-256). Same contradiction produces same ID across runs.

### Large Issue Sets (Context Limits)
If 20+ issues are passed, each gap-checker agent receives ALL issue data — could blow context.
- **Solution**: For >10 issues, truncate each issue body to 3000 chars and each comment to 1000 chars. Note truncation in agent input. The `--depth DEEP` flag should not be used with >10 issues (warn and downgrade to QUICK).

### Git Agent `update-issue` is Destructive
All existing Git agent operations are read or create-only. `update-issue` modifies existing GitHub state.
- **Solution**: Gap-analysis Phase 4 (Resolve) only runs after explicit user approval in Phase 3. The Git agent's `update-issue` operation should include a `REASON` field logged in the gap report's decision log for audit trail. The command NEVER modifies issues without prior AskUserQuestion approval.

### Closed/Draft Issues
What if some issues passed to `/gap-analysis` are closed?
- **Solution**: Include closed issues in analysis (contradictions can exist in closed issues). Flag status in report. Skip draft issues (not publicly visible).

### Missing Acceptance Criteria
`/plan` stores AC in the plan artifact, but the source issue may have none.
- **Solution**: If no AC found, the plan artifact's AC section reads "Not specified — plan based on issue description and codebase patterns." Design Reviewer flags this as a MEDIUM concern.

---

### Additional Files to Modify (not in original list)

| File | Change | Why |
|------|--------|-----|
| `shared/skills/docs-framework/SKILL.md` | Add `.docs/plans/` and `.docs/gap-analysis/` directories + agent persistence rules | New output directories need naming conventions |
| `shared/skills/ambient-router/SKILL.md` | Add `/gap-analysis` and `/plan` to PLAN intent routing | User prompts like "check my issues for consistency" should suggest the command |
| `shared/skills/ambient-router/references/skill-catalog.md` | Add gap-analysis and design-review to skill-to-intent mapping | Ambient mode needs to know about new skills |

### Plugin.json Fix
`devflow-plan` plugin.json must also declare `git` agent (used in Phase 1 to fetch issue).

### Partial Agent Failure
If 1 of 4 gap-checker agents fails (timeout, context overflow), the synthesizer should:
- Process results from the remaining agents
- Note which check layers were NOT analyzed due to failure
- Recommend re-running with `--depth QUICK` if the failed agent was the alignment checker
- Score calculation only factors in analyzed layers (don't penalize for missing data)

Same applies to `/plan`: if 1 of 4 explore agents fails, synthesizer works with 3 results and notes the gap.

### Auto-Detect Prior Report
Instead of requiring `--prior` flag every time, `/gap-analysis` should auto-detect the most recent report for the same issue set:
- Look in `.docs/gap-analysis/` for reports matching the same issue numbers
- If found, use as prior automatically
- User can override with `--prior none` to start fresh
- This makes iterative runs seamless: just run `/gap-analysis --issues 42,43,44` repeatedly

### Commands Work Independently
The pipeline `/specify → /gap-analysis → /plan → /implement` is the recommended flow, but each command works standalone:
- `/plan` works without prior `/gap-analysis` (issues may have gaps, but planning proceeds)
- `/implement` works without prior `/plan` (backward compatible, runs its own explore/plan)
- `/gap-analysis` works without prior `/specify` (issues may have been created manually)
No command enforces dependencies on prior commands.

### Re-Planning After Implementation Starts
If user runs `/plan #42` after implementation has already started on a feature branch:
- The new plan overwrites the old plan file
- BUT code already exists on the branch
- `/implement` should detect this: if the feature branch already has commits, warn: "Feature branch already has commits. Plan may conflict with existing work. Proceed or abort?"

### Spec Document Format
The `--spec` flag should accept:
- Markdown files (`.md`)
- Plain text files (`.txt`)
- Any text-based format (read as raw text)
- NOT directories (suggest listing specific files instead)

### Artifact Persistence
`.docs/plans/` and `.docs/gap-analysis/` should be **committed to git** (unlike `.memory/` which is session-local). These are project artifacts useful for team context.
- No `.gitignore` entry needed for these directories
- They follow the same pattern as `.docs/reviews/` (already committed)

---

## Files to Create (14 new files)

### New Plugin: `devflow-gap-analysis`
```
plugins/devflow-gap-analysis/
  .claude-plugin/plugin.json
  commands/gap-analysis.md
  commands/gap-analysis-teams.md
  README.md
```

### New Plugin: `devflow-plan`
```
plugins/devflow-plan/
  .claude-plugin/plugin.json
  commands/plan.md
  commands/plan-teams.md
  README.md
```

### New Shared Agents
```
shared/agents/gap-checker.md        (~100 lines, Worker agent)
shared/agents/design-reviewer.md    (~100 lines, Worker agent)
```

### New Shared Skills
```
shared/skills/gap-analysis/SKILL.md                 (~140 lines)
shared/skills/gap-analysis/references/check-layers.md
shared/skills/design-review/SKILL.md                (~130 lines)
shared/skills/design-review/references/red-flags.md
```

## Files to Modify (11 files)

| File | Change |
|------|--------|
| `plugins/devflow-implement/commands/implement.md` | Add Phase 1.25 (Plan Detection) with staleness warning |
| `plugins/devflow-implement/commands/implement-teams.md` | Same Phase 1.25 addition |
| `shared/agents/synthesizer.md` | Add `gap-analysis` mode |
| `shared/agents/git.md` | Add `fetch-issues-batch` + `update-issue` operations |
| `shared/skills/docs-framework/SKILL.md` | Add `.docs/plans/` and `.docs/gap-analysis/` directories + persistence rules |
| `shared/skills/ambient-router/SKILL.md` | Route PLAN intent to `/gap-analysis` and `/plan` suggestions |
| `shared/skills/ambient-router/references/skill-catalog.md` | Add gap-analysis + design-review to skill-to-intent mapping |
| `src/cli/plugins.ts` | Register `devflow-gap-analysis` + `devflow-plan` |
| `.claude-plugin/marketplace.json` | Add 2 marketplace entries |
| `CLAUDE.md` | Update plugin table, agent/skill counts, command roster, pipeline diagram |
| `README.md` | Add new commands to feature list |

---

## Implementation Sequence

### Phase 1: Shared assets (no dependencies)
1. Create `shared/skills/gap-analysis/SKILL.md` + references
2. Create `shared/skills/design-review/SKILL.md` + references
3. Create `shared/agents/gap-checker.md`
4. Create `shared/agents/design-reviewer.md`
5. Extend `shared/agents/synthesizer.md` (add gap-analysis mode)
6. Extend `shared/agents/git.md` (add fetch-issues-batch, update-issue ops)

### Phase 2: Plugins
7. Create `plugins/devflow-gap-analysis/` (plugin.json, commands, README)
8. Create `plugins/devflow-plan/` (plugin.json, commands, README)

### Phase 3: Implement modification
9. Add Phase 1.25 to `implement.md` + `implement-teams.md`

### Phase 4: Registration & docs
10. Update `src/cli/plugins.ts` (add 2 plugins)
11. Update `.claude-plugin/marketplace.json` (add 2 entries)
12. Update `CLAUDE.md` + `README.md`

### Phase 5: Build & verify
13. `npm run build` (distributes new skills/agents to plugins)
14. `npm test` (verify no regressions)
15. `node dist/cli.js init` (verify installation)
16. `node dist/cli.js list` (verify new plugins appear)

---

## Verification

### Build verification
- `npm run build` passes (compiles CLI + distributes assets)
- `npm test` passes (existing tests auto-validate: `all skills in shared/skills/ are referenced by at least one plugin` + `all agents in shared/agents/ are referenced by at least one plugin`)
- Plugin counts: 17 → 19 (add gap-analysis + plan)
- Skill count: 26 → 28 (add gap-analysis + design-review)
- Agent count: 10 → 12 (add gap-checker + design-reviewer)
- Existing `has at least 8 plugins` test passes (19 ≥ 8)

### Manual verification
- `node dist/cli.js list` shows both new plugins
- `node dist/cli.js init --plugin=gap-analysis` installs correctly
- `node dist/cli.js init --plugin=plan` installs correctly
- `/gap-analysis --issues 1,2,3` runs the full 5-phase flow
- `/plan #1` runs the full 9-phase flow with design review
- `/implement #1` detects plan in `.docs/plans/` and skips exploration/planning

### Integration test
- Full pipeline: `/specify` → `/gap-analysis` → `/plan` → `/implement` runs end-to-end

File	Change
`plugins/devflow-implement/commands/implement.md`	Add Phase 1.25 (Plan Detection) with staleness warning
`plugins/devflow-implement/commands/implement-teams.md`	Same Phase 1.25 addition
`shared/agents/synthesizer.md`	Add `gap-analysis` mode
`shared/agents/git.md`	Add `fetch-issues-batch` + `update-issue` operations
`shared/skills/docs-framework/SKILL.md`	Add `.docs/plans/` and `.docs/gap-analysis/` directories + persistence rules
`shared/skills/ambient-router/SKILL.md`	Route PLAN intent to `/gap-analysis` and `/plan` suggestions
`shared/skills/ambient-router/references/skill-catalog.md`	Add gap-analysis + design-review to skill-to-intent mapping
`src/cli/plugins.ts`	Register `devflow-gap-analysis` + `devflow-plan`
`.claude-plugin/marketplace.json`	Add 2 marketplace entries
`CLAUDE.md`	Update plugin table, agent/skill counts, command roster, pipeline diagram
`README.md`	Add new commands to feature list

Change	Type	Purpose
`/gap-analysis`	New command + plugin	Cross-artifact spec consistency (standalone, iterative)
`/plan`	New command + plugin	Explore + plan + design review + user approval → stored artifact
`/implement` mod	Phase 1.25 addition	Detect pre-approved plan → skip explore/plan phases

Agent	Check Layers	What It Catches
Consistency	Contradiction detection + comment drift	Conflicting statements across issues; stale comments contradicting bodies
Completeness	Completeness validation + AC testability	Missing schemas, undefined edge cases, vague acceptance criteria
Scope	Ownership clarity + dependency mapping	Same feature in N issues, implicit dependencies not declared
Alignment (DEEP only)	Codebase alignment	Spec assumptions that don't match actual code

Check	Red Flag	From Session Insight
Query cardinality	"for each X, fetch Y" patterns	N+1 Middesk calls caught in review, not planning
Function size	Single step spanning 5+ operations	346-line createEntity handler
Parallelism	Sequential steps with no data dependency	Sequential Firestore reads that could be parallel
Error handling	State mutation without rollback plan	Reorder failure handling was underspecified
Caching	Same data read in multiple steps	Redundant auth/tenant reads
Decomposition	Step touching 3+ layers	Mixed API + DB + UI concerns

File	Change	Why
`shared/skills/docs-framework/SKILL.md`	Add `.docs/plans/` and `.docs/gap-analysis/` directories + agent persistence rules	New output directories need naming conventions
`shared/skills/ambient-router/SKILL.md`	Add `/gap-analysis` and `/plan` to PLAN intent routing	User prompts like "check my issues for consistency" should suggest the command
`shared/skills/ambient-router/references/skill-catalog.md`	Add gap-analysis and design-review to skill-to-intent mapping	Ambient mode needs to know about new skills

feat: add /gap-analysis and /plan commands with /implement plan detection #108

Description

Plan: /gap-analysis + /plan Commands + /implement Plan Detection

Context

Overview: 3 Changes

1. /gap-analysis Command

Plugin: devflow-gap-analysis

Command Flow (5 phases)

Gap-Checker Agent Focus Areas (parallel)

Key Design Decisions (from session insights)

Usage

Output Artifact

2. /plan Command

Plugin: devflow-plan

Command Flow (9 phases)

Design Reviewer Agent

Plan Artifact Format

Usage

Key Design Decisions

3. /implement Modifications

New Phase 1.25: Plan Detection

4. Edge Cases & Side Effects

Plan Staleness

Plan Overwrite

Gap ID Stability (Convergence Tracking)

Large Issue Sets (Context Limits)

Git Agent update-issue is Destructive

Closed/Draft Issues

Missing Acceptance Criteria

Additional Files to Modify (not in original list)

Plugin.json Fix

Partial Agent Failure

Auto-Detect Prior Report

Commands Work Independently

Re-Planning After Implementation Starts

Spec Document Format

Artifact Persistence

Files to Create (14 new files)

New Plugin: devflow-gap-analysis

New Plugin: devflow-plan

New Shared Agents

New Shared Skills

Files to Modify (11 files)

Implementation Sequence

Phase 1: Shared assets (no dependencies)

Phase 2: Plugins

Phase 3: Implement modification

Phase 4: Registration & docs

Phase 5: Build & verify

Verification

Build verification

Manual verification

Integration test

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Plan: `/gap-analysis` + `/plan` Commands + `/implement` Plan Detection

1. `/gap-analysis` Command

Plugin: `devflow-gap-analysis`

2. `/plan` Command

Plugin: `devflow-plan`

3. `/implement` Modifications

Git Agent `update-issue` is Destructive

New Plugin: `devflow-gap-analysis`

New Plugin: `devflow-plan`