agileflow 2.77.0 → 2.78.0

package/src/core/commands/adr.md

@@ -1,9 +1,26 @@
 ---
 description: Create an Architecture Decision Record
 argument-hint: NUMBER=<4-digit> 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"
+    - "Always show preview FIRST, wait for YES/NO confirmation BEFORE writing"
+    - "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-new
+# adr
 
 Create a new Architecture Decision Record.
 
@@ -14,35 +31,56 @@ node .agileflow/scripts/obtain-context.js adr
 ```
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Command**: `adr` - Create Architecture Decision Records (ADRs) documenting architectural choices
+## ⚠️ COMPACT SUMMARY - /agileflow:adr IS ACTIVE
 
-**Quick Usage**:
-```
-/agileflow:adr NUMBER=0042 TITLE="Use PostgreSQL for persistence" CONTEXT="Need reliable ACID database" DECISION="PostgreSQL chosen over MongoDB" CONSEQUENCES="Better data integrity, steeper learning curve"
-```
+**CRITICAL**: You are creating Architecture Decision Records (ADRs) that document architectural choices made in the project.
 
-**What It Does**: Parse inputs → Create ADR file → Show preview → Write if approved
+**ROLE**: ADR Writer
 
-### Tool Usage Examples
+---
 
-**TodoWrite** (to track ADR creation):
-```xml
-<invoke name="TodoWrite">
-<parameter name="content">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</parameter>
-<parameter name="status">in-progress</parameter>
-<parameter name="activeForm">1</parameter>
-</invoke>
-```
+### 🚨 RULE #1: ALL INPUTS REQUIRED
 
-**Write** (to create ADR file):
-```xml
-<invoke name="Write">
-<parameter name="file_path">/full/path/to/docs/03-decisions/adr-0042-postgresql.md</parameter>
-<parameter name="content">---
+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
@@ -53,42 +91,112 @@ tags: [database, architecture]
 # ADR-0042: Use PostgreSQL for persistence
 
 ## Context
-We need a reliable database with ACID guarantees for user data...
+[Why this decision - explain the problem/constraints]
 
 ## Decision
-We will use PostgreSQL as our primary database...
+[What was chosen and why - be specific]
 
 ## Consequences
-- Better data integrity and reliability
-- Team needs PostgreSQL training
-- Slightly higher operational complexity than NoSQL
+### Positive
+- Better data integrity
+- ACID guarantees
+
+### Negative
+- Team needs training
+- Operational complexity
 
 ## Related
-- [ADR-0041: Database selection process](adr-0041-db-selection.md)
-- [US-0055: Database migration](../06-stories/US-0055.md)</parameter>
-</invoke>
+- [ADR-0041](adr-0041-db-selection.md)
+- [US-0055](../06-stories/US-0055.md)
 ```
 
-**AskUserQuestion** (for confirmation):
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{"question": "Create this ADR?", "header": "Preview", "multiSelect": false, "options": [{"label": "Yes, create ADR", "description": "Write ADR-0042 to docs/03-decisions/"}, {"label": "No, abort", "description": "Cancel without creating"}]}]</parameter>
-</invoke>
-```
+---
+
+### 🚨 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 |
 
-**Template Structure**:
-- Frontmatter (number, title, date, status, tags)
-- Context section (why decision needed)
-- Decision section (what was chosen)
-- Consequences section (trade-offs and impacts)
-- Optional links to related docs
+Both are important - readers need full trade-off picture.
 
-**Best Practices**:
-- Number ADRs sequentially (0001, 0002, etc.)
-- Write context before decision (explain the "why")
-- Document both positive and negative consequences
-- Keep concise (1-2 pages max)
-- Link related ADRs and stories
+---
+
+### 🚨 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 -->
 
@@ -120,3 +228,52 @@ ACTIONS
 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`
+
+---
+
+## 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

package/src/core/commands/agent.md

@@ -1,6 +1,22 @@
 ---
 description: Onboard a new agent with profile and contract
 argument-hint: AGENT_ID=<id> ROLE=<role> [TOOLS=<list>] [SCOPE=<dirs>]
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:agent - Agent onboarding with profiles and contracts"
+    - "CRITICAL: Create agent profile markdown file at docs/02-practices/prompts/agents/agent-{AGENT_ID}.md"
+    - "CRITICAL: Update roster.yaml at docs/09-agents/roster.yaml with agent metadata"
+    - "MUST include System Prompt (contract) with scope boundaries, commit rules, test requirements"
+    - "MUST use diff-first approach: show preview, get YES/NO confirmation before writing"
+    - "Agent IDs must be descriptive (AG-UI, AG-API, AG-CI) not generic (AG-001)"
+    - "Profile includes: role, tools, scope directories, story tags, contract rules"
+  state_fields:
+    - agent_id
+    - role
+    - tools_list
+    - scope_directories
+    - scope_story_tags
 ---
 
 # agent-new

package/src/core/commands/assign.md

@@ -1,6 +1,22 @@
 ---
 description: Assign or reassign a story to an owner
 argument-hint: STORY=<US-ID> NEW_OWNER=<id> [NEW_STATUS=<status>] [NOTE=<text>]
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:assign - Story assigner and owner changer"
+    - "MUST update story frontmatter (owner, status, updated timestamp)"
+    - "MUST update docs/09-agents/status.json using jq or Edit tool"
+    - "MUST validate JSON after modification"
+    - "MUST append assign event to docs/09-agents/bus/log.jsonl"
+    - "MUST use AskUserQuestion for user confirmation (YES/NO format)"
+    - "MUST show diff preview before confirming (diff-first pattern)"
+    - "Status values: ready|in-progress|blocked|in-review|done"
+  state_fields:
+    - story_id
+    - current_owner
+    - new_owner
+    - new_status
 ---
 
 # assign
@@ -14,59 +30,134 @@ node .agileflow/scripts/obtain-context.js assign
 ```
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Command**: `assign`
-**Purpose**: Assign or reassign stories to owners with status updates
+## ⚠️ COMPACT SUMMARY - /agileflow:assign IS ACTIVE
 
-**Quick Usage**:
+**CRITICAL**: You assign/reassign stories to owners. This modifies two files + bus log.
+
+---
+
+### 🚨 RULE #1: ALWAYS Update Both Story File AND status.json
+
+**Two-part update required**:
+1. Update story frontmatter (owner, status, updated timestamp)
+2. Update docs/09-agents/status.json (using jq or Edit tool)
+
+### 🚨 RULE #2: 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 #3: ALWAYS Show Diff Preview Before Confirming
+
+**Workflow**:
+1. Parse inputs (STORY, NEW_OWNER, NEW_STATUS, NOTE)
+2. Prepare story frontmatter update
+3. Prepare status.json update
+4. Show unified DIFF preview (story + status.json)
+5. Ask YES/NO confirmation
+6. Only on YES: Execute all updates + append bus message
+
+### 🚨 RULE #4: VALID STATUS TRANSITIONS
+
+Status can transition:
+- `ready` → `in-progress` (starting work)
+- `in-progress` → `blocked` (hit blocker)
+- `in-progress` → `in-review` (finished, ready for review)
+- `blocked` → `in-progress` (blocker resolved)
+- `in-review` → `done` (review complete)
+- Any → `ready` (reset story)
+
+---
+
+## Key Files & Actions
+
+**Input Parameters**:
+```
+STORY=<US-ID>             # e.g., US-0042 (required)
+NEW_OWNER=<id>            # New owner (required)
+NEW_STATUS=<status>       # ready|in-progress|blocked|in-review|done (optional)
+NOTE=<text>               # Brief note for bus message (optional)
 ```
-/agileflow:assign STORY=US-0042 NEW_OWNER=AG-UI NEW_STATUS=in-progress NOTE="Starting work on login form"
+
+**Files Updated**:
+1. docs/06-stories/<EPIC>/<STORY>-<slug>.md (frontmatter)
+2. docs/09-agents/status.json (story entry)
+3. docs/09-agents/bus/log.jsonl (appended event)
+
+**Story Frontmatter Update**:
+```yaml
+owner: AG-UI
+status: in-progress
+updated: 2025-10-22T14:30:00Z
 ```
 
-**What It Does**:
-1. Updates story frontmatter (owner, status, updated timestamp) in `docs/06-stories/**/<STORY>*.md`
-2. Updates `docs/09-agents/status.json` (owner, status, last_update) using jq or Edit tool
-3. Validates JSON after modification (prevents corruption)
-4. Appends "assign" event to `docs/09-agents/bus/log.jsonl`
-
-**Status Values**:
-- `ready` - Story ready to start
-- `in-progress` - Currently being worked on
-- `blocked` - Waiting on dependency
-- `in-review` - Code review in progress
-- `done` - Completed and verified
-
-**JSON Safety Protocol**:
-- **ALWAYS** use jq or Edit tool for JSON operations
-- **NEVER** use echo/cat > status.json (can corrupt JSON)
-- **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
-  ```
-
-**Example Workflow**:
+**status.json Update**:
+```json
+{
+  "stories": {
+    "US-0042": {
+      "owner": "AG-UI",
+      "status": "in-progress",
+      "last_update": "ISO-timestamp"
+    }
+  }
+}
 ```
-1. Story US-0042 created (owner: unassigned, status: ready)
-2. /agileflow:assign STORY=US-0042 NEW_OWNER=AG-UI NEW_STATUS=in-progress
-3. AG-UI works on story
-4. /agileflow:assign STORY=US-0042 NEW_OWNER=AG-UI NEW_STATUS=in-review
-5. Review complete
-6. /agileflow:assign STORY=US-0042 NEW_OWNER=AG-UI NEW_STATUS=done
+
+**Append to bus/log.jsonl**:
+```json
+{"ts":"ISO-timestamp","from":"SYSTEM","type":"assign","from":"<user>","to":"<NEW_OWNER>","story":"<STORY>","status":"<NEW_STATUS>","text":"<NOTE>"}
 ```
 
-**Best Practices**:
-- Always preview changes before confirming (diff-first)
-- Include NOTE for context on status changes
-- Validate JSON after every update
-- Use appropriate status transitions (ready → in-progress → in-review → done)
+---
+
+## Anti-Patterns & Correct Usage
+
+❌ **DON'T**:
+- Update story file without updating status.json
+- Use echo or cat for JSON changes
+- Skip validation after JSON updates
+- Forget to show diff before confirming
+- Use invalid status values
+
+✅ **DO**:
+- Update story frontmatter AND status.json together
+- Use jq for JSON operations
+- Validate with `jq empty` after every write
+- Show diff preview before confirmation
+- Use only valid status values
+
+---
 
-**Tool Usage Examples**:
+## Confirmation Flow
 
-AskUserQuestion:
+1. **Show diff preview**:
+```
+Story: docs/06-stories/EP-0010/US-0042-login-form.md
+-owner: unassigned
++owner: AG-UI
+-status: ready
++status: in-progress
+
+Status: docs/09-agents/status.json
+"US-0042": {
+  -"owner": "unassigned",
+  +"owner": "AG-UI",
+  -"status": "ready",
+  +"status": "in-progress",
+  +"last_update": "ISO-timestamp"
+}
+```
+
+2. **Ask confirmation**:
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
@@ -74,13 +165,26 @@ AskUserQuestion:
   "header": "Confirm Assignment",
   "multiSelect": false,
   "options": [
-    {"label": "Yes, assign", "description": "Update story and status.json"},
+    {"label": "Yes, assign", "description": "Update files"},
     {"label": "No, cancel", "description": "Don't assign"}
   ]
 }]</parameter>
 </invoke>
 ```
 
+3. **On YES**: Execute updates + validate JSON + append bus message
+4. **On NO**: Abort without changes
+
+---
+
+## REMEMBER AFTER COMPACTION
+
+- Updates story frontmatter + status.json + bus log
+- ALWAYS validate JSON after modification
+- ALWAYS show diff before confirming
+- Status values: ready, in-progress, blocked, in-review, done
+- Two-part update: story file + status.json (don't forget either)
+
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/commands/auto.md

@@ -1,6 +1,23 @@
 ---
 description: Auto-generate stories from PRDs, mockups, or specs
-argument-hint: (no arguments)
+argument-hint: SOURCE=<path|url> [EPIC=<id>] [OWNER=<agent>] [AUTO_CREATE=yes|no]
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:auto-story - Auto-generate stories from product artifacts"
+    - "CRITICAL: Use TodoWrite to track 10-step generation process immediately"
+    - "CRITICAL: Always preview BEFORE creating (AUTO_CREATE=no default)"
+    - "MUST generate stories with Given/When/Then Acceptance Criteria format"
+    - "MUST estimate using INVEST: 0.5d (simple) | 1d (standard) | 1.5d (complex) | 2d (refactor)"
+    - "Stories >2d MUST be split into smaller stories"
+    - "MUST create story files, test stubs, update status.json, and bus log"
+    - "Supported sources: PRDs (.md/.pdf), mockups (Figma/PNG), API docs (OpenAPI/Swagger), flows (Mermaid)"
+  state_fields:
+    - source_file
+    - source_type
+    - epic_id
+    - owner_agent
+    - stories_generated
 ---
 
 # auto-story