agileflow 2.76.0 → 2.78.0

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

@@ -0,0 +1,171 @@
+---
+description: List all Architecture Decision Records
+argument-hint: [STATUS=<status>]
+---
+
+# /agileflow:adr:list
+
+Display all Architecture Decision Records with status and quick actions.
+
+---
+
+## Purpose
+
+Shows all ADRs from `docs/03-decisions/` with:
+- Status (proposed, accepted, deprecated, superseded)
+- Date created
+- Summary
+- Quick action options
+
+**This is a read-only command** - no files are written.
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:adr:list [STATUS=<status>]`
+**Purpose**: Display ADRs with filters and offer quick actions
+
+### Flow
+1. Read docs/03-decisions/ directory
+2. Parse ADR frontmatter for status/date
+3. Display formatted table
+4. Offer actions: view details, create new, update status
+
+### Critical Rules
+- **Read-only**: No file writes
+- **Always offer actions**: End with AskUserQuestion for next steps
+- **Show status clearly**: Color-code by status
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| STATUS | No | Filter by status (proposed, accepted, deprecated, superseded) |
+
+---
+
+## IMMEDIATE ACTIONS
+
+Upon invocation, execute these steps:
+
+### Step 1: Read ADR Directory
+
+```bash
+ls docs/03-decisions/adr-*.md
+```
+
+### Step 2: Parse Each ADR
+
+For each ADR file, extract from frontmatter:
+- number
+- title
+- date
+- status
+- tags (if present)
+
+### Step 3: Apply Filters
+
+If STATUS provided, show only ADRs with that status.
+
+### Step 4: Display ADRs
+
+Format output as table sorted by number:
+
+```markdown
+## Architecture Decision Records
+
+| # | Title | Status | Date | Tags |
+|---|-------|--------|------|------|
+| 0003 | Use PostgreSQL for persistence | accepted | 2024-12-28 | database, architecture |
+| 0002 | Session management approach | accepted | 2024-12-25 | auth, sessions |
+| 0001 | AgileFlow agent system | accepted | 2024-12-20 | agents, architecture |
+
+---
+**Summary**: 3 ADRs (3 accepted, 0 proposed, 0 deprecated)
+
+Statuses:
+- **proposed**: Under discussion, not yet decided
+- **accepted**: Decision made and in effect
+- **deprecated**: No longer applies (superseded or obsolete)
+- **superseded**: Replaced by a newer ADR
+```
+
+### Step 5: Offer Actions
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What would you like to do?",
+  "header": "Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "View ADR details", "description": "Read full ADR with context and consequences"},
+    {"label": "Create new ADR", "description": "Document a new architecture decision"},
+    {"label": "Update ADR status", "description": "Change status of existing ADR"},
+    {"label": "Done", "description": "Exit"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If "View ADR details"**:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which ADR would you like to view?",
+  "header": "Select",
+  "multiSelect": false,
+  "options": [
+    {"label": "ADR-0003: Use PostgreSQL for persistence", "description": "accepted - 2024-12-28"},
+    {"label": "ADR-0002: Session management approach", "description": "accepted - 2024-12-25"},
+    {"label": "ADR-0001: AgileFlow agent system", "description": "accepted - 2024-12-20"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+Then invoke: `/agileflow:adr:view NUMBER=<selected>`
+
+**If "Create new ADR"**:
+Invoke: `/agileflow:adr`
+
+**If "Update ADR status"**:
+Invoke: `/agileflow:adr:update`
+
+---
+
+## Example Usage
+
+```bash
+# List all ADRs
+/agileflow:adr:list
+
+# List only proposed ADRs
+/agileflow:adr:list STATUS=proposed
+
+# List only accepted ADRs
+/agileflow:adr:list STATUS=accepted
+```
+
+---
+
+## Rules
+
+- **Read-only**: No file writes
+- **Parse frontmatter**: Extract status, date, tags from YAML
+- **Show summary**: Include counts by status at the bottom
+- **Always offer actions**: End with next step options
+
+---
+
+## Related Commands
+
+- `/agileflow:adr:view` - View full ADR details
+- `/agileflow:adr` - Create new ADR
+- `/agileflow:adr:update` - Update ADR status
+- `/agileflow:research:analyze` - Analyze research that may lead to ADR

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

@@ -0,0 +1,235 @@
+---
+description: Update ADR status or content
+argument-hint: NUMBER=<4-digit> [STATUS=<status>] [REASON=<text>]
+---
+
+# /agileflow:adr:update
+
+Update an existing ADR's status or add amendments.
+
+---
+
+## Purpose
+
+Allows you to:
+- Change ADR status (proposed → accepted, accepted → deprecated, etc.)
+- Add amendment notes explaining status changes
+- Mark an ADR as superseded by a newer ADR
+- Reactivate deprecated ADRs
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:adr:update NUMBER=<4-digit> [STATUS=<status>] [REASON=<text>]`
+**Purpose**: Update ADR status with optional reason/amendment
+
+### Flow
+1. Read existing ADR
+2. Ask for new status if not provided
+3. Require reason for status change
+4. Show preview of changes
+5. Update file if confirmed
+6. Offer next actions
+
+### Critical Rules
+- **Require reason**: Every status change needs a reason documented
+- **Show preview**: Display changes before writing
+- **Link superseding ADRs**: If superseded, require link to new ADR
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| NUMBER | Yes | ADR number to update (e.g., 0042) |
+| STATUS | No | New status (proposed, accepted, deprecated, superseded) |
+| REASON | No | Reason for the status change |
+| SUPERSEDED_BY | No | If superseding, the new ADR number |
+
+---
+
+## IMMEDIATE ACTIONS
+
+Upon invocation, execute these steps:
+
+### Step 1: Validate and Read ADR
+
+```bash
+cat docs/03-decisions/adr-<NUMBER>-*.md
+```
+
+If file not found, show error and suggest `/agileflow:adr:list`.
+
+### Step 2: Ask for New Status (if not provided)
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What should the new status be for ADR-<NUMBER>?",
+  "header": "Status",
+  "multiSelect": false,
+  "options": [
+    {"label": "accepted", "description": "Decision approved and in effect"},
+    {"label": "deprecated", "description": "No longer applies (but not replaced)"},
+    {"label": "superseded", "description": "Replaced by a newer ADR"},
+    {"label": "proposed", "description": "Back to discussion phase"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 3: Get Reason for Change
+
+Always require a reason:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Why is this ADR being changed to '<STATUS>'?",
+  "header": "Reason",
+  "multiSelect": false,
+  "options": [
+    {"label": "Provide reason", "description": "Enter in 'Other' field (required)"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 4: If Superseded, Get Replacement ADR
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which ADR supersedes this one?",
+  "header": "Replacement",
+  "multiSelect": false,
+  "options": [
+    {"label": "ADR-0045 (latest)", "description": "Most recent ADR"},
+    {"label": "ADR-0044", "description": "Previous ADR"},
+    {"label": "Create new ADR", "description": "I need to create the replacement first"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+If "Create new ADR": Run `/agileflow:adr` first, then return to update this one.
+
+### Step 5: Preview Changes
+
+Show what will be updated:
+
+```markdown
+## ADR-0042 Update Preview
+
+**Current Status**: accepted
+**New Status**: superseded
+
+**Changes to file:**
+
+```diff
+- status: accepted
++ status: superseded
+
++ ## Amendment - 2024-12-30
++
++ **Status changed**: accepted → superseded
++ **Reason**: New requirements made this approach obsolete.
++ **Superseded by**: [ADR-0045](adr-0045-new-approach.md)
+```
+
+### Step 6: Confirm Update
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Apply this update to ADR-<NUMBER>?",
+  "header": "Confirm",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, update ADR", "description": "Apply changes to file"},
+    {"label": "No, cancel", "description": "Discard changes"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 7: Update File
+
+If confirmed:
+1. Update frontmatter status
+2. Append Amendment section with:
+   - Date
+   - Status change (from → to)
+   - Reason
+   - Superseded by link (if applicable)
+
+### Step 8: Offer Next Actions
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "ADR-<NUMBER> updated. What would you like to do next?",
+  "header": "Next Steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "View updated ADR", "description": "See the changes with /agileflow:adr:view"},
+    {"label": "Update another ADR", "description": "Change status of a different ADR"},
+    {"label": "View all ADRs", "description": "Return to /agileflow:adr:list"},
+    {"label": "Done", "description": "Exit"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Status Transitions
+
+| From | To | Common Reasons |
+|------|-----|----------------|
+| proposed | accepted | Team approved, ready to implement |
+| proposed | rejected | Alternative chosen, not viable |
+| accepted | deprecated | No longer relevant, context changed |
+| accepted | superseded | Better approach found, replaced by new ADR |
+| deprecated | accepted | Reconsidered, still valid |
+| superseded | accepted | Replacement didn't work out |
+
+---
+
+## Example Usage
+
+```bash
+# Mark ADR as accepted
+/agileflow:adr:update NUMBER=0042 STATUS=accepted REASON="Team approved after review"
+
+# Mark ADR as superseded
+/agileflow:adr:update NUMBER=0042 STATUS=superseded SUPERSEDED_BY=0045 REASON="New requirements"
+
+# Deprecate an ADR
+/agileflow:adr:update NUMBER=0042 STATUS=deprecated REASON="Context no longer applies"
+
+# Interactive (no arguments)
+/agileflow:adr:update NUMBER=0042
+```
+
+---
+
+## Rules
+
+- **Require reason**: Every status change must have documented reason
+- **Show preview**: Always display changes before writing
+- **Link superseding ADRs**: If superseded, must link to replacement
+- **Preserve history**: Never delete content, always append amendments
+- **Update timestamps**: Set updated date in frontmatter
+
+---
+
+## Related Commands
+
+- `/agileflow:adr:view` - View ADR details
+- `/agileflow:adr:list` - View all ADRs
+- `/agileflow:adr` - Create new ADR

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

@@ -0,0 +1,252 @@
+---
+description: View ADR details with contextual actions
+argument-hint: NUMBER=<4-digit>
+---
+
+# /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
+
+---
+
+<!-- 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