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

[dean0x]

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:

# 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 fix: add user-invocable: false to all DevFlow skills #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