agileflow 3.4.3 → 4.0.0-alpha.1

package/src/core/commands/adr/view.md

@@ -1,274 +0,0 @@
----
-description: View ADR details with contextual actions
-argument-hint: "NUMBER=<number>"
-compact_context:
-  priority: medium
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:adr:view - Views ADR with context-aware actions"
-    - "MUST read ADR file from docs/03-decisions/adr-NUMBER-*.md"
-    - "MUST display full ADR content: context, decision, consequences, links"
-    - "MUST offer CONTEXT-AWARE actions based on ADR status"
-    - "STATUS=proposed → Accept, reject, request changes"
-    - "STATUS=accepted → Create stories, supersede, deprecate"
-    - "STATUS=deprecated/superseded → View history, replacement"
-    - "ALWAYS offer next steps via AskUserQuestion"
-  state_fields:
-    - selected_adr_number
-    - adr_status
----
-
-# /agileflow:adr:view
-
-View full ADR details and take contextual actions based on ADR status.
-
----
-
-## Purpose
-
-Displays complete ADR information and offers **context-aware actions** based on the ADR's current status:
-- **proposed** → Accept, reject, request changes
-- **accepted** → Create implementation stories, supersede, deprecate
-- **deprecated** → View history, reactivate if needed
-- **superseded** → View replacement ADR, understand evolution
-
----
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js adr:view
-```
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `/agileflow:adr:view NUMBER=<4-digit>`
-**Purpose**: View ADR details with context-aware action suggestions
-
-### Flow
-1. Read ADR file from docs/03-decisions/
-2. Display full ADR content
-3. Offer actions based on current status
-4. Execute selected action
-
-### Critical Rules
-- **Context-aware actions**: Different options based on ADR status
-- **Show everything**: Context, decision, consequences, links
-- **Always offer next steps**: End with relevant AskUserQuestion
-<!-- COMPACT_SUMMARY_END -->
-
----
-
-## Arguments
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| NUMBER | Yes | ADR number (e.g., 0042) |
-
----
-
-## IMMEDIATE ACTIONS
-
-Upon invocation, execute these steps:
-
-### Step 1: Validate Input
-
-If NUMBER not provided, list recent ADRs:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Which ADR would you like to view?",
-  "header": "Select",
-  "multiSelect": false,
-  "options": [
-    {"label": "ADR-0003: Latest ADR", "description": "accepted"},
-    {"label": "ADR-0002: Previous ADR", "description": "accepted"},
-    {"label": "Show all ADRs", "description": "View full ADR list"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-### Step 2: Read ADR File
-
-```bash
-cat docs/03-decisions/adr-<NUMBER>-*.md
-```
-
-If file not found, show error and suggest `/agileflow:adr:list`.
-
-### Step 3: Display ADR Content
-
-```markdown
-## ADR-0042: Use PostgreSQL for Persistence
-
-**Status**: accepted
-**Date**: 2024-12-28
-**Tags**: database, architecture
-
----
-
-### Context
-
-We need a reliable database with ACID guarantees for user data.
-The application handles financial transactions requiring strong consistency.
-Current SQLite implementation cannot scale to multiple servers.
-
----
-
-### Decision
-
-We will use PostgreSQL as our primary database because:
-- Mature, well-tested ACID compliance
-- Excellent tooling and ecosystem
-- Team has existing experience
-- Supports advanced features (JSONB, full-text search)
-
----
-
-### Consequences
-
-**Positive:**
-- Strong data integrity guarantees
-- Better performance at scale
-- Rich query capabilities
-
-**Negative:**
-- Requires managed database service or self-hosting
-- Team needs PostgreSQL-specific training
-- Migration effort from SQLite
-
----
-
-### Related
-
-- [Research: Database Selection](../10-research/20241225-database-selection.md)
-- [US-0050: Database migration story](../06-stories/EP-0005/US-0050.md)
-- Supersedes: ADR-0010 (Use SQLite)
-```
-
-### Step 4: Offer Context-Aware Actions
-
-**Based on ADR status, show different options:**
-
-#### If STATUS = proposed
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "This ADR is proposed. What would you like to do?",
-  "header": "Actions",
-  "multiSelect": false,
-  "options": [
-    {"label": "Accept this ADR", "description": "Mark as accepted and in effect"},
-    {"label": "Request changes", "description": "Add comments or modify the proposal"},
-    {"label": "Reject this ADR", "description": "Mark as rejected with reason"},
-    {"label": "Back to ADR list", "description": "Return to /agileflow:adr:list"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-**If "Accept"**:
-- Run `/agileflow:adr:update NUMBER=<NUMBER> STATUS=accepted`
-- Ask: "Create implementation stories for this decision?"
-
-#### If STATUS = accepted
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "This ADR is accepted and in effect. What would you like to do?",
-  "header": "Actions",
-  "multiSelect": false,
-  "options": [
-    {"label": "Create implementation stories (Recommended)", "description": "Turn this decision into actionable work"},
-    {"label": "Supersede with new ADR", "description": "Replace with updated decision"},
-    {"label": "Deprecate this ADR", "description": "Mark as no longer applicable"},
-    {"label": "View related research", "description": "See research that led to this decision"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-**If "Create implementation stories"**:
-1. Analyze the ADR's consequences and decision
-2. Ask: "This decision suggests the following work:"
-3. Present potential stories/epic
-4. If confirmed, run `/agileflow:epic` or `/agileflow:story`
-
-**If "Supersede"**:
-- Ask for reason/context for new decision
-- Create new ADR referencing this one
-- Update this ADR status to "superseded"
-- Add link to new ADR
-
-#### If STATUS = deprecated
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "This ADR is deprecated. What would you like to do?",
-  "header": "Actions",
-  "multiSelect": false,
-  "options": [
-    {"label": "View deprecation history", "description": "See why this was deprecated"},
-    {"label": "Reactivate this ADR", "description": "Mark as accepted again"},
-    {"label": "View replacement ADR", "description": "See what superseded this"},
-    {"label": "Back to ADR list", "description": "Return to /agileflow:adr:list"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-#### If STATUS = superseded
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "This ADR was superseded. What would you like to do?",
-  "header": "Actions",
-  "multiSelect": false,
-  "options": [
-    {"label": "View replacement ADR", "description": "See the ADR that replaced this one"},
-    {"label": "View decision evolution", "description": "See how this decision evolved over time"},
-    {"label": "Back to ADR list", "description": "Return to /agileflow:adr:list"}
-  ]
-}]</parameter>
-</invoke>
-```
-
----
-
-## Example Usage
-
-```bash
-# View specific ADR
-/agileflow:adr:view NUMBER=0042
-
-# Will prompt for selection if no number
-/agileflow:adr:view
-```
-
----
-
-## Rules
-
-- **Context-aware**: Actions must match current ADR status
-- **Show everything**: Context, decision, consequences, links
-- **Always offer next steps**: End with relevant action options
-- **Connect to related commands**: Link to stories, research, other ADRs
-
----
-
-## Related Commands
-
-- `/agileflow:adr:list` - View all ADRs
-- `/agileflow:adr` - Create new ADR
-- `/agileflow:adr:update` - Update ADR status
-- `/agileflow:story` - Create implementation story
-- `/agileflow:epic` - Create implementation epic
-- `/agileflow:research:view` - View related research

package/src/core/commands/adr.md

@@ -1,394 +0,0 @@
----
-description: Create an Architecture Decision Record
-phase: planning
-argument-hint: "NUMBER=<number> TITLE=<text> CONTEXT=<text> DECISION=<text> CONSEQUENCES=<text> [LINKS=<text>]"
-compact_context:
-  priority: medium
-  preserve_rules:
-    - "NUMBER is REQUIRED - must be 4-digit sequentially (0001, 0002, etc.)"
-    - "TITLE, CONTEXT, DECISION, CONSEQUENCES all REQUIRED"
-    - "Create ADR file in docs/03-decisions/adr-<NUMBER>-<slug>.md"
-    - "{{RULES:file_preview}}"
-    - "Document BOTH positive and negative consequences"
-    - "Keep ADRs concise: 1-2 pages max"
-    - "Link related ADRs and stories in Related section"
-    - "Use template from @packages/cli/src/core/templates/adr-template.md"
-  state_fields:
-    - adr_number
-    - adr_title
-    - context
-    - decision
-    - consequences
----
-
-# adr
-
-Create a new Architecture Decision Record.
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js adr
-```
-
-<!-- COMPACT_SUMMARY_START -->
-
-## ⚠️ COMPACT SUMMARY - /agileflow:adr IS ACTIVE
-
-**CRITICAL**: You are creating Architecture Decision Records (ADRs) that document architectural choices made in the project.
-
-**ROLE**: ADR Writer
-
----
-
-### 🚨 RULE #1: ALL INPUTS REQUIRED
-
-Always require these inputs. Ask if missing:
-
-| Input | Required? | Example |
-|-------|-----------|---------|
-| NUMBER | YES | `NUMBER=0042` (4-digit, sequential) |
-| TITLE | YES | `TITLE="Use PostgreSQL for persistence"` |
-| CONTEXT | YES | `CONTEXT="Need reliable ACID database..."` |
-| DECISION | YES | `DECISION="PostgreSQL chosen over MongoDB"` |
-| CONSEQUENCES | YES | `CONSEQUENCES="Better integrity, learning curve"` |
-| LINKS | NO | `LINKS="ADR-0041, US-0055"` |
-
-❌ WRONG: Create ADR without CONTEXT or DECISION
-✅ RIGHT: Ask for missing inputs, then proceed
-
----
-
-### 🚨 RULE #2: SEQUENTIAL NUMBERING
-
-ADRs MUST be numbered sequentially (0001, 0002, 0003, etc.):
-
-1. Check existing ADRs in docs/03-decisions/
-2. Find highest number (e.g., 0041)
-3. Next ADR should be 0042
-4. Never skip numbers or reuse numbers
-
-❌ WRONG: Create ADR-0100 when only 0042 exists
-✅ RIGHT: Find next sequential number and use it
-
----
-
-### 🚨 RULE #3: ADR FILE STRUCTURE
-
-Create file at: `docs/03-decisions/adr-<NUMBER>-<slug>.md`
-
-Example: `docs/03-decisions/adr-0042-postgresql.md`
-
-Use template from `@packages/cli/src/core/templates/adr-template.md`:
-```markdown
----
-number: 0042
-title: Use PostgreSQL for persistence
-date: 2025-12-22
-status: accepted
-tags: [database, architecture]
----
-
-# ADR-0042: Use PostgreSQL for persistence
-
-## Context
-[Why this decision - explain the problem/constraints]
-
-## Decision
-[What was chosen and why - be specific]
-
-## Consequences
-### Positive
-- Better data integrity
-- ACID guarantees
-
-### Negative
-- Team needs training
-- Operational complexity
-
-## Related
-- [ADR-0041](adr-0041-db-selection.md)
-- [US-0055](../06-stories/US-0055.md)
-```
-
----
-
-### 🚨 RULE #4: CONTEXT BEFORE DECISION
-
-**ALWAYS explain the "why" in Context section:**
-
-❌ WRONG: "We use PostgreSQL because it's good"
-✅ RIGHT: "Need ACID guarantees for financial transactions. Considered MongoDB (eventual consistency risk), Redis (in-memory limits). PostgreSQL best fit for requirements."
-
-Good context helps future readers understand the trade-offs.
-
----
-
-### 🚨 RULE #5: DOCUMENT BOTH POSITIVE AND NEGATIVE
-
-**ALWAYS document consequences honestly:**
-
-| Type | Examples |
-|------|----------|
-| **Positive** | Performance, maintenance, guarantees |
-| **Negative** | Learning curve, cost, migration effort |
-
-Both are important - readers need full trade-off picture.
-
----
-
-### 🚨 RULE #6: DIFF-FIRST, YES/NO PATTERN
-
-**ALWAYS follow this pattern:**
-
-1. Generate ADR content (don't write yet)
-2. Show preview/diff to user
-3. Ask: "Create this ADR? (YES/NO)"
-4. Only write file if user says YES
-
----
-
-### ANTI-PATTERNS (DON'T DO THESE)
-
-❌ Create ADR with only DECISION (no CONTEXT)
-❌ Reuse or skip ADR numbers
-❌ Write vague consequences ("pros and cons")
-❌ Create multi-page ADRs (keep concise)
-❌ Write ADR without showing preview
-❌ Document only positive consequences
-
-### DO THESE INSTEAD
-
-✅ Explain CONTEXT (the "why") thoroughly
-✅ Use sequential numbering
-✅ Document positive AND negative consequences
-✅ Keep to 1-2 pages max
-✅ Show preview before creating
-✅ Honest about trade-offs
-
----
-
-### WORKFLOW
-
-1. **Input Validation**: Ensure all inputs (ask if missing)
-2. **Check Number**: Verify next sequential ADR
-3. **Generate ADR**: Create from template
-4. **Show Preview**: Display to user
-5. **Confirm**: Ask "Create this ADR? (YES/NO)"
-6. **Write**: Only if approved
-7. **Done**: Show success message
-
----
-
-### KEY FILES TO REMEMBER
-
-| File | Purpose |
-|------|---------|
-| `docs/03-decisions/adr-<NUMBER>-<slug>.md` | ADR file location |
-| `@packages/cli/src/core/templates/adr-template.md` | ADR template |
-
----
-
-### REMEMBER AFTER COMPACTION
-
-- `/agileflow:adr` IS ACTIVE - creating ADRs
-- All inputs required (NUMBER, TITLE, CONTEXT, DECISION, CONSEQUENCES)
-- NUMBER must be sequential 4-digit
-- Always explain CONTEXT (the "why")
-- Document positive AND negative consequences
-- Keep 1-2 pages max
-- Show preview, wait for YES/NO before writing
-
-<!-- COMPACT_SUMMARY_END -->
-
-## Prompt
-
-ROLE: ADR Writer
-
-TODO LIST TRACKING
-**CRITICAL**: Immediately create a todo list using TaskCreate/TaskUpdate tool to track ADR creation:
-```
-1. Parse inputs (NUMBER, TITLE, CONTEXT, DECISION, CONSEQUENCES, LINKS)
-2. Create docs/03-decisions/adr-<NUMBER>-<slug>.md from template
-3. Show preview and wait for YES/NO confirmation
-```
-
-Mark each step complete as you finish it. This ensures nothing is forgotten.
-
-INPUTS
-NUMBER=<4-digit>  TITLE=<Decision Title>
-CONTEXT=<short context>  DECISION=<choice>
-CONSEQUENCES=<trade-offs>  LINKS=<optional bullets>
-
-TEMPLATE
-Use the following ADR template structure:
-@packages/cli/src/core/templates/adr-template.md
-
-ACTIONS
-1) Parse inputs (NUMBER, TITLE, CONTEXT, DECISION, CONSEQUENCES, LINKS)
-2) Create docs/03-decisions/adr-<NUMBER>-<slug>.md from template
-3) Show diff and wait for YES/NO confirmation
-4) Write file if approved
-
----
-
-## POST-CREATION ACTIONS
-
-After successfully creating the ADR, offer next steps:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "ADR-<NUMBER> created! What would you like to do next?",
-  "header": "Next Steps",
-  "multiSelect": false,
-  "options": [
-    {"label": "Create implementation stories (Recommended)", "description": "Turn this decision into actionable work"},
-    {"label": "Link to existing research", "description": "Connect to research that led to this decision"},
-    {"label": "Create another ADR", "description": "Document another architecture decision"},
-    {"label": "View all ADRs", "description": "See full list with /agileflow:adr:list"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-**If "Create implementation stories"**:
-1. Analyze the ADR's decision and consequences
-2. Suggest potential stories/epic based on the decision
-3. If confirmed, run `/agileflow:epic` or `/agileflow:story`
-
-**If "Link to existing research"**:
-1. Run `/agileflow:research:list` to show available research
-2. Select research note
-3. Add reference to ADR: `**Research**: See [Research Title](../10-research/...)`
-
-**If "Create another ADR"**:
-- Re-run `/agileflow:adr` with next number
-
-**If "View all ADRs"**:
-- Run `/agileflow:adr:list`
-
----
-
-## Expected Output
-
-### Successful ADR Creation
-
-```
-📋 Creating ADR: ADR-0042
-
-Checking existing ADRs...
-✅ Next sequential number: 0042
-
-Title: Use PostgreSQL for persistence
-Status: accepted
-
-Files to create:
-───────────────────────────────────
-1. docs/03-decisions/adr-0042-postgresql.md
-
-Preview:
-─────────────────────────────────────────────
----
-number: 0042
-title: Use PostgreSQL for persistence
-date: 2026-01-21
-status: accepted
-tags: [database, architecture]
----
-
-# ADR-0042: Use PostgreSQL for persistence
-
-## Context
-Need reliable ACID-compliant database for financial transactions.
-Evaluated MongoDB (eventual consistency), Redis (memory limits),
-and PostgreSQL (full ACID with JSON support).
-
-## Decision
-Use PostgreSQL 16 with native JSON support for document storage
-while maintaining ACID guarantees.
-
-## Consequences
-### Positive
-- Full ACID compliance for financial data
-- Native JSON/JSONB for flexible schemas
-- Mature ecosystem and tooling
-
-### Negative
-- Team needs PostgreSQL training
-- Slightly more complex operational setup
-- Vertical scaling limitations
-
-## Related
-- [ADR-0041](adr-0041-db-evaluation.md)
-- [US-0055](../06-stories/US-0055.md)
-─────────────────────────────────────────────
-
-[AskUserQuestion: "Create this ADR? (YES/NO)"]
-
-✅ ADR-0042 created successfully!
-   docs/03-decisions/adr-0042-postgresql.md
-
-[AskUserQuestion: "What would you like to do next?"]
-```
-
-### Missing Required Inputs
-
-```
-❌ Missing required inputs
-
-The following inputs are required:
-  • NUMBER - 4-digit sequential ID (e.g., 0042)
-  • TITLE - Decision title
-  • CONTEXT - Why this decision is needed
-  • DECISION - What was chosen
-  • CONSEQUENCES - Trade-offs (positive and negative)
-
-Usage:
-/agileflow:adr NUMBER=0042 TITLE="Use PostgreSQL" CONTEXT="Need ACID..." DECISION="PostgreSQL chosen" CONSEQUENCES="Better integrity, learning curve"
-```
-
-### Non-Sequential Number Warning
-
-```
-⚠️ Non-sequential ADR number
-
-Requested: ADR-0100
-Last ADR: ADR-0042
-Next expected: ADR-0043
-
-Do you want to:
-  1. Use sequential number (0043) - Recommended
-  2. Keep requested number (0100)
-  3. Cancel
-
-[AskUserQuestion: Select option]
-```
-
-### ADR Already Exists
-
-```
-❌ ADR-0042 already exists
-
-Existing ADR:
-  Title: Use PostgreSQL for persistence
-  Date: 2026-01-15
-  Status: accepted
-
-To update this ADR:
-  /agileflow:adr:update NUMBER=0042 STATUS=superseded
-
-To create a new ADR:
-  /agileflow:adr NUMBER=0043 TITLE="..."
-```
-
----
-
-## Related Commands
-
-- `/agileflow:adr:list` - View all ADRs with status
-- `/agileflow:adr:view` - View ADR details with contextual actions
-- `/agileflow:adr:update` - Update ADR status
-- `/agileflow:research:analyze` - Analyze research that may lead to ADR
-- `/agileflow:epic` - Create implementation epic
-- `/agileflow:story` - Create implementation story