sdlc-framework 2.1.1 → 3.1.0

package/src/commands/transition.md

@@ -1,99 +0,0 @@
----
-name: sdlc:transition
-description: Transition to the next phase after all plans in a phase complete
-argument-hint: "[phase-name]"
-allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, AskUserQuestion]
----
-
-<objective>
-Transition from the current phase to the next phase within a milestone. Verify phase completeness, update project state, commit the phase, and advance to the next phase.
-
-**When to use:** After /sdlc:close detects the last plan in a phase is done. Can also be run manually to force a phase transition.
-
-**What it does:**
-1. Verify all plans in the current phase are complete (every SPEC has a SUMMARY, all ACs passed).
-2. Cross-check STATE.md, PROJECT.md, and ROADMAP.md for consistency.
-3. Update PROJECT.md with implemented, superseded, and newly discovered requirements.
-4. Advance state to the next phase (or trigger milestone completion if this was the last phase).
-5. Update ROADMAP.md with phase completion details.
-6. Create a git commit marking the phase boundary.
-
-**What happens next:**
-- Next phase exists: Framework directs you to /sdlc:spec for the first plan of the new phase.
-- Last phase in milestone: Framework directs you to /sdlc:close for milestone finalization.
-
-**Critical rule:** No phase transitions without completeness verification. Every plan must have a summary. Every AC must pass. State inconsistencies are surfaced and resolved before advancing.
-</objective>
-
-<execution_context>
-@~/.claude/sdlc-framework/workflows/transition-phase.md
-@.sdlc/STATE.md
-@.sdlc/ROADMAP.md
-@.sdlc/PROJECT.md
-</execution_context>
-
-<context>
-$ARGUMENTS — optional phase name to transition from. If not provided, read from .sdlc/STATE.md current_phase field.
-
-Read these files:
-- .sdlc/STATE.md — current phase, milestone, loop position.
-- .sdlc/ROADMAP.md — phase list, plan counts, next phase identification.
-- .sdlc/PROJECT.md — requirements to update based on completed work.
-- All SUMMARY.md files in the completing phase's directory.
-</context>
-
-<process>
-Follow workflow: @~/.claude/sdlc-framework/workflows/transition-phase.md
-
-Step-by-step:
-
-1. **Verify phase completeness**
-   - Read .sdlc/STATE.md. Confirm loop_position is CLOSE ✓. If not, warn: "Loop not closed. Run /sdlc:close first."
-   - List all SPEC and SUMMARY files in .sdlc/phases/{current_phase}/.
-   - Every SPEC must have a corresponding SUMMARY. If not, block: "Phase transition blocked. Plan {N} has a spec but no summary."
-   - Every SUMMARY must show all ACs passed. If not, block: "Phase transition blocked. Plan {N} has failing ACs."
-
-2. **Verify state consistency**
-   - Cross-check STATE.md, PROJECT.md, and ROADMAP.md:
-     - STATE.md current_milestone matches ROADMAP.md in-progress milestone.
-     - STATE.md current_phase matches the phase being completed.
-     - Prior phases in this milestone are all COMPLETE.
-   - If inconsistency found: display details, offer to auto-fix, ask for confirmation.
-
-3. **Update PROJECT.md**
-   - Read all SUMMARY.md files from the completing phase.
-   - Mark addressed requirements as IMPLEMENTED.
-   - Mark contradicted requirements as SUPERSEDED.
-   - Add newly discovered requirements as NOT STARTED.
-   - Display proposed changes and ask user to confirm before writing.
-
-4. **Advance state to next phase**
-   - Read ROADMAP.md to identify the next phase.
-   - If next phase exists:
-     - Update STATE.md: current_phase, clear current_plan, set loop_position: TRANSITION ✓, set next_required_action: /sdlc:spec.
-     - Update ROADMAP.md: mark completed phase as COMPLETE, set next phase to IN PROGRESS.
-   - If no next phase (last phase in milestone):
-     - Update STATE.md: set next_required_action: /sdlc:close (milestone completion).
-
-5. **Update ROADMAP.md with phase summary**
-   - Add completion date, plan count, hotfix count, key deliverables, and duration.
-
-6. **Create git commit** (if in a git repository)
-   - Stage .sdlc/ files and source files from the phase.
-   - Commit with message: "feat({phase-name}): complete phase {number}"
-
-7. **Output next action**
-   - If next phase exists: end with NEXT ACTION REQUIRED: /sdlc:spec
-   - If milestone complete: end with NEXT ACTION REQUIRED: /sdlc:close
-</process>
-
-<success_criteria>
-- [ ] Phase completeness verified: every SPEC has a SUMMARY, all ACs passed
-- [ ] State consistency checked across STATE.md, PROJECT.md, ROADMAP.md
-- [ ] PROJECT.md updated with implemented, superseded, and new requirements
-- [ ] STATE.md advanced to next phase (or milestone completion)
-- [ ] ROADMAP.md updated with phase completion details and summary
-- [ ] Git commit created at phase boundary (if in a git repo)
-- [ ] If next phase exists: output ends with NEXT ACTION REQUIRED: /sdlc:spec
-- [ ] If milestone complete: output ends with NEXT ACTION REQUIRED: /sdlc:close
-</success_criteria>

package/src/workflows/research.md

@@ -1,219 +0,0 @@
-<purpose>Conduct structured research before writing a specification. Spawns sub-agents to explore the codebase or search the web, saves findings, and routes back to the spec phase with informed context.</purpose>
-<when_to_use>Run when you need to understand existing code patterns, evaluate technical options, or gather external information before committing to a spec. Typically run before /sdlc:spec or when the spec phase reveals unknowns.</when_to_use>
-<required_reading>.sdlc/STATE.md, .sdlc/PROJECT.md</required_reading>
-<loop_context>
-  expected_phase: RESEARCH (pre-spec activity)
-  prior_phase: any (usually between loops or during spec clarification)
-  next_phase: SPEC (research always leads to a spec)
-</loop_context>
-<process>
-
-<step name="define_research_question" priority="first">
-  Ask the user: "What do you need to research? Describe the question or topic."
-
-  Then classify the research type:
-
-  TYPE: CODEBASE_EXPLORATION
-  Indicators: "how does X work in our code", "where is Y implemented", "what pattern does Z use", "find all instances of W"
-  Method: Codebase search agents (Grep, Glob, Read)
-
-  TYPE: WEB_RESEARCH
-  Indicators: "what is the best library for X", "how does Y technology work", "compare options for Z", "what are best practices for W"
-  Method: WebSearch agent
-
-  TYPE: HYBRID
-  Indicators: "how should we implement X" (needs both codebase understanding AND external knowledge)
-  Method: Both codebase and web agents
-
-  Display: "Research type: {type}. Proceeding with {method}."
-
-  WHY: Different research types need different tools. Searching the web for "how is auth implemented in our code" is useless. Searching the codebase for "best JWT library" is equally useless.
-</step>
-
-<step name="spawn_codebase_agents" priority="second">
-  ONLY IF type is CODEBASE_EXPLORATION or HYBRID.
-
-  Spawn an exploration agent with run_in_background: true.
-
-  Agent instruction:
-  ```
-  You are researching the codebase to answer: "{research question}"
-
-  PROJECT CONTEXT:
-  {from PROJECT.md: tech stack, architecture, conventions}
-
-  YOUR TASK:
-  1. Search for files and code related to: {topic}
-     - Use Glob to find files by name pattern
-     - Use Grep to search file contents for relevant patterns
-     - Read key files to understand implementation details
-
-  2. For each relevant finding, record:
-     - File path and line numbers
-     - What the code does
-     - What pattern it follows
-     - How it relates to the research question
-
-  3. Look for:
-     - Existing implementations of similar features
-     - Patterns and conventions used in the codebase
-     - Utilities, helpers, and shared code that could be reused
-     - Test patterns used for similar features
-     - Configuration and setup patterns
-
-  4. Compile findings into a structured summary:
-     - Existing patterns found: {list with file references}
-     - Reusable code: {list of utilities/helpers that apply}
-     - Conventions: {naming, structure, testing patterns}
-     - Gaps: {what does NOT exist yet that would be needed}
-     - Recommendation: {how to approach the implementation based on existing patterns}
-  ```
-
-  WHY: Codebase exploration prevents reinventing the wheel. Finding existing patterns before writing a spec ensures the spec follows conventions.
-</step>
-
-<step name="spawn_web_agents" priority="third">
-  ONLY IF type is WEB_RESEARCH or HYBRID.
-
-  Spawn a web research agent with run_in_background: true.
-
-  Agent instruction:
-  ```
-  You are researching an external topic to inform a specification.
-
-  RESEARCH QUESTION: "{research question}"
-
-  PROJECT CONTEXT:
-  {from PROJECT.md: tech stack — so research is relevant to the stack}
-
-  YOUR TASK:
-  1. Use WebSearch to find information about: {topic}
-  2. Search for:
-     - Official documentation for relevant libraries/tools
-     - Best practices and common patterns
-     - Comparison articles if evaluating options
-     - Known issues, gotchas, and caveats
-     - Security considerations
-
-  3. For each option/approach found:
-     - Name and description
-     - Pros: {advantages}
-     - Cons: {disadvantages}
-     - Maturity: {stable, beta, experimental}
-     - Community: {active, declining, abandoned}
-     - Compatibility with our stack: {yes/no, details}
-
-  4. Compile findings into a structured summary:
-     - Options evaluated: {list}
-     - Recommended option: {which and why}
-     - Key considerations: {trade-offs, risks}
-     - Implementation notes: {relevant details for the spec}
-  ```
-
-  WHY: Web research prevents choosing outdated or inappropriate tools. It also surfaces gotchas that would otherwise be discovered mid-implementation.
-</step>
-
-<step name="review_findings" priority="fourth">
-  Wait for all agents to complete.
-
-  Read and synthesize the results:
-
-  FOR CODEBASE FINDINGS:
-  - Are the patterns consistent? Or are there competing approaches in the codebase?
-  - Is there reusable code? How much can be leveraged?
-  - What gaps need to be filled?
-
-  FOR WEB FINDINGS:
-  - Are the recommended options compatible with our stack?
-  - Do any options conflict with existing patterns?
-  - Are there security concerns?
-
-  FOR HYBRID:
-  - Do the codebase patterns align with external best practices?
-  - Where do they diverge? Is the divergence justified?
-
-  Present the synthesized findings to the user:
-  ```
-  Research Findings: {topic}
-
-  Codebase:
-  - Found {N} relevant patterns
-  - Key pattern: {description} (used in {files})
-  - Reusable: {list of utilities/helpers}
-  - Gap: {what is missing}
-
-  External:
-  - Recommended approach: {option}
-  - Key trade-off: {trade-off}
-  - Risk: {risk}
-
-  Recommendation for spec:
-  {How to approach this in the specification, given both codebase and external findings}
-  ```
-
-  Ask: "Does this answer your question? Any follow-up research needed?"
-
-  IF FOLLOW-UP NEEDED: Return to step 1 with the refined question.
-
-  WHY: Raw agent output needs synthesis. The user should see a coherent recommendation, not a dump of search results.
-</step>
-
-<step name="save_findings" priority="fifth">
-  Create .sdlc/research/{topic-slug}.md:
-
-  ```markdown
-  # Research: {topic}
-
-  ## Question
-  {Original research question}
-
-  ## Date
-  {ISO timestamp}
-
-  ## Type
-  {CODEBASE|WEB|HYBRID}
-
-  ## Codebase Findings
-  {Structured findings from codebase exploration}
-  - Pattern: {description} — {file}:{line}
-  - Reusable: {utility/helper} — {file}
-
-  ## External Findings
-  {Structured findings from web research}
-  - Option: {name} — Pros: {pros}, Cons: {cons}
-
-  ## Synthesis
-  {Combined analysis}
-
-  ## Recommendation
-  {What to do in the spec, and why}
-
-  ## References
-  - {file paths for codebase references}
-  - {URLs for web references}
-  ```
-
-  WHY: Research findings are reusable. A future spec in the same area should read prior research instead of re-doing it. The research/ directory is a knowledge base.
-</step>
-
-<step name="route_to_spec" priority="sixth">
-  Update .sdlc/STATE.md:
-  - Add history entry: "{timestamp} | research | Topic: {topic}. Type: {type}. Findings saved."
-  - next_required_action: /sdlc:spec (if not already set)
-
-  Display:
-  ```
-  Research complete.
-
-  Findings: .sdlc/research/{topic-slug}.md
-
-  The spec phase will use these findings for informed task decomposition.
-
-  NEXT ACTION REQUIRED: /sdlc:spec
-  Run /sdlc:spec to create a specification informed by this research.
-  ```
-
-  WHY: Research without a spec is just reading. The forcing function ensures findings are applied to actual work.
-</step>
-
-</process>

package/src/workflows/transition-phase.md

@@ -1,203 +0,0 @@
-<purpose>Transition from one phase to the next within a milestone. Called automatically by close-phase when the last plan in a phase completes. Verifies completeness, updates project state, and commits the phase.</purpose>
-<when_to_use>Triggered automatically when /sdlc:close detects the last plan in a phase is done. Can also be run manually via /sdlc:transition to force a phase transition.</when_to_use>
-<required_reading>.sdlc/STATE.md, .sdlc/ROADMAP.md, .sdlc/PROJECT.md, all SUMMARY.md files in the completing phase</required_reading>
-<loop_context>
-  expected_phase: TRANSITION (between phases)
-  prior_phase: CLOSE ✓ (last plan in phase)
-  next_phase: first SPEC of the next phase, or milestone completion
-</loop_context>
-<process>
-
-<step name="verify_phase_completeness" priority="first">
-  Read .sdlc/STATE.md. Extract the current phase.
-  Read .sdlc/ROADMAP.md. Get the current phase's plan count.
-
-  List all files in .sdlc/phases/{current_phase}/:
-  - Count *-SPEC.md files (plans created)
-  - Count *-SUMMARY.md files (plans completed)
-  - Count HOTFIX-*-SUMMARY.md files (hotfixes applied)
-
-  VERIFY: Every SPEC.md has a corresponding SUMMARY.md.
-  - If a SPEC exists without a SUMMARY: that plan was not completed.
-  - STOP. Display: "Phase transition blocked. Plan {N} has a spec but no summary. Complete it first."
-
-  VERIFY: Every SUMMARY.md shows all ACs passed.
-  - Read each SUMMARY.md. Check the AC results table.
-  - If any AC is FAIL: STOP. Display: "Phase transition blocked. Plan {N} has failing ACs."
-
-  Display:
-  ```
-  Phase {phase} completeness check:
-  Plans: {N} created, {N} completed
-  Hotfixes: {N}
-  All ACs: PASSED
-  Phase is ready for transition.
-  ```
-
-  WHY: Transitioning with incomplete work means skipping it forever. The completeness check prevents accidental abandonment.
-</step>
-
-<step name="verify_state_consistency" priority="second">
-  Cross-check three state files for consistency:
-
-  STATE.MD:
-  - current_milestone should match ROADMAP.md's in-progress milestone
-  - current_phase should match the phase being completed
-  - loop_position should be CLOSE ✓
-
-  PROJECT.MD:
-  - Tech stack should still be accurate (ask user if uncertain)
-  - Requirements section should reflect what was built
-
-  ROADMAP.MD:
-  - Current phase should show correct plan count
-  - Prior phases in this milestone should all be COMPLETE
-
-  IF INCONSISTENCY FOUND:
-  Display: "State inconsistency: {detail}. Recommend fixing before transitioning."
-  Offer to auto-fix obvious inconsistencies (e.g., plan count mismatch).
-  Ask for user confirmation before applying fixes.
-
-  WHY: State drift accumulates silently. Catching it at phase boundaries prevents compounding errors.
-</step>
-
-<step name="update_project_md" priority="third">
-  Read .sdlc/PROJECT.md.
-
-  Based on the completed phase's summaries:
-
-  A. VALIDATE EXISTING REQUIREMENTS:
-  For each requirement listed in PROJECT.md:
-  - Was it addressed in this phase? (search summaries for related work)
-  - If addressed: mark as IMPLEMENTED with reference to plan number
-  - If not addressed: leave as-is (future phase responsibility)
-
-  B. INVALIDATE OUTDATED REQUIREMENTS:
-  For each requirement:
-  - Does the implementation contradict or supersede it?
-  - If yes: mark as SUPERSEDED with explanation
-
-  C. ADD NEW REQUIREMENTS:
-  From decisions and lessons learned in summaries:
-  - Were new requirements discovered during implementation?
-  - If yes: add them to PROJECT.md with status NOT STARTED
-
-  Display changes to user before writing:
-  ```
-  PROJECT.md updates:
-  - IMPLEMENTED: {requirement} (Plan {N})
-  - SUPERSEDED: {requirement} (replaced by {new approach})
-  - NEW: {requirement} (discovered in Plan {N})
-
-  Apply these changes? (yes/no)
-  ```
-
-  WHY: PROJECT.md must stay current. Stale requirements mislead future specs. New requirements discovered during implementation must be captured or they are forgotten.
-</step>
-
-<step name="update_state_for_next_phase" priority="fourth">
-  Read .sdlc/ROADMAP.md. Identify the next phase in the current milestone.
-
-  IF NEXT PHASE EXISTS:
-    Update .sdlc/STATE.md:
-    - current_phase: {next phase number and name}
-    - current_plan: cleared
-    - loop_position: TRANSITION ✓
-    - next_required_action: /sdlc:spec
-    - Add history entry: "{timestamp} | transition | Phase {old} complete. Transitioning to phase {new}."
-
-    Update .sdlc/ROADMAP.md:
-    - Set completed phase status to COMPLETE with date
-    - Set next phase status to IN PROGRESS
-
-  IF NO NEXT PHASE (this was the last phase in the milestone):
-    Update .sdlc/STATE.md:
-    - loop_position: TRANSITION ✓
-    - next_required_action: /sdlc:close (milestone completion handled inline)
-    - Add history entry: "{timestamp} | transition | Phase {current} complete. Last phase in milestone. Trigger milestone completion."
-
-    Update .sdlc/ROADMAP.md:
-    - Set completed phase status to COMPLETE with date
-
-  WHY: The state machine must always point to exactly one next action. Whether that is the next phase or milestone completion depends on the roadmap.
-</step>
-
-<step name="update_roadmap" priority="fifth">
-  Update .sdlc/ROADMAP.md with phase completion details:
-
-  For the completed phase, update the row:
-  ```
-  | {phase-num} | {name} | COMPLETE ({date}) | {plan-count} |
-  ```
-
-  Add a phase summary note under the milestone:
-  ```
-  #### Phase {number} Summary
-  - Plans executed: {N}
-  - Hotfixes: {N}
-  - Key deliverables: {from summaries}
-  - Duration: {first spec date} to {completion date}
-  ```
-
-  WHY: The roadmap is the high-level progress tracker. Completion details help stakeholders understand velocity and scope.
-</step>
-
-<step name="create_git_commit" priority="sixth">
-  IF the project is a git repository:
-
-  Check: git status for uncommitted changes.
-
-  IF UNCOMMITTED CHANGES EXIST:
-    Stage all .sdlc/ files: git add .sdlc/
-    Stage any source files that were part of the phase
-
-    Create commit:
-    ```
-    feat({phase-name}): complete phase {number}
-
-    Phase {number} ({phase-name}) of milestone {milestone-number} is complete.
-
-    Plans executed: {N}
-    Key deliverables:
-    - {deliverable 1}
-    - {deliverable 2}
-    ```
-
-    Display: "Git commit created: {hash}"
-
-  IF NO UNCOMMITTED CHANGES:
-    Display: "No uncommitted changes to commit."
-
-  WHY: Phase completion is a natural commit point. The commit message documents what was accomplished, making git log useful as a project history.
-</step>
-
-<step name="display_result" priority="seventh">
-  IF NEXT PHASE EXISTS:
-    Display:
-    ```
-    Phase transition complete.
-
-    Completed: Phase {old-number} — {old-name}
-    Plans: {N} executed
-    Starting: Phase {new-number} — {new-name}
-
-    NEXT ACTION REQUIRED: /sdlc:spec
-    Run /sdlc:spec to create the first specification for Phase {new-number}.
-    ```
-
-  IF MILESTONE COMPLETE (no next phase):
-    Display:
-    ```
-    Phase transition complete.
-
-    Completed: Phase {number} — {name} (LAST PHASE)
-    Milestone {milestone-number} — {milestone-name}: ALL PHASES COMPLETE
-
-    NEXT ACTION REQUIRED: /sdlc:close
-    Run /sdlc:close to finalize the milestone.
-    ```
-
-  WHY: The display makes the transition visible. Moving to a new phase is a significant moment — the user should know where they are in the broader plan.
-</step>
-
-</process>