agileflow 3.4.3 → 4.0.0-alpha.2

package/src/core/commands/status/undo.md

@@ -1,191 +0,0 @@
----
-description: Undo the last status change for a story (rollback)
-argument-hint: "STORY=<US-ID>"
-compact_context:
-  priority: high
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:status:undo - Rollback story status to previous value"
-    - "{{RULES:json_operations}}"
-    - "{{RULES:user_confirmation}}"
-    - "{{RULES:file_preview}}"
-    - "MUST read bus/log.jsonl to find the last status change"
-    - "MUST show current vs previous status as diff"
-    - "MUST confirm with AskUserQuestion before applying"
-    - "MUST log revert event to bus/log.jsonl with type=status-reverted"
-  state_fields:
-    - story_id
-    - current_status
-    - previous_status
----
-
-# /agileflow:status:undo
-
-Undo the last status change for a story by reading the bus event log to find the previous status.
-
----
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js status:undo
-```
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `/agileflow:status:undo STORY=<US-ID>`
-**Purpose**: Rollback a story's status to its previous value using bus log history
-
-### Flow
-1. Parse STORY parameter (required)
-2. Read bus/log.jsonl to find status change history for the story
-3. Read current status from status.json
-4. Show diff: current status vs previous status
-5. Confirm via AskUserQuestion
-6. Apply rollback to status.json
-7. Log status-reverted event to bus/log.jsonl
-
-### Critical Rules
-- **Bus log sourced**: Previous status comes from bus/log.jsonl history
-- **Diff preview**: Show current vs previous before applying
-- **Confirmation**: Never write without user approval
-- **Bus logging**: Append status-reverted event after rollback
-- **No history = no undo**: If no previous status event found, inform user
-<!-- COMPACT_SUMMARY_END -->
-
----
-
-## Arguments
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| STORY | Yes | Story ID to revert (e.g., US-0042) |
-
----
-
-## IMMEDIATE ACTIONS
-
-### Step 1: Validate Input
-
-If STORY not provided, list recently changed stories from bus log.
-
-### Step 2: Find Previous Status
-
-Read `docs/09-agents/bus/log.jsonl` and find status change events for the given story. Look for events with:
-- `type: "status"` and matching `story` field
-- `type: "assign"` (initial creation = "ready")
-- `type: "status-reverted"` (previous undos)
-
-Parse the log in reverse chronological order to find:
-1. **Current status event** (most recent)
-2. **Previous status event** (the one before that)
-
-If only one status event exists (the initial creation), inform the user:
-```
-No previous status found for US-0042.
-Current status "ready" is the original status from story creation.
-Nothing to undo.
-```
-
-### Step 3: Read Current State
-
-Read story from `docs/09-agents/status.json` to confirm the current status matches what the bus log says.
-
-### Step 4: Show Diff Preview
-
-```markdown
-## Status Undo: US-0042
-
-| | Status |
-|---|--------|
-| Current | in_progress |
-| Revert to | ready |
-
-Based on bus event from 2026-03-01T14:30:00Z:
-  "Story US-0042 status changed to in_progress"
-```
-
-### Step 5: Confirm Rollback
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Revert US-0042 from 'in_progress' back to 'ready'?",
-  "header": "Confirm undo",
-  "multiSelect": false,
-  "options": [
-    {"label": "Yes, revert status (Recommended)", "description": "Change status from in_progress back to ready"},
-    {"label": "No, cancel", "description": "Keep current status"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-### Step 6: Apply Rollback
-
-On confirmation:
-
-1. **Update status.json** using Edit tool:
-   - Set story status to the previous value
-   - Update the `updated` timestamp
-
-2. **Validate JSON**:
-```bash
-node -e "JSON.parse(require('fs').readFileSync('docs/09-agents/status.json','utf8')); console.log('valid')"
-```
-
-3. **Append to bus/log.jsonl**:
-```json
-{"ts":"<ISO>","type":"status-reverted","from":"USER","story":"<STORY>","from_status":"<current>","to_status":"<previous>","text":"Status reverted from <current> to <previous>"}
-```
-
-### Step 7: Confirm Success
-
-```
-US-0042 status reverted: in_progress -> ready
-```
-
----
-
-## Edge Cases
-
-| Scenario | Behavior |
-|----------|----------|
-| No status events in bus log | Check status.json only, inform "no history available" |
-| Story not found | Error: "Story {ID} not found in status.json" |
-| Current status doesn't match bus log | Warn user, show both, ask which to revert to |
-| Multiple rapid changes | Revert to the immediately previous status only |
-
----
-
-## Example Usage
-
-```bash
-# Undo last status change
-/agileflow:status:undo STORY=US-0042
-
-# Typical flow: accidentally marked done, want to go back
-# Before: done -> After: in_progress
-```
-
----
-
-## Rules
-
-- **Always preview**: Show current vs previous status before applying
-- **Always confirm**: Use AskUserQuestion before writes
-- **Always log**: Append status-reverted event to bus/log.jsonl
-- **Always validate**: Check JSON integrity after write
-- **One level**: Only undo one status change at a time (run again for more)
-- **Bus log is source of truth**: Previous status comes from event history
-
----
-
-## Related Commands
-
-- `/agileflow:status` - Update story status
-- `/agileflow:story:view` - View story details
-- `/agileflow:story:edit` - Edit story fields
-- `/agileflow:board` - View kanban board

package/src/core/commands/status.md

@@ -1,423 +0,0 @@
----
-description: Update story status and progress
-phase: pre-story
-argument-hint: "STORY=<US-ID> STATUS=<status> [SUMMARY=<text>] [PR=<url>] [TO=<agent-id>]"
-compact_context:
-  priority: high
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:status - Status updater broadcasting to message bus"
-    - "{{RULES:json_operations}}"
-    - "{{RULES:bus_messaging}}"
-    - "{{RULES:user_confirmation}}"
-    - "{{RULES:file_preview}}"
-    - "{{RULES:status_updates}}"
-    - "MUST escape user text automatically (jq handles escaping)"
-    - "PHASE HANDOFF: Prompt for summary on phase transitions (ready→in-progress, in-progress→in-review, in-review→done)"
-  state_fields:
-    - story_id
-    - current_status
-    - new_status
-    - pr_url
-    - phase_from
-    - phase_to
----
-
-# status
-
-Update story status and broadcast to agents via message bus.
-
----
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js status
-```
-
-This gathers git status, stories/epics, session state, and registers for PreCompact.
-
----
-
-## Context Loading (Documentation)
-
-**PURPOSE**: Immediately load full context before executing any logic.
-
-**ACTIONS**:
-1. Read this command file (`.agileflow/commands/status.md`) in its entirety
-2. Absorb all instructions, rules, and examples
-3. Proceed to execution phase with complete context
-
-**WHY**: Prevents incomplete instruction loading and ensures consistent behavior.
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-
-## ⚠️ COMPACT SUMMARY - /agileflow:status IS ACTIVE
-
-**CRITICAL**: You update story status and broadcast to agents. This command updates core project state.
-
----
-
-### 🚨 RULE #1: ALWAYS Use jq or Edit Tool (NEVER echo/cat >)
-
-**REQUIRED**:
-- ALWAYS use jq for status.json updates (prevents corruption)
-- ALWAYS validate after modification:
-```bash
-if ! jq empty docs/09-agents/status.json 2>/dev/null; then
-  echo "❌ ERROR: status.json is now invalid JSON!"
-  exit 1
-fi
-```
-
-### 🚨 RULE #2: ALWAYS Show Diff Preview Before Confirming
-
-**Workflow**:
-1. Parse inputs (STORY, STATUS, SUMMARY, PR, TO)
-2. Prepare status.json update
-3. Show diff of changes
-4. Ask YES/NO confirmation
-5. Only on YES: Execute update + append bus message
-
-### 🚨 RULE #3: VALID STATUS VALUES ONLY
-
-Status must be one of:
-- `ready` - Story ready to start
-- `in-progress` - Currently being worked on
-- `blocked` - Waiting on dependency
-- `in-review` - Code review/PR in progress
-- `done` - Completed and verified
-
----
-
-## Key Files & Actions
-
-**Input Parameters**:
-```
-STORY=<US-ID>           # e.g., US-0042 (required)
-STATUS=<status>         # ready|in-progress|blocked|in-review|done (required)
-SUMMARY=<text>          # 1-2 lines explaining status (optional)
-PR=<url>                # Pull request URL for in-review (optional)
-TO=<agent-id>           # Recipient agent for bus message (optional)
-```
-
-**Update status.json**:
-```json
-{
-  "stories": {
-    "US-0042": {
-      "status": "in-progress",
-      "phase": "execute",
-      "summary": "Started work on login form",
-      "pr": "https://github.com/.../pull/42",
-      "last_update": "ISO-timestamp"
-    }
-  }
-}
-```
-
-**Phase Field** (auto-set based on status):
-| Status | Phase |
-|--------|-------|
-| ready | plan |
-| in-progress | execute |
-| blocked | execute |
-| in-review | audit |
-| done | complete |
-
-**Append to bus/log.jsonl**:
-```json
-{"ts":"ISO-timestamp","from":"SYSTEM","to":"<TO or ALL>","type":"status","story":"<STORY>","status":"<STATUS>","text":"<SUMMARY>"}
-```
-
----
-
-## Anti-Patterns & Correct Usage
-
-❌ **DON'T**:
-- Use echo or cat to write to status.json
-- Skip validation after JSON changes
-- Use invalid status values (e.g., "in_progress")
-- Forget to show diff before confirming
-- Let user text corrupt JSON (use jq escaping)
-
-✅ **DO**:
-- Use jq for all JSON operations
-- Validate with `jq empty` after every write
-- Use only valid status values
-- Show diff preview before confirmation
-- Let jq handle text escaping automatically
-
----
-
-## Confirmation Flow
-
-1. **Show diff preview**:
-```
-docs/09-agents/status.json
-
-- "status": "ready",
-+ "status": "in-progress",
-+ "phase": "execute",
-+ "summary": "Started work on login form",
-+ "pr": "https://github.com/.../pull/42",
-```
-
-2. **Ask confirmation**:
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Update US-0042 to in-progress?",
-  "header": "Confirm Status Update",
-  "multiSelect": false,
-  "options": [
-    {"label": "Yes, update", "description": "Update status.json and bus log"},
-    {"label": "No, cancel", "description": "Don't update"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-3. **On YES**: Execute update + validate JSON + append bus message
-4. **On NO**: Abort without changes
-
----
-
-## REMEMBER AFTER COMPACTION
-
-- Updates status.json (uses jq for safety)
-- Broadcasts to agents via bus/log.jsonl
-- ALWAYS validate JSON after modification
-- ALWAYS show diff before confirming
-- Status values: ready, in-progress, blocked, in-review, done
-- Text escaping handled automatically by jq
-- **PHASE HANDOFF**: On phase transitions (ready→in-progress, in-progress→in-review, in-review→done), prompt for handoff summary and log to bus/log.jsonl with type "phase_handoff"
-
-<!-- COMPACT_SUMMARY_END -->
-
----
-
-## Prompt
-
-ROLE: Status Updater
-
-INPUTS
-STORY=<US-ID>  STATUS=in-progress|blocked|in-review|done
-SUMMARY=<1–2 lines>  PR=<url optional>  TO=<agent id optional>
-
-ACTIONS
-1) Update docs/09-agents/status.json (status,phase,summary,last_update,pr).
-   - Set phase based on status: ready→plan, in-progress/blocked→execute, in-review→audit, done→complete
-   **CRITICAL**: Always use jq for JSON operations to prevent corruption.
-2) **Validate JSON after update**:
-   ```bash
-   # Validate status.json after modification
-   if ! jq empty docs/09-agents/status.json 2>/dev/null; then
-     echo "❌ ERROR: status.json is now invalid JSON after update!"
-     echo "Fix: Use jq to validate and repair the JSON structure"
-     exit 1
-   fi
-   ```
-3) Append a bus line: {"ts":now,"from":"<self>","to":"<TO or ALL>","type":"status","story":"<STORY>","text":"<SUMMARY>"}.
-
-**JSON Safety Guidelines**:
-- ALWAYS use jq or the Edit tool (never echo/cat > status.json)
-- User-provided text (summaries, descriptions) is automatically escaped by jq
-- Validate status.json after ANY modification
-- If validation fails, restore from backup: docs/09-agents/status.json.backup
-
-Diff-first; YES/NO.
-
----
-
-## Phase Handoff (GSD Integration)
-
-When status transitions indicate a phase change, prompt for a handoff summary to capture context for the next phase.
-
-### Phase Transitions
-
-| Status Change | Phase Transition | Handoff Prompt |
-|--------------|------------------|----------------|
-| ready → in-progress | plan → execute | "What's the plan for implementing this story?" |
-| in-progress → in-review | execute → audit | "What was implemented? Any issues encountered?" |
-| in-review → done | audit → complete | "Final summary: What was delivered?" |
-
-### Handoff Workflow
-
-**Step 1: Detect Phase Transition**
-
-Before updating status, check if this is a phase-changing transition:
-```javascript
-const phaseTransitions = {
-  'ready→in-progress': { from: 'plan', to: 'execute' },
-  'in-progress→in-review': { from: 'execute', to: 'audit' },
-  'in-review→done': { from: 'audit', to: 'complete' }
-};
-const key = `${currentStatus}→${newStatus}`;
-const transition = phaseTransitions[key];
-```
-
-**Step 2: Prompt for Handoff Summary**
-
-If a phase transition is detected, prompt BEFORE the status confirmation:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Phase transition: {{FROM}} → {{TO}}. Summarize what was accomplished:",
-  "header": "Handoff",
-  "multiSelect": false,
-  "options": [
-    {"label": "Enter summary", "description": "Capture context for next phase"},
-    {"label": "Skip handoff", "description": "No summary needed"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-**Step 3: Log Phase Handoff**
-
-If summary provided, append to bus/log.jsonl:
-```json
-{
-  "ts": "2026-01-19T12:00:00Z",
-  "type": "phase_handoff",
-  "story": "US-0130",
-  "from": "plan",
-  "to": "execute",
-  "summary": "User's handoff summary here"
-}
-```
-
-### Example Flow
-
-```
-User: /agileflow:status US-0042 STATUS=in-progress
-
-Claude:
-📋 Phase Transition Detected: plan → execute
-
-Before updating status, let's capture a handoff summary.
-
-[AskUserQuestion: "What's the plan for implementing this story?"]
-
-User: "Adding login form with email/password validation, using React Hook Form"
-
-Claude:
-✅ Handoff captured
-
-docs/09-agents/status.json
-- "status": "ready",
-+ "status": "in-progress",
-+ "last_update": "2026-01-19T12:00:00Z"
-
-[AskUserQuestion: "Update US-0042 to in-progress?"]
-
-User: "Yes, update"
-
-Claude:
-✅ Status updated: US-0042 → in-progress
-✅ Phase handoff logged: plan → execute
-```
-
-### Handoff Prompts by Transition
-
-**plan → execute** (ready → in-progress):
-- "What's the implementation approach?"
-- "Any architectural decisions made?"
-- "Key files to be modified?"
-
-**execute → audit** (in-progress → in-review):
-- "What was implemented?"
-- "Any issues or blockers encountered?"
-- "Tests passing? Coverage notes?"
-
-**audit → complete** (in-review → done):
-- "Final summary of what was delivered"
-- "Any technical debt introduced?"
-- "Lessons learned?"
-
----
-
-## Expected Output
-
-### Successful Status Update
-
-```
-📋 Status Update for US-0042
-
-Current: ready (plan phase)
-New: in-progress (execute phase)
-
-docs/09-agents/status.json
-───────────────────────────
-- "status": "ready",
-- "phase": "plan",
-+ "status": "in-progress",
-+ "phase": "execute",
-+ "summary": "Started work on login form",
-+ "last_update": "2026-01-21T14:30:00Z"
-
-[AskUserQuestion: "Update US-0042 to in-progress?"]
-
-✅ Status updated: US-0042 → in-progress
-✅ Bus message sent to: ALL
-```
-
-### With Phase Handoff
-
-```
-📋 Phase Transition Detected: plan → execute
-
-Before updating status, let's capture a handoff summary.
-
-[AskUserQuestion: "What's the plan for implementing this story?"]
-
-User: "Adding login form with email/password validation"
-
-✅ Handoff captured
-
-docs/09-agents/status.json
-───────────────────────────
-- "status": "ready",
-+ "status": "in-progress",
-+ "summary": "Adding login form with email/password validation"
-
-[AskUserQuestion: "Update US-0042 to in-progress?"]
-
-✅ Status updated: US-0042 → in-progress
-✅ Phase handoff logged: plan → execute
-```
-
-### Validation Error
-
-```
-❌ Invalid status value: "in_progress"
-
-Valid values are:
-  • ready - Story ready to start
-  • in-progress - Currently being worked on
-  • blocked - Waiting on dependency
-  • in-review - Code review/PR in progress
-  • done - Completed and verified
-```
-
-### JSON Corruption Recovery
-
-```
-❌ ERROR: status.json is now invalid JSON after update!
-
-Fix: Restoring from backup: docs/09-agents/status.json.backup
-✅ Backup restored successfully
-```
-
----
-
-## Related Commands
-
-- `/agileflow:board` - Visual kanban board
-- `/agileflow:assign` - Assign stories to owners
-- `/agileflow:blockers` - Track and resolve blockers
-- `/agileflow:story:view` - View story details
-- `/agileflow:handoff` - Document work handoff