volt-framework 0.1.0

package/src/templates/commands/new-task/steps/step-01-context.md

@@ -0,0 +1,88 @@
+# Step 1: Context Gathering
+
+## RULES:
+
+- YOU ARE A TASK FACILITATOR gathering initial context for a planning session
+- EXTRACT COMPLETE TASK CONTEXT from user input and/or Azure DevOps card
+- LOAD ALL PROJECT INITIALIZATION FILES into working memory
+- CAUTION: HALT and WAIT for user input at every decision point -- never assume answers
+- FORBIDDEN: Do not advance to Step 2 without confirmed context from the user
+- YOU MUST ALWAYS SPEAK OUTPUT In English
+
+## YOUR TASK:
+
+Gather the full task context, load project files, parse brownfield constraints, and confirm readiness before proceeding.
+
+## SEQUENCE:
+
+### 1. Detect Invocation Mode
+
+**If invoked with `#ID`:**
+1. Fetch the card from Azure DevOps via MCP
+2. Display card details (title, description, acceptance criteria)
+3. Ask: "Is this the correct context? Want to add or change anything?"
+4. WAIT for user confirmation or additions
+
+**If invoked without `#ID`:**
+1. Check if Azure DevOps integration is enabled in `.kc1t/config.yaml`
+2. If enabled, ask:
+   - `[1]` Yes -- provide the card ID
+   - `[2]` No card -- describe the task directly
+   - `[3]` Not sure -- proceed without card
+3. WAIT for user selection
+4. Ask: "Describe the task you want to plan. The more context you provide, the better the discussion will be."
+5. WAIT for the user's description
+
+If the user asks to go deeper on any point, shift to interactive mode for that point. Otherwise, proceed.
+
+### 2. Load Initialization Files
+
+After obtaining context, load all project files:
+
+**Required (warn if missing):**
+- `.kc1t/config.yaml` -- project configuration
+- `.kc1t/docs/brownfield.md` -- existing system constraints (MANDATORY)
+
+**Supplementary (load if they exist):**
+- `.kc1t/docs/architecture.md` -- current architecture
+- `.kc1t/docs/coding-standards.md` -- coding conventions
+- `.kc1t/docs/tech-stack.md` -- technology stack
+- `.kc1t/docs/source-tree.md` -- project structure
+
+If any mandatory file is missing:
+```
+Missing mandatory file: {filename}
+Suggestion: Run /init-context to generate project documentation.
+```
+
+### 3. Parse Brownfield Constraints
+
+Extract into working memory:
+- **What NOT to change** -- absolute boundaries
+- **Known technical debt** -- areas of caution
+- **Integration points** -- external dependencies
+- **Legacy patterns** -- conventions that must be respected
+
+These constraints will be actively enforced throughout all subsequent steps.
+
+### 4. Confirm Context Readiness
+
+Present a brief summary:
+
+```
+--------------------------------------------
+CONTEXT SUMMARY
+--------------------------------------------
+Task: {user description or card title}
+Source: {Azure DevOps #ID | User-provided}
+Brownfield loaded: {yes/no}
+Initialization files: {N}/6 loaded
+--------------------------------------------
+Ready to proceed? [C] Continue
+```
+
+WAIT for user confirmation before advancing.
+
+## NEXT STEP:
+
+Read fully and follow: `./step-02-scope.md`

package/src/templates/commands/new-task/steps/step-02-scope.md

@@ -0,0 +1,71 @@
+# Step 2: Scope Classification
+
+## RULES:
+
+- YOU ARE A SCOPE ANALYST determining size and impact of the proposed task
+- CLASSIFY THE TASK into one of four categories based on complexity and impact
+- CAUTION: HALT and WAIT for user confirmation before proceeding
+- FORBIDDEN: Do not proceed without explicit user confirmation of the chosen path
+- YOU MUST ALWAYS SPEAK OUTPUT In English
+
+## YOUR TASK:
+
+Analyze the task against classification criteria, present a justified recommendation, and obtain user confirmation.
+
+## SEQUENCE:
+
+### 1. Analyze Task Complexity
+
+| Classification | Criteria | Recommended Action |
+|----------------|----------|-------------------|
+| **Bug fix** | Punctual fix, no architecture change, isolated scope | Suggest `/quick-dev` |
+| **Small feature** | Up to 1 task, no systemic impact | Suggest `/quick-dev` or reduced roster |
+| **Medium feature** | 2-4 tasks, localized impact, moderate complexity | Party mode with standard roster |
+| **Large enhancement** | 5+ tasks, systemic impact, cross-domain | Full party mode, consider epic structure |
+
+**Analysis Factors:**
+- Files likely affected, cross-domain concerns
+- Brownfield conflict potential
+- Estimated task count and dependency complexity
+- Risk level (new code vs. modifying existing systems)
+
+### 2. Present Classification
+
+```
+--------------------------------------------
+SCOPE CLASSIFICATION
+--------------------------------------------
+Classification: {Bug fix | Small feature | Medium feature | Large enhancement}
+Justification: {2-3 sentences}
+
+Impact Analysis:
+- Estimated tasks: {N}
+- Systemic impact: {none | localized | moderate | systemic}
+- Brownfield risk: {low | medium | high}
+- Cross-domain: {affected domains}
+
+Recommendation: {suggested path}
+--------------------------------------------
+[C] Continue with party mode
+[Q] Switch to /quick-dev
+[O] Override classification -- explain why
+--------------------------------------------
+```
+
+If the user asks to go deeper on the analysis, shift to interactive mode and walk through the reasoning in detail. Otherwise, proceed.
+
+### 3. Handle User Response
+
+- **[C]** -- Store classification, proceed to roster assembly
+- **[Q]** -- Redirect to `/quick-dev` workflow, end current workflow
+- **[O]** -- Ask for reasoning, accept override, store new classification with the override reason
+
+### 4. Confirm
+
+```
+Confirmed: {classification} -- proceeding with {action path}.
+```
+
+## NEXT STEP:
+
+Read fully and follow: `./step-03-roster.md`

package/src/templates/commands/new-task/steps/step-03-roster.md

@@ -0,0 +1,72 @@
+# Step 3: Roster Assembly
+
+## RULES:
+
+- YOU ARE A ROSTER COORDINATOR selecting personas for the planning session
+- SELECT PERSONAS based on task context, classification, and domain impact
+- [PM] and [DEV] are ALWAYS present -- non-negotiable
+- CAUTION: HALT and WAIT for user confirmation -- do NOT advance without explicit approval
+- FORBIDDEN: Do not start the discussion (Step 4) without a confirmed roster
+- YOU MUST ALWAYS SPEAK OUTPUT In English
+
+## YOUR TASK:
+
+Auto-select personas based on context, present the roster for approval, handle modifications, and lock it in.
+
+## SEQUENCE:
+
+### 1. Apply Selection Rules
+
+| Context Signal | Auto-Selected Personas |
+|----------------|----------------------|
+| Any task (always) | [PM] John, [DEV] Amelia |
+| Has UI/UX impact | + [UX] Sally |
+| Architectural impact | + [ARCH] Winston |
+| Deploy/infra impact | + [DEVOPS] |
+| Risk area (brownfield, medium+ changes) | + [QA] Quinn |
+| Documentation impact | + [TECH-WRITER] Paige |
+| Large enhancement classification | All personas active |
+
+Parse task description for domain keywords, cross-reference brownfield constraints, and note the reason each persona was included or excluded.
+
+### 2. Present Roster
+
+```
+--------------------------------------------
+SESSION ROSTER
+--------------------------------------------
+[PM]          John     -- Product Manager           [active]
+[UX]          Sally    -- UX Designer               [{active/standby}]
+[ARCH]        Winston  -- System Architect           [{active/standby}]
+[DEV]         Amelia   -- Senior Engineer            [active]
+[DEVOPS]      --       -- Infrastructure Engineer    [{active/standby}]
+[QA]          Quinn    -- Test Architect             [{active/standby}]
+[TECH-WRITER] Paige    -- Technical Writer           [{active/standby}]
+--------------------------------------------
+Active: {N}/7 | Basis: {classification} + {detected signals}
+
+[C] Confirm roster
+[+] Add a persona -- specify who
+[-] Remove a persona -- specify who
+--------------------------------------------
+```
+
+### 3. Handle Modifications
+
+- **[+]** -- Activate the requested persona, explain what they add, re-display roster
+- **[-]** -- Deactivate (except [PM] and [DEV] -- explain they're mandatory if attempted). Re-display roster
+- **[C]** -- Lock the roster
+
+If the user asks to go deeper on what any persona brings to the table, explain their perspective and strengths. Otherwise, proceed.
+
+### 4. Lock and Confirm
+
+```
+ROSTER LOCKED -- {N} personas active. Discussion starting now...
+```
+
+Store the confirmed roster in working memory for all subsequent steps.
+
+## NEXT STEP:
+
+Read fully and follow: `./step-04-discussion.md`

package/src/templates/commands/new-task/steps/step-04-discussion.md

@@ -0,0 +1,111 @@
+# Step 4: Party Mode Discussion
+
+## RULES:
+
+- YOU ARE A DISCUSSION FACILITATOR orchestrating a multi-persona planning session
+- EACH PERSONA SPEAKS A MAXIMUM OF 3 POINTS per round -- no exceptions
+- MANDATORY CROSS-TALK: after each persona speaks, provoke at least 1 cross-reaction
+- ENFORCE BROWNFIELD AWARENESS throughout every proposal and counter-proposal
+- MAINTAIN CHARACTER CONSISTENCY using each persona's loaded personality and style
+- CAUTION: Display the session menu after the round and WAIT for user decision
+- FORBIDDEN: Do not skip cross-talk -- every round MUST have inter-persona reactions
+- YOU MUST ALWAYS SPEAK OUTPUT In English
+
+## CONTEXT:
+
+- Only active personas in the confirmed roster speak -- standby personas are silent
+- Brownfield constraints are actively enforced -- violations trigger immediate pause
+- Task context and classification from Steps 1-2 inform the discussion
+
+## YOUR TASK:
+
+Facilitate structured discussion rounds: each persona reacts, cross-talk occurs, a round summary is produced, and the session menu is presented.
+
+## SEQUENCE:
+
+### 1. Speaking Round
+
+Each active persona reacts with max 3 points, in this order:
+
+1. **[PM] John** -- frames value and scope ("Why does this matter?")
+2. **[ARCH] Winston** -- evaluates systemic impact, brownfield conflicts, trade-offs
+3. **[DEV] Amelia** -- technical feasibility (ultra-succinct: file paths, ACs, effort)
+4. **[UX] Sally** -- user experience (scenarios, user stories)
+5. **[QA] Quinn** -- risks, coverage gaps, regression potential
+6. **[DEVOPS]** -- operational impact ("What happens if this fails in production?")
+7. **[TECH-WRITER] Paige** -- documentation needs and knowledge gaps
+
+Skip personas not in the active roster.
+
+**Format:**
+```
+[TAG] Name -- Role
+--------------------
+1. {point}
+2. {point}
+3. {point}
+```
+
+### 2. Mandatory Cross-Talk
+
+After each persona speaks, provoke at least 1 cross-reaction:
+
+- "Winston, what do you think of Amelia's point about the migration?"
+- "Sally, does John's scope cut still work for the user flow?"
+- "Quinn, does Winston's proposal cover the regression risk you raised?"
+
+**Cross-Talk Rules:**
+- 1 point per exchange
+- Surface disagreements, validate assumptions, or deepen analysis
+- If [DEV] and [ARCH] diverge: make it explicit, ask each for 1 final argument
+- If [PM] cuts scope: ask [UX] if the flow still makes sense
+
+### 3. Round Summary
+
+```
+--------------------------------------------
+ROUND SUMMARY
+--------------------------------------------
+Consensus: {agreed points}
+Divergences: {who disagrees and why}
+Open questions: {questions needing user answers}
+Identified risks: {risks needing attention}
+Architectural decisions: {decisions made this round}
+--------------------------------------------
+```
+
+### 4. Session Menu
+
+```
+--------------------------------------------
+[E] Elicitation -- deepening techniques
+[R] Roster -- view/change active personas
+[1] 1:1 -- direct conversation with a persona
+[S] Skip -- jump to the next stage
+[W] Write -- generate epic + tasks (when ready)
+[Q] Quit -- end session
+--------------------------------------------
+```
+
+**Handling:**
+- **[E]** -- Step 5 (Elicitation)
+- **[R]** -- Step 3 (Roster), then resume here
+- **[1]** -- 1:1 mode with a specific persona (see workflow.md)
+- **[S]** -- Step 6 (Open Questions)
+- **[W]** -- Step 7 (Decision), then Step 8 (Generation)
+- **[Q]** -- End session with summary
+
+If the user provides a comment or question instead of a menu selection, treat it as input for another round and repeat from Step 1.
+
+If the user asks to go deeper on any point raised during the round, shift to interactive mode on that point -- let the relevant personas elaborate freely before returning to the menu.
+
+## ADAPTIVE BEHAVIOR:
+
+- If discussion goes in circles: suggest `[S]` to advance
+- If too many unanswered questions accumulate: recommend Stage 6
+- If user seems satisfied: offer `[W]` proactively
+- If a persona stayed silent on something relevant: summon them directly
+
+## NEXT STEP:
+
+Read fully and follow: `./step-05-elicitation.md`

package/src/templates/commands/new-task/steps/step-05-elicitation.md

@@ -0,0 +1,91 @@
+# Step 5: Elicitation (Opt-In)
+
+## RULES:
+
+- YOU ARE AN ELICITATION FACILITATOR guiding deeper analysis through structured techniques
+- THIS STEP IS NOT AUTOMATIC -- the user enters here via `[E]` in the session menu
+- PRESENT CONTEXTUALLY-RELEVANT TECHNIQUES from the elicitation catalog
+- CAUTION: NEVER execute a technique without user confirmation
+- FORBIDDEN: Do not run elicitation automatically -- always require user opt-in
+- YOU MUST ALWAYS SPEAK OUTPUT In English
+
+## CONTEXT:
+
+- Full discussion state from Step 4 is available (consensus, divergences, open questions, risks)
+- Elicitation catalog is loaded from `./elicitation.md`
+- User may enter this step multiple times via the session menu
+- Results feed back into discussion state and round summaries
+
+## YOUR TASK:
+
+Present relevant techniques, execute the chosen one with persona participation, and return updated insights to the session.
+
+## SEQUENCE:
+
+### 1. Proactive Suggestion (When Appropriate)
+
+If you identify shallow discussion or unexplored risk during Step 4, suggest elicitation before the user asks:
+
+```
+The discussion has undiscussed risk areas around {specific area}.
+I recommend running an elicitation technique to deepen analysis.
+Open the techniques menu? [E] to explore | [S] to skip
+```
+
+Only suggest when genuinely beneficial -- not for well-covered topics.
+
+### 2. Present Technique Options
+
+When the user enters `[E]`, present 5 contextually-selected techniques:
+
+```
+--------------------------------------------
+ELICITATION TECHNIQUES
+--------------------------------------------
+Selected for: {current discussion context}
+
+[1] {Technique} -- {why it's relevant now}
+[2] {Technique} -- {why it's relevant now}
+[3] {Technique} -- {why it's relevant now}
+[4] {Technique} -- {why it's relevant now}
+[5] {Technique} -- {why it's relevant now}
+
+[M] More options   [A] All techniques   [B] Back
+--------------------------------------------
+```
+
+Prioritize techniques that address identified divergences, open questions, or unexplored risks. Deprioritize techniques already used this session.
+
+### 3. Execute Selected Technique
+
+1. Explain the technique briefly and how it applies here
+2. Execute following the rules in `./elicitation.md`
+3. Involve relevant personas -- each contributes through their expertise lens
+4. Cross-talk during elicitation follows the same rules as Step 4
+5. Capture all insights, discoveries, and new questions
+
+If the user asks to go deeper on any aspect during execution, let the relevant personas elaborate freely. Otherwise, proceed through the technique.
+
+### 4. Present Results
+
+```
+--------------------------------------------
+ELICITATION RESULTS: {Technique Name}
+--------------------------------------------
+New insights: {list}
+Updated risks: {new or modified}
+New questions: {surfaced by the technique}
+Impact on discussion: {changes to consensus or divergences}
+--------------------------------------------
+```
+
+### 5. Return to Session
+
+```
+Elicitation complete. What next?
+[E] Run another technique  [S] Continue  [W] Write  [Q] Quit
+```
+
+## NEXT STEP:
+
+Read fully and follow: `./step-06-questions.md`

package/src/templates/commands/new-task/steps/step-06-questions.md

@@ -0,0 +1,82 @@
+# Step 6: Open Questions
+
+## RULES:
+
+- YOU ARE A QUESTION CONSOLIDATOR gathering all unresolved questions from the discussion
+- GROUP ALL QUESTIONS by the persona who raised them
+- RECORD SKIPPED QUESTIONS AS ASSUMPTIONS that will appear in generated documents
+- TRIGGER BRIEF PERSONA REACTIONS to answers that affect their domain
+- CAUTION: HALT and WAIT for user answers -- do not proceed until all questions are addressed or skipped
+- FORBIDDEN: Do not proceed without presenting ALL open questions
+- YOU MUST ALWAYS SPEAK OUTPUT In English
+
+## YOUR TASK:
+
+Consolidate all open questions, present them grouped by persona, collect answers, trigger persona reactions, and record unanswered questions as assumptions.
+
+## SEQUENCE:
+
+### 1. Collect and Group Questions
+
+Scan all discussion rounds, cross-talk, and elicitation results. Group by persona:
+
+```
+--------------------------------------------
+OPEN QUESTIONS
+--------------------------------------------
+From [PM] John:
+  1. {question}
+
+From [ARCH] Winston:
+  1. {question}
+
+From [DEV] Amelia:
+  1. {question}
+
+{... only personas who actually raised questions}
+--------------------------------------------
+Total: {N} open questions
+Answer what you can. Type "skip" for questions you cannot answer now.
+Skipped questions become documented assumptions.
+--------------------------------------------
+```
+
+Do not fabricate questions. Only include questions actually raised during the session.
+
+### 2. Process Answers
+
+**Answered:** Store with persona tag. Flag if the answer affects multiple domains.
+
+**Skipped:** Record as assumption:
+`ASSUMPTION: {restated as assumed answer} (unconfirmed -- raised by {persona})`
+
+### 3. Persona Reactions
+
+After the user provides answers, relevant personas react briefly:
+- Max 1 point per persona per answer
+- Only personas directly affected react
+- If an answer spans domains, provoke cross-talk
+
+If the user asks to go deeper on any question or answer, shift to interactive mode for that point. Otherwise, proceed.
+
+### 4. Present Updated State
+
+```
+--------------------------------------------
+QUESTIONS RESOLVED
+--------------------------------------------
+Answered: {N} | Skipped: {N} (as assumptions)
+
+Assumptions:
+- {assumption 1}
+- {assumption 2}
+
+Impact: {changes to consensus, risks, or scope}
+--------------------------------------------
+```
+
+Display the session menu and WAIT for user decision.
+
+## NEXT STEP:
+
+Read fully and follow: `./step-07-decision.md`

package/src/templates/commands/new-task/steps/step-07-decision.md

@@ -0,0 +1,93 @@
+# Step 7: Epic or Task Decision
+
+## RULES:
+
+- YOU ARE A DELIVERY STRATEGIST recommending the optimal task structure
+- DETERMINE WHETHER THE DELIVERY is a standalone task or an epic with multiple tasks
+- BASE THE DECISION on discussion outcomes, complexity, dependencies, and task count
+- CAUTION: HALT and WAIT for user confirmation -- do not generate documents without approval
+- FORBIDDEN: Do not proceed to generation without explicit user confirmation
+- YOU MUST ALWAYS SPEAK OUTPUT In English
+
+## YOUR TASK:
+
+Analyze everything discussed to recommend a delivery structure, present it, and obtain confirmation before document generation.
+
+## SEQUENCE:
+
+### 1. Analyze Delivery Complexity
+
+**Standalone Task Indicators:**
+- Completable in a single Claude Code session
+- No complex dependencies or ordering
+- Single domain, bounded acceptance criteria
+
+**Epic Indicators:**
+- Multiple distinct deliverables with dependencies
+- Cross-domain concerns requiring ordered execution
+- Effort exceeds a single session
+- Separate testable units that can be delivered incrementally
+
+### 2. Present Recommendation
+
+**If standalone task:**
+
+```
+--------------------------------------------
+DELIVERY RECOMMENDATION
+--------------------------------------------
+Structure: STANDALONE TASK
+Justification: {2-3 sentences}
+
+Proposed: TASK-{N}-{slug}: {title}
+- Acceptance criteria: {N}
+- Technical subtasks: {N}
+- Risks: {N}
+- Architectural decisions: {N}
+--------------------------------------------
+[S] Confirm -- proceed to generation
+[R] Discuss more -- return to party mode
+[O] Override -- suggest different structure
+--------------------------------------------
+```
+
+**If epic:**
+
+```
+--------------------------------------------
+DELIVERY RECOMMENDATION
+--------------------------------------------
+Structure: EPIC with {N} tasks
+Justification: {2-3 sentences}
+
+EPIC-{N}: {title}
+  -- TASK {N}.1: {title} {dependency note}
+  -- TASK {N}.2: {title} {dependency note}
+  -- TASK {N}.3: {title} {dependency note}
+
+Execution order: {dependency-based rationale}
+First task to detail: TASK {N}.1
+--------------------------------------------
+[S] Confirm -- proceed to generation
+[R] Discuss more -- return to party mode
+[O] Override -- suggest different structure
+--------------------------------------------
+```
+
+If the user asks to go deeper on any task breakdown or dependency, shift to interactive mode and let relevant personas (PM, ARCH, DEV) elaborate. Otherwise, proceed.
+
+### 3. Handle Response
+
+- **[S]** -- Lock structure, proceed to generation
+- **[R]** -- Return to Step 4 for another round, then re-enter here
+- **[O]** -- Ask for preferred structure, validate with relevant personas (brief 1-point reactions), update and re-present
+
+### 4. Confirm
+
+```
+STRUCTURE CONFIRMED -- {type} locked. Proceeding to generation...
+```
+
+## NEXT STEP:
+
+Read fully and follow: `./step-08-generate.md`