Skip to content

Commit 743871e

Browse files
aRustyDevclaude
aRustyDev
and
claude
committed
feat(plan-commands): Complete Phase 5 integration testing
All test cases pass: - TC1a: Happy Path - Schema-compliant plan validates correctly - TC1b: Failure + Recovery - Missing section detected, --fix-schema adds it - TC2: Legacy Compatibility - merge-convert-skills reviewed with warnings - TC3: Apply Review - Review findings applied to plan - TC4: Edge Cases - Edge cases handled gracefully Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 6feee50 commit 743871e

14 files changed

Lines changed: 1246 additions & 0 deletions

File tree

‎.claude/plans/plan-commands-enhancement/PLAN.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Plan Commands Enhancement
2+
3+
**Created:** 2025-03-16
4+
**Updated:** 2025-03-16
5+
**Owner:** Claude Code AI
6+
7+
Enhance `/context:plan:create`, `/context:plan:review`, and `/context:plan:refine` commands with schema validation, logic gap analysis, and consistency checking.
8+
9+
## Objectives
10+
11+
| # | Objective | Measurable | Success Metric |
12+
|---|-----------|------------|----------------|
13+
| 1 | Enforce consistent plan structure | Yes | 100% of plans created via `/context:plan:create` pass `--validate-schema=strict` |
14+
| 2 | Identify logic gaps in plans | Yes | Review reports include causal/completeness/dependency gaps |
15+
| 3 | Check internal consistency | Yes | Cross-reference validation catches misalignments |
16+
| 4 | Check external consistency | Yes | Plans align with project standards (CLAUDE.md, naming conventions) |
17+
| 5 | Auto-fix schema violations | Yes | `--fix-schema` adds missing required sections with placeholders |
18+
19+
## Current State
20+
21+
| Metric | Current Value | Target Value | Gap |
22+
|--------|---------------|--------------|-----|
23+
| Schema validation | None | Full validation | Missing |
24+
| Logic gap analysis | None | Causal + completeness | Missing |
25+
| Internal consistency | Partial (review.md) | Full cross-ref | Incomplete |
26+
| External consistency | None | Project + industry | Missing |
27+
| Auto-fix capability | None | Schema auto-fix | Missing |
28+
29+
## Required Plan Schema (Preview)
30+
31+
> **Note:** This is a preview. The canonical schema will be defined in Phase 1 deliverable: `context/commands/context/plan/SCHEMA.md`
32+
33+
```yaml
34+
# Required top-level elements
35+
objectives: # Table with Measurable column
36+
currentState: # Table with Current/Target/Gap columns
37+
phases: # Table with ID/Dependencies/Status columns
38+
risks: # Table with Mitigation column
39+
40+
# Required per-phase elements
41+
phase.success: # Checklist format, measurable criteria
42+
phase.deliverables: # Table with Location column
43+
phase.files: # Create/Modify sections
44+
```
45+
46+
## Phases
47+
48+
| ID | Name | Status | Dependencies | Effort | Success Criteria |
49+
|----|------|--------|--------------|--------|------------------|
50+
| phase-0 | Audit Existing Plans | **complete** | - | 1h | Survey of legacy plans, migration guidance |
51+
| phase-1 | Schema Definition | **complete** | phase-0 | 2h | Schema spec documented, validation rules defined |
52+
| phase-2 | Create Command | **complete** | phase-1 | 2h | create.md generates schema-compliant plans |
53+
| phase-3 | Review Command | **complete** | phase-1, phase-2 | 3h | review.md validates schema + gaps + consistency |
54+
| phase-4 | Refine Command | **complete** | phase-2, phase-3 | 2h | refine.md applies fixes with --fix-schema |
55+
| phase-5 | Integration Test | **complete** | phase-2, phase-3, phase-4 | 2h | Full create→review→refine cycle works |
56+
57+
**Total estimated effort:** 12 hours
58+
59+
## Risks
60+
61+
| Risk | Likelihood | Impact | Mitigation |
62+
|------|------------|--------|------------|
63+
| Breaking existing plans | Medium | High | Schema validation optional via flag (`--validate-schema=off`) |
64+
| Over-engineering | Medium | Medium | Start minimal, iterate |
65+
| Inconsistent enforcement | Low | Medium | Single source of truth: SCHEMA.md |
66+
| Changes cause regressions | Low | High | Backup original commands before modification |
67+
68+
## Rollback Strategy
69+
70+
If changes break existing workflows:
71+
72+
1. **Immediate:** Restore original commands from git: `git checkout HEAD~1 -- context/commands/context/plan/`
73+
2. **Graceful degradation:** Use `--validate-schema=off` to bypass new validation
74+
3. **Legacy mode:** Keep old behavior as default, new features opt-in initially
75+
76+
## Timeline
77+
78+
| Milestone | Target | Actual |
79+
|-----------|--------|--------|
80+
| Audit complete | After Phase 0 | 2025-03-16 |
81+
| Schema spec complete | After Phase 1 | 2025-03-16 |
82+
| Create command updated | After Phase 2 | 2025-03-16 |
83+
| Review command updated | After Phase 3 | 2025-03-16 |
84+
| Refine command updated | After Phase 4 | 2025-03-16 |
85+
| Integration tested | After Phase 5 | 2025-03-16 |
86+
87+
## Notes
88+
89+
- Commands are in `context/commands/context/plan/`
90+
- Schema should allow graceful degradation for legacy plans
91+
- SCHEMA.md is the single source of truth for validation rules
92+
- Default validation mode: `warn` (inform but don't block)
93+
- `--validate-schema=strict` intended for CI/formal plans
94+
95+
## Future Enhancements (Out of Scope)
96+
97+
- User-facing documentation for new schema requirements
98+
- Auto-migration tool for bulk legacy plan updates
99+
- IDE/editor integration for schema validation

‎.claude/plans/plan-commands-enhancement/audit/inventory.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Plan Inventory
2+
3+
**Audit Date:** 2025-03-16
4+
**Total Plans:** 7 directories (excluding `.archive`)
5+
6+
## Summary
7+
8+
| Category | Count | Plans |
9+
|----------|-------|-------|
10+
| Compliant | 1 | plan-commands-enhancement |
11+
| Near-compliant | 1 | merge-convert-skills |
12+
| Partial | 1 | sqlite-vec |
13+
| Legacy/Different | 4 | ai-arusty-dev, convert-skill-mcp, features, plugins |
14+
15+
## Detailed Inventory
16+
17+
### 1. plan-commands-enhancement
18+
19+
| Attribute | Value |
20+
|-----------|-------|
21+
| **Category** | Compliant |
22+
| **Structure** | `PLAN.md` + `phase/*.md` |
23+
| **Has Objectives Table** | Yes (with Measurable) |
24+
| **Has Current State** | Yes (with Current/Target/Gap) |
25+
| **Has Phases Table** | Yes (with ID/Dependencies) |
26+
| **Has Risks** | Yes (with Mitigation) |
27+
| **Phase Files Have** | Success Criteria, Deliverables, Files |
28+
| **Migration Needed** | None |
29+
30+
### 2. merge-convert-skills
31+
32+
| Attribute | Value |
33+
|-----------|-------|
34+
| **Category** | Near-compliant |
35+
| **Structure** | `index.md` + `phase/*.md` + `analysis/` + `data/` |
36+
| **Has Objectives Table** | No (has "Goals" prose section) |
37+
| **Has Current State** | Partial (has "Current Status" table but different columns) |
38+
| **Has Phases Table** | Yes (has "Phase Overview" with Effort) |
39+
| **Has Risks** | No |
40+
| **Phase Files Have** | Varies - some have deliverables, none have Files section |
41+
| **Migration Needed** | Rename to PLAN.md, add Objectives table, add Risks, update phases |
42+
43+
### 3. sqlite-vec
44+
45+
| Attribute | Value |
46+
|-----------|-------|
47+
| **Category** | Partial |
48+
| **Structure** | Numbered task files (`00-overview.md` through `07-*.md`) |
49+
| **Has Objectives Table** | No (has "Goal" prose) |
50+
| **Has Current State** | No |
51+
| **Has Phases Table** | No (has "Tasks" table with Blocked By) |
52+
| **Has Risks** | No |
53+
| **Phase Files Have** | Task-specific content, no standard structure |
54+
| **Migration Needed** | Restructure to PLAN.md + phase/, or document as "task list" pattern |
55+
56+
### 4. ai-arusty-dev
57+
58+
| Attribute | Value |
59+
|-----------|-------|
60+
| **Category** | Legacy |
61+
| **Structure** | Two files: `concept-schema.md` (empty), `prd.md` |
62+
| **Has Objectives Table** | No |
63+
| **Has Current State** | No |
64+
| **Has Phases Table** | No |
65+
| **Has Risks** | No |
66+
| **Migration Needed** | Too minimal to migrate - appears to be early draft/notes |
67+
68+
### 5. convert-skill-mcp
69+
70+
| Attribute | Value |
71+
|-----------|-------|
72+
| **Category** | Legacy |
73+
| **Structure** | Single file: `tree-sitter.md` |
74+
| **Has Objectives Table** | No |
75+
| **Has Current State** | No |
76+
| **Has Phases Table** | No |
77+
| **Has Risks** | No |
78+
| **Migration Needed** | Too minimal - appears to be research notes |
79+
80+
### 6. features/
81+
82+
| Attribute | Value |
83+
|-----------|-------|
84+
| **Category** | Legacy (container) |
85+
| **Structure** | Nested directories: `plugin-build-system/`, `plugin-feedback-infrastructure/` |
86+
| **Contains** | Sub-plans with `index.md` + `phase/*.md` pattern |
87+
| **Migration Needed** | Each sub-plan needs individual assessment |
88+
89+
### 7. plugins/
90+
91+
| Attribute | Value |
92+
|-----------|-------|
93+
| **Category** | Legacy (container) |
94+
| **Structure** | Nested directories for each plugin plan |
95+
| **Common Pattern** | `brainstorm.md`, `research.md`, `roadmap.md`, `REPORT.md` |
96+
| **Contains** | 8 plugin plans (asciinema-ops, blog-workflow, browser-extension-dev, design-to-code, job-hunting, mcp-discovery, planning-workflow, skill-dev) |
97+
| **Migration Needed** | Different structure - plugin planning workflow, not general plans |
98+
99+
## Structure Patterns Found
100+
101+
| Pattern | Plans Using It | Schema Compatibility |
102+
|---------|----------------|---------------------|
103+
| `PLAN.md` + `phase/*.md` | plan-commands-enhancement | Full |
104+
| `index.md` + `phase/*.md` | merge-convert-skills, features/* | High (rename index→PLAN) |
105+
| Numbered task files | sqlite-vec | Medium (restructure needed) |
106+
| Research workflow | plugins/* | Low (different purpose) |
107+
| Minimal/notes | ai-arusty-dev, convert-skill-mcp | N/A (not plans) |
108+
109+
## Recommendations
110+
111+
1. **Use as test cases:**
112+
- merge-convert-skills (near-compliant, good for `--fix-schema` testing)
113+
- sqlite-vec (partial, good for edge case testing)
114+
115+
2. **Skip migration:**
116+
- ai-arusty-dev, convert-skill-mcp (too minimal, not real plans)
117+
- plugins/* (different workflow, schema doesn't apply)
118+
119+
3. **Consider for future:**
120+
- Document "plugin planning workflow" as separate pattern
121+
- Document "task list" pattern (sqlite-vec style) as alternative

‎.claude/plans/plan-commands-enhancement/audit/migration-notes.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Migration Notes
2+
3+
**Audit Date:** 2025-03-16
4+
5+
## Key Findings
6+
7+
### 1. Only One Plan Uses New Schema
8+
9+
`plan-commands-enhancement` is the only plan following the new PLAN.md schema. This is expected since we just created it.
10+
11+
### 2. Most Structured Plan: merge-convert-skills
12+
13+
This plan has the richest structure and would benefit most from schema enforcement:
14+
15+
- Already has `index.md` with clear sections
16+
- Has `phase/*.md` files with varying completeness
17+
- Missing: Objectives table, Current State table, Risks, per-phase Files sections
18+
19+
### 3. Different Patterns Serve Different Purposes
20+
21+
| Pattern | Purpose | Migrate? |
22+
|---------|---------|----------|
23+
| PLAN.md + phase/ | Multi-phase implementation plans | Yes (target) |
24+
| brainstorm → research → roadmap | Plugin planning workflow | No (different use case) |
25+
| Numbered task files | Step-by-step guides | Optional |
26+
| Single notes file | Research/exploration | No |
27+
28+
### 4. Schema Validation Should Be Optional
29+
30+
Many existing "plans" are really:
31+
32+
- Research notes (convert-skill-mcp)
33+
- Early drafts (ai-arusty-dev)
34+
- Plugin workflows (plugins/*)
35+
36+
These should not fail schema validation. Recommendation: **default to `--validate-schema=warn`**
37+
38+
## Migration Recommendations
39+
40+
### Migrate: merge-convert-skills
41+
42+
**Effort:** ~30 minutes
43+
44+
**Steps:**
45+
46+
1. Rename `index.md` → `PLAN.md`
47+
2. Add Objectives table (convert Goals prose)
48+
3. Add Current State table (already has similar)
49+
4. Add Risks table
50+
5. Update phase files with Files sections
51+
52+
**Or:** Use as test case for `--fix-schema` auto-migration
53+
54+
### Document Only: sqlite-vec
55+
56+
**Reason:** Task-list structure serves its purpose well
57+
58+
**Action:** Document as alternative "task-list plan" pattern
59+
60+
### Skip: ai-arusty-dev, convert-skill-mcp
61+
62+
**Reason:** Not actually plans - just notes/drafts
63+
64+
**Action:** Consider moving to `.archive/` or `notes/`
65+
66+
### Skip: plugins/*
67+
68+
**Reason:** Uses plugin planning workflow (brainstorm → research → roadmap)
69+
70+
**Action:** Document as separate workflow pattern
71+
72+
### Skip: features/*
73+
74+
**Reason:** Container directory, sub-plans need individual review
75+
76+
**Action:** Review each sub-plan separately if/when they become active
77+
78+
## Validation Mode Recommendations
79+
80+
| Plan Type | Validation Mode | Rationale |
81+
|-----------|-----------------|-----------|
82+
| New plans via `/context:plan:create` | `strict` | Ensure compliance from start |
83+
| Existing implementation plans | `warn` | Show gaps without blocking |
84+
| Research notes | `off` | Not applicable |
85+
| Plugin workflows | `off` | Different pattern |
86+
87+
## Test Cases Selected
88+
89+
For Phase 5 integration testing:
90+
91+
1. **TC2: Legacy Compatibility**
92+
- Use `merge-convert-skills` as near-compliant plan
93+
- Test `--validate-schema=off` and `--validate-schema=warn`
94+
95+
2. **TC4: Edge Cases**
96+
- Use `ai-arusty-dev` as minimal plan
97+
- Use `convert-skill-mcp` as single-file plan
98+
99+
## Schema Design Implications
100+
101+
Based on this audit, the schema should:
102+
103+
1. **Be lenient by default** - Many valid plans don't match the schema
104+
2. **Support index.md OR PLAN.md** - Both conventions exist
105+
3. **Handle missing sections gracefully** - Report, don't fail
106+
4. **Support `--validate-schema=off`** - For non-plan content in plans directory

0 commit comments

Comments
 (0)