agileflow 2.92.0 → 2.93.0

package/src/core/templates/agent-coordination-pattern.md

@@ -0,0 +1,38 @@
+### AGENT COORDINATION
+
+This agent coordinates with other AgileFlow agents via the bus messaging system.
+
+**Coordination Files**:
+- `docs/09-agents/status.json` - Story statuses and assignments
+- `docs/09-agents/bus/log.jsonl` - Inter-agent messages (append-only)
+
+**When to Send Bus Messages**:
+1. **Status Update**: After changing story status in status.json
+2. **Blocked**: When waiting for another agent's work
+3. **Unblock**: When completing work that unblocks others
+4. **Finding**: When discovering issues that affect other agents
+
+**Bus Message Format**:
+```jsonl
+{"ts":"<ISO-timestamp>","from":"{AGENT_ID}","type":"<type>","story":"<US-ID>","text":"<message>"}
+```
+
+**Message Types**:
+| Type | When to Use | Example |
+|------|-------------|---------|
+| `status` | After status.json update | "Completed implementation, ready for review" |
+| `blocked` | Cannot proceed | "Blocked: waiting for API endpoint from AG-API" |
+| `unblock` | Unblocking another agent | "API ready, unblocking US-0042" |
+| `finding` | Discovered issue | "Finding: Performance issue in component X" |
+| `request` | Requesting help | "Request: Need security review before release" |
+
+**Reading the Bus**:
+On invocation, check last 10 messages for requests or blockers:
+```bash
+tail -10 docs/09-agents/bus/log.jsonl | grep "{AGENT_ID}"
+```
+
+**Coordination with Other Agents**:
+- **Before starting**: Check if your work will unblock others
+- **After completing**: Notify waiting agents via unblock message
+- **On blocker**: Document clearly with blocked message and reference story ID

package/src/core/templates/agileflow-metadata.json

@@ -94,6 +94,31 @@
       "10-research": true
     }
   },
+  "sessions": {
+    "defaultStartupMode": "normal",
+    "startupModes": {
+      "normal": {
+        "label": "Normal",
+        "description": "Standard Claude with permission prompts",
+        "flags": null
+      },
+      "skip-permissions": {
+        "label": "Skip permissions",
+        "description": "claude --dangerously-skip-permissions (trusted mode)",
+        "flags": "--dangerous"
+      },
+      "accept-edits": {
+        "label": "Accept edits only",
+        "description": "claude --permission-mode acceptEdits",
+        "flags": "--claude-args \"--permission-mode acceptEdits\""
+      },
+      "no-claude": {
+        "label": "Don't start Claude",
+        "description": "Create worktree only, start Claude manually",
+        "flags": "--no-claude"
+      }
+    }
+  },
   "git": {
     "initialized": false,
     "remoteConfigured": false,

package/src/core/templates/preserve-rules-common.md

@@ -0,0 +1,107 @@
+# Common Preserve Rules
+
+This template provides standardized preserve rules that can be injected into command frontmatter.
+Commands reference rule sets using `{{RULES:<category>}}` syntax in their preserve_rules.
+
+## Usage
+
+In command frontmatter:
+```yaml
+compact_context:
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:command-name"
+    - "{{RULES:json_operations}}"
+    - "{{RULES:file_preview}}"
+    - "Command-specific rule here"
+```
+
+---
+
+## Rule Categories
+
+### json_operations
+Rules for safe JSON file modifications (status.json, etc.)
+
+```
+- "MUST use Edit tool or jq for JSON operations (never echo/cat > file.json)"
+- "MUST validate JSON after every modification (jq . file.json)"
+```
+
+### file_preview
+Rules for showing previews before writing files
+
+```
+- "MUST show diff preview before confirming writes (diff-first pattern)"
+- "Wait for YES/NO confirmation BEFORE writing any file"
+```
+
+### user_confirmation
+Rules for using AskUserQuestion tool
+
+```
+- "MUST use AskUserQuestion tool for user decisions (not text prompts)"
+- "Options: YES to confirm, NO to cancel, or specific choices"
+```
+
+### todo_tracking
+Rules for using TodoWrite tool
+
+```
+- "MUST create TodoWrite task list for 3+ step workflows"
+- "Mark tasks in_progress before starting, completed when done"
+```
+
+### bus_messaging
+Rules for bus message logging
+
+```
+- "MUST append status update to docs/09-agents/bus/log.jsonl"
+- "Bus format: {ts, from, type, story, text} as single-line JSON"
+```
+
+### plan_mode
+Rules for using EnterPlanMode
+
+```
+- "MUST use EnterPlanMode for non-trivial implementation tasks"
+- "Plan first, get approval, then implement"
+```
+
+### commit_approval
+Rules about git commits
+
+```
+- "NEVER auto-commit without explicit user approval"
+- "Always show diff and ask before committing"
+```
+
+### delegation
+Rules for expert delegation
+
+```
+- "Delegate complex work to domain experts (don't do everything yourself)"
+- "Simple task -> do yourself | Complex single-domain -> spawn expert"
+```
+
+---
+
+## How Injection Works
+
+The content-injector.js processes preserve_rules arrays and expands
+`{{RULES:category}}` markers into the actual rule strings.
+
+Example:
+```yaml
+# Before injection
+preserve_rules:
+  - "ACTIVE COMMAND: /agileflow:story"
+  - "{{RULES:json_operations}}"
+
+# After injection
+preserve_rules:
+  - "ACTIVE COMMAND: /agileflow:story"
+  - "MUST use Edit tool or jq for JSON operations (never echo/cat > file.json)"
+  - "MUST validate JSON after every modification (jq . file.json)"
+```
+
+This eliminates duplication while maintaining readability.

package/src/core/templates/preserve-rules.json

@@ -0,0 +1,42 @@
+{
+  "json_operations": [
+    "MUST use Edit tool or jq for JSON operations (never echo/cat > file.json)",
+    "MUST validate JSON after every modification (jq . file.json)"
+  ],
+  "file_preview": [
+    "MUST show diff preview before confirming writes (diff-first pattern)",
+    "Wait for YES/NO confirmation BEFORE writing any file"
+  ],
+  "user_confirmation": [
+    "MUST use AskUserQuestion tool for user decisions (not text prompts)",
+    "Options: YES to confirm, NO to cancel, or specific choices"
+  ],
+  "todo_tracking": [
+    "MUST create TodoWrite task list for 3+ step workflows",
+    "Mark tasks in_progress before starting, completed when done"
+  ],
+  "bus_messaging": [
+    "MUST append status update to docs/09-agents/bus/log.jsonl",
+    "Bus format: {ts, from, type, story, text} as single-line JSON"
+  ],
+  "plan_mode": [
+    "MUST use EnterPlanMode for non-trivial implementation tasks",
+    "Plan first, get approval, then implement"
+  ],
+  "commit_approval": [
+    "NEVER auto-commit without explicit user approval",
+    "Always show diff and ask before committing"
+  ],
+  "delegation": [
+    "Delegate complex work to domain experts (don't do everything yourself)",
+    "Simple task -> do yourself | Complex single-domain -> spawn expert"
+  ],
+  "research_first": [
+    "Check docs/10-research/ for existing research before starting",
+    "Invoke /agileflow:research:ask if research is missing or stale"
+  ],
+  "status_updates": [
+    "Update docs/09-agents/status.json after each status change",
+    "Valid statuses: ready|in-progress|blocked|in-review|done"
+  ]
+}

package/src/core/templates/proactive-action-spec.md

@@ -0,0 +1,29 @@
+### PROACTIVE ACTION SPECIFICATIONS
+
+This agent performs proactive actions under specific, well-defined conditions. Each action has a clear trigger, detection mechanism, and output format.
+
+**Trigger Types**:
+| Trigger | Detection Mechanism | Example |
+|---------|---------------------|---------|
+| **On Invocation** | Agent is spawned/called | First action when user invokes this agent |
+| **On Story Assignment** | `status.json` shows story with `owner=={AGENT_ID}` | When a story is assigned to this agent |
+| **On Blocker Request** | `bus/log.jsonl` contains request for `{AGENT_ID}` | Another agent requests help |
+| **On Status Change** | Story status changes in `status.json` | Story moves to `in-progress`, `in-review`, etc. |
+
+**Action Execution Pattern**:
+```
+IF [trigger condition detected]
+THEN:
+  1. [Load context - specific files/locations]
+  2. [Analyze/process - specific operations]
+  3. [Output result - specific format]
+  4. [Update state - status.json, bus message]
+```
+
+**Standard Output Formats**:
+- **Status Update**: `{"ts":"<ISO>","from":"{AGENT_ID}","type":"status","story":"<US_ID>","text":"<summary>"}`
+- **Blocked Notice**: `{"ts":"<ISO>","from":"{AGENT_ID}","type":"blocked","story":"<US_ID>","text":"Blocked: <reason>"}`
+- **Unblock Notice**: `{"ts":"<ISO>","from":"{AGENT_ID}","type":"unblock","story":"<US_ID>","text":"Unblocking <target_story>: <reason>"}`
+- **Finding/Alert**: `{"ts":"<ISO>","from":"{AGENT_ID}","type":"finding","story":"<US_ID>","text":"Finding: <details>"}`
+
+**DO NOT** perform proactive actions without a clear trigger. Vague instructions like "proactively do X" require explicit conditions to be actionable.

package/src/core/templates/quality-gate-priorities.md

@@ -0,0 +1,34 @@
+### QUALITY GATE PRIORITIES
+
+Quality gates are grouped by priority. **CRITICAL gates cannot be overridden**, HIGH gates require documentation, and MEDIUM gates can flex for MVP.
+
+| Priority | Meaning | Override? |
+|----------|---------|-----------|
+| **CRITICAL** | Must pass. No exceptions. | ❌ No |
+| **HIGH** | Should pass. Document if skipped. | ⚠️ Yes, with issue |
+| **MEDIUM** | Ideal to pass. Can flex for MVP. | ✅ Yes, note in PR |
+
+**UNIVERSAL CRITICAL GATES** (Apply to ALL agents):
+- [ ] **Tests pass** - All existing tests must pass
+- [ ] **No hardcoded secrets** - API keys, passwords, tokens in env vars only
+- [ ] **No security regressions** - No new vulnerabilities introduced
+- [ ] **Build succeeds** - Project compiles/builds without errors
+
+**UNIVERSAL HIGH GATES** (Apply to ALL agents):
+- [ ] **Test coverage** - New code has meaningful test coverage
+- [ ] **No lint errors** - Code passes linting rules
+- [ ] **No type errors** - TypeScript/type checking passes (if applicable)
+- [ ] **Documentation updated** - README/API docs reflect changes (if applicable)
+
+**UNIVERSAL MEDIUM GATES** (Apply to ALL agents):
+- [ ] **Code review ready** - Self-reviewed, obvious issues fixed
+- [ ] **Performance acceptable** - No obvious performance regressions
+- [ ] **Accessibility basics** - Core accessibility not broken (UI only)
+
+**Override Documentation Format**:
+When overriding a HIGH gate, append to bus message:
+```jsonl
+{"ts":"{TIMESTAMP}","from":"{AGENT_ID}","type":"warning","story":"{STORY_ID}","text":"Override: [GATE NAME] skipped. Reason: [explanation]. Tracked in: [issue link]"}
+```
+
+**Remember**: CRITICAL gates protect the project. Skipping them creates debt that compounds.

package/src/core/templates/session-harness-protocol.md

@@ -0,0 +1,128 @@
+SESSION HARNESS & VERIFICATION PROTOCOL (v2.25.0+)
+
+**CRITICAL**: Session Harness System prevents agents from breaking functionality, claiming work is done when tests fail, or losing context between sessions.
+
+**PRE-IMPLEMENTATION VERIFICATION**
+
+Before starting work on ANY story:
+
+1. **Check Session Harness**:
+   - Look for `docs/00-meta/environment.json`
+   - If exists → Session harness is active
+   - If missing → Suggest `/agileflow:session:init` to user
+
+2. **Test Baseline Check**:
+   - Read `test_status` from story in `docs/09-agents/status.json`
+   - If `"passing"` → Proceed with implementation
+   - If `"failing"` → STOP. Cannot start new work with failing baseline
+   - If `"not_run"` → Run `/agileflow:verify` first to establish baseline
+   - If `"skipped"` → Check why tests are skipped, document override decision
+
+3. **Environment Verification** (if session harness active):
+   - Run `/agileflow:session:resume` to verify environment and load context
+   - Check for regressions (tests were passing, now failing)
+   - If regression detected → Fix before proceeding with new story
+
+**DURING IMPLEMENTATION**
+
+1. **Incremental Testing**:
+   - Run tests frequently during development (not just at end)
+   - Fix test failures immediately (don't accumulate debt)
+   - Use `/agileflow:verify US-XXXX` to check specific story tests
+
+2. **Real-time Status Updates**:
+   - Update `test_status` in status.json as tests are written/fixed
+   - Append bus messages when tests pass milestone checkpoints
+
+**POST-IMPLEMENTATION VERIFICATION**
+
+After completing ANY changes:
+
+1. **Run Full Test Suite**:
+   - Execute `/agileflow:verify US-XXXX` to run tests for the story
+   - Check exit code (0 = success required for completion)
+   - Review test output for warnings or flaky tests
+
+2. **Update Test Status**:
+   - `/agileflow:verify` automatically updates `test_status` in status.json
+   - Verify the update was successful
+   - Expected: `test_status: "passing"` with test results metadata
+
+3. **Regression Check**:
+   - Compare test results to baseline (initial test status)
+   - If new failures introduced → Fix before marking complete
+   - If test count decreased → Investigate deleted tests
+
+4. **Story Completion Requirements**:
+   - Story can ONLY be marked `"in-review"` if `test_status: "passing"`
+   - If tests failing → Story remains `"in-progress"` until fixed
+   - No exceptions unless documented override (see below)
+
+**OVERRIDE PROTOCOL** (Use with extreme caution)
+
+If tests are failing but you need to proceed:
+
+1. **Document Override Decision**:
+   - Append bus message with full explanation:
+   ```jsonl
+   {"ts":"2025-12-06T14:00:00Z","from":"{AGENT_ID}","type":"warning","story":"US-0040","text":"Override: Marking in-review with 1 failing test. Reason: Test requires external service mock, tracked in US-0099."}
+   ```
+
+2. **Update Story Dev Agent Record**:
+   - Add note to "Issues Encountered" section explaining override
+   - Link to tracking issue for the failing test
+   - Document risk and mitigation plan
+
+3. **Create Follow-up Story**:
+   - If test failure is real but out of scope → Create new story
+   - Link dependency in status.json
+   - Notify user of the override and follow-up story
+
+**BASELINE MANAGEMENT**
+
+After completing major milestones (epic complete, sprint end):
+
+1. **Establish Baseline**:
+   - Suggest `/agileflow:baseline "Epic EP-XXXX complete"` to user
+   - Requires: All tests passing, git working tree clean
+   - Creates git tag + metadata for reset point
+
+2. **Baseline Benefits**:
+   - Known-good state to reset to if needed
+   - Regression detection reference point
+   - Deployment readiness checkpoint
+   - Sprint/epic completion marker
+
+**INTEGRATION WITH WORKFLOW**
+
+The verification protocol integrates into the standard workflow:
+
+1. **Before creating feature branch**: Run pre-implementation verification
+2. **Before marking in-review**: Run post-implementation verification
+3. **After merge**: Verify baseline is still passing
+
+**ERROR HANDLING**
+
+If `/agileflow:verify` fails:
+- Read error output carefully
+- Check if test command is configured in `docs/00-meta/environment.json`
+- Verify test dependencies are installed
+- If project has no tests → Suggest `/agileflow:session:init` to set up testing
+- If tests are misconfigured → Coordinate with AG-CI
+
+**SESSION RESUME PROTOCOL**
+
+When resuming work after context loss:
+
+1. **Run Resume Command**: `/agileflow:session:resume` loads context automatically
+2. **Check Session State**: Review `docs/09-agents/session-state.json`
+3. **Verify Test Status**: Ensure no regressions occurred
+4. **Load Previous Insights**: Check Dev Agent Record from previous stories
+
+**KEY PRINCIPLES**
+
+- **Tests are the contract**: Passing tests = feature works as specified
+- **Fail fast**: Catch regressions immediately, not at PR review
+- **Context preservation**: Session harness maintains progress across context windows
+- **Transparency**: Document all override decisions fully
+- **Accountability**: test_status field creates audit trail

package/tools/cli/commands/setup.js

@@ -185,7 +185,12 @@ ${claudeMdMarker}
 
       // Update metadata with config tracking
       try {
-        const metadataPath = path.join(config.directory, config.docsFolder, '00-meta', 'agileflow-metadata.json');
+        const metadataPath = path.join(
+          config.directory,
+          config.docsFolder,
+          '00-meta',
+          'agileflow-metadata.json'
+        );
         if (fs.existsSync(metadataPath)) {
           const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
           const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
@@ -223,8 +228,12 @@ ${claudeMdMarker}
       // Shell alias reload reminder
       if (coreResult.shellAliases?.configured?.length > 0) {
         console.log(chalk.bold('\nShell aliases:'));
-        info(`Reload shell to use: ${chalk.cyan('source ~/.bashrc')} or ${chalk.cyan('source ~/.zshrc')}`);
-        info(`Then run ${chalk.cyan('af')} to start Claude in tmux (or ${chalk.cyan('claude')} for normal)`);
+        info(
+          `Reload shell to use: ${chalk.cyan('source ~/.bashrc')} or ${chalk.cyan('source ~/.zshrc')}`
+        );
+        info(
+          `Then run ${chalk.cyan('af')} to start Claude in tmux (or ${chalk.cyan('claude')} for normal)`
+        );
       }
 
       console.log(chalk.dim(`\nInstalled to: ${coreResult.path}\n`));

package/tools/cli/installers/ide/windsurf.js

@@ -15,7 +15,7 @@ const { BaseIdeSetup } = require('./_base-ide');
  */
 class WindsurfSetup extends BaseIdeSetup {
   constructor() {
-    super('windsurf', 'Windsurf', true);
+    super('windsurf', 'Windsurf', false);
     this.configDir = '.windsurf';
     this.workflowsDir = 'workflows';
   }