agileflow 3.4.3 → 4.0.0-alpha.10

package/src/core/templates/product-brief.md

@@ -1,136 +0,0 @@
----
-brief_id: {{BRIEF_ID}}
-topic: {{TOPIC}}
-depth: {{DEPTH}}
-created: {{CREATED}}
-status: draft
-ideation_source: {{IDEATION_SOURCE}}
-research_sources: {{RESEARCH_SOURCES}}
----
-
-# Product Brief: {{TOPIC}}
-
-## Executive Summary
-
-{{EXECUTIVE_SUMMARY}}
-
----
-
-## Problem Statement
-
-### What Problem Are We Solving?
-
-{{PROBLEM_DESCRIPTION}}
-
-### Why Now?
-
-{{WHY_NOW}}
-
-### Who Has This Problem?
-
-{{TARGET_USERS}}
-
----
-
-## User Personas
-
-### Persona 1: {{PERSONA_1_NAME}}
-
-- **Role**: {{PERSONA_1_ROLE}}
-- **Pain Points**: {{PERSONA_1_PAINS}}
-- **Goals**: {{PERSONA_1_GOALS}}
-- **Current Workaround**: {{PERSONA_1_WORKAROUND}}
-
-### Persona 2: {{PERSONA_2_NAME}}
-
-- **Role**: {{PERSONA_2_ROLE}}
-- **Pain Points**: {{PERSONA_2_PAINS}}
-- **Goals**: {{PERSONA_2_GOALS}}
-- **Current Workaround**: {{PERSONA_2_WORKAROUND}}
-
----
-
-## Key Features (MoSCoW)
-
-### MUST HAVE (High-Confidence / Core Value)
-
-| # | Feature | Rationale | Source |
-|---|---------|-----------|--------|
-| 1 | {{MUST_1}} | {{RATIONALE}} | {{SOURCE}} |
-| 2 | {{MUST_2}} | {{RATIONALE}} | {{SOURCE}} |
-
-### SHOULD HAVE (Medium-Confidence / Important)
-
-| # | Feature | Rationale | Source |
-|---|---------|-----------|--------|
-| 1 | {{SHOULD_1}} | {{RATIONALE}} | {{SOURCE}} |
-| 2 | {{SHOULD_2}} | {{RATIONALE}} | {{SOURCE}} |
-
-### COULD HAVE (Nice-to-Have / Differentiators)
-
-| # | Feature | Rationale | Source |
-|---|---------|-----------|--------|
-| 1 | {{COULD_1}} | {{RATIONALE}} | {{SOURCE}} |
-
-### WON'T HAVE (Explicit Out-of-Scope)
-
-| # | Feature | Rationale |
-|---|---------|-----------|
-| 1 | {{WONT_1}} | {{RATIONALE}} |
-
----
-
-## Success Metrics
-
-| Metric | Target | How to Measure |
-|--------|--------|----------------|
-| {{METRIC_1}} | {{TARGET_1}} | {{MEASURE_1}} |
-| {{METRIC_2}} | {{TARGET_2}} | {{MEASURE_2}} |
-| {{METRIC_3}} | {{TARGET_3}} | {{MEASURE_3}} |
-
----
-
-## Business Case (Simple ROI)
-
-- **Effort Estimate**: {{EFFORT_ESTIMATE}}
-- **Expected Benefit**: {{EXPECTED_BENEFIT}}
-- **Payback Period**: {{PAYBACK_PERIOD}}
-- **Confidence Level**: {{ROI_CONFIDENCE}}
-
----
-
-## Competitive Context
-
-### Existing Alternatives
-
-| Alternative | Strengths | Weaknesses | Our Differentiator |
-|-------------|-----------|------------|-------------------|
-| {{ALT_1}} | {{STRENGTHS}} | {{WEAKNESSES}} | {{DIFFERENTIATOR}} |
-| {{ALT_2}} | {{STRENGTHS}} | {{WEAKNESSES}} | {{DIFFERENTIATOR}} |
-
-### Positioning Statement
-
-{{POSITIONING}}
-
----
-
-## Risks and Edge Cases
-
-| Risk | Severity | Likelihood | Mitigation |
-|------|----------|------------|------------|
-| {{RISK_1}} | {{SEV}} | {{LIKE}} | {{MITIGATION}} |
-| {{RISK_2}} | {{SEV}} | {{LIKE}} | {{MITIGATION}} |
-
----
-
-## Technical Considerations
-
-{{TECHNICAL_NOTES}}
-
----
-
-## Next Steps
-
-1. Create epic: `/agileflow:epic "{{TOPIC}}"`
-2. Generate stories: `/agileflow:auto`
-3. Implement: `/agileflow:babysit`

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

@@ -1,34 +0,0 @@
-### 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/research-template.md

@@ -1,44 +0,0 @@
-# Research: {{TITLE}}
-
-**Date**: {{DATE}}
-**Researcher**: {{RESEARCHER}}
-**Status**: {{STATUS}}
-
-## Summary
-{{SUMMARY}}
-
-## Key Findings
-1.
-2.
-3.
-
-## Detailed Analysis
-{{DETAILS}}
-
-## Recommended Approach
-{{RECOMMENDATION}}
-
-## Implementation Steps
-1.
-2.
-3.
-
-## Risks & Considerations
--
-
-## Trade-offs
-| Option | Pros | Cons |
-|--------|------|------|
-|        |      |      |
-
-## Sources
-- [Title](URL) - Retrieved {{DATE}}
--
-
-## Related
-- ADRs:
-- Stories:
-- Epics:
-
-## Notes
-{{NOTES}}

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

@@ -1,128 +0,0 @@
-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/src/core/templates/session-state.json

@@ -1,56 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft-07/schema#",
-  "description": "AgileFlow session state tracking",
-  "schema_version": 3,
-  "current_session": {
-    "id": "sess-20251206-100000",
-    "started_at": "2025-12-06T10:00:00Z",
-    "baseline_verified": false,
-    "initial_test_status": "not_run",
-    "current_story": null,
-    "active_agent": null,
-    "thread_type": "base",
-    "thread_complexity": "routine",
-    "expected_duration_minutes": null
-  },
-  "_thread_type_enum": ["base", "parallel", "chained", "fusion", "big", "long"],
-  "_thread_complexity_enum": ["trivial", "routine", "complex", "exploratory"],
-  "active_command": {
-    "_comment": "Tracks which command (babysit, etc.) is currently active for context preservation across compacts",
-    "name": null,
-    "activated_at": null,
-    "state": {}
-  },
-  "last_session": {
-    "id": null,
-    "ended_at": null,
-    "stories_completed": [],
-    "final_test_status": "not_run",
-    "commits": []
-  },
-  "session_history": [],
-  "batch_loop": {
-    "_comment": "State for batch pmap loop mode - iterative processing with quality gates",
-    "enabled": false,
-    "batch_id": null,
-    "pattern": null,
-    "action": null,
-    "quality_gate": "tests",
-    "current_item": null,
-    "items": {},
-    "summary": {
-      "total": 0,
-      "completed": 0,
-      "in_progress": 0,
-      "pending": 0,
-      "failed": 0
-    },
-    "iteration": 0,
-    "max_iterations": 50,
-    "started_at": null,
-    "completed_at": null,
-    "stopped_reason": null,
-    "last_failure": null
-  },
-  "_batch_item_status_enum": ["pending", "in_progress", "completed", "failed", "skipped"]
-}

package/src/core/templates/story-lifecycle.md

@@ -1,213 +0,0 @@
-# Story Lifecycle
-
-This document describes how stories transition through different states in AgileFlow.
-
----
-
-## State Diagram
-
-```mermaid
-stateDiagram-v2
-    [*] --> draft: create
-
-    draft --> ready: validate (DoR met)
-    draft --> draft: edit
-
-    ready --> in_progress: start work
-    ready --> blocked: dependency issue
-
-    in_progress --> in_review: submit PR
-    in_progress --> blocked: blocker found
-    in_progress --> ready: pause work
-
-    blocked --> ready: unblocked
-    blocked --> in_progress: unblocked (continue)
-
-    in_review --> done: PR merged
-    in_review --> in_progress: changes requested
-
-    done --> [*]
-```
-
----
-
-## Story States
-
-| State | Description | Next Actions |
-|-------|-------------|--------------|
-| **draft** | Story created but not ready for work | Validate, add AC, set estimate |
-| **ready** | Definition of Ready (DoR) met | Start work, assign owner |
-| **in-progress** | Actively being worked on | Complete, submit PR, or pause |
-| **blocked** | Waiting on external dependency | Resolve blocker, escalate |
-| **in-review** | Pull request submitted | Review, approve, merge |
-| **done** | Work complete and merged | Archive, celebrate |
-
----
-
-## State Transitions
-
-### draft → ready
-
-**Trigger**: Story passes Definition of Ready (DoR)
-
-**DoR Checklist**:
-- [ ] Clear acceptance criteria (Given/When/Then)
-- [ ] Estimate provided
-- [ ] Dependencies identified
-- [ ] Owner assigned
-- [ ] Epic linked
-
-**Command**: `/agileflow:story-validate STORY=US-XXXX`
-
----
-
-### ready → in-progress
-
-**Trigger**: Developer starts work
-
-**Actions**:
-1. Update status.json: `status: "in-progress"`
-2. Set phase to `execute`
-3. Log to bus/log.jsonl
-
-**Command**: `/agileflow:status STORY=US-XXXX STATUS=in-progress`
-
----
-
-### in-progress → in-review
-
-**Trigger**: Pull request created
-
-**Actions**:
-1. Update status.json: `status: "in-review"`
-2. Set phase to `audit`
-3. Add PR link
-4. Log to bus/log.jsonl
-
-**Command**: `/agileflow:status STORY=US-XXXX STATUS=in-review PR=<url>`
-
----
-
-### in-review → done
-
-**Trigger**: PR merged to main
-
-**Actions**:
-1. Update status.json: `status: "done"`
-2. Set phase to `complete`
-3. Log completion to bus/log.jsonl
-4. Auto-archive after 7 days
-
-**Command**: `/agileflow:status STORY=US-XXXX STATUS=done`
-
----
-
-### → blocked
-
-**Trigger**: External dependency or blocker found
-
-**Actions**:
-1. Update status.json: `status: "blocked"`
-2. Add blocker reason
-3. Log to bus/log.jsonl
-4. Notify dependent teams
-
-**Command**: `/agileflow:status STORY=US-XXXX STATUS=blocked SUMMARY="Waiting on API keys"`
-
----
-
-## Phase Mapping
-
-Stories have both a **status** and a **phase**. Phases group statuses for high-level tracking:
-
-| Status | Phase | Description |
-|--------|-------|-------------|
-| draft | plan | Planning and scoping |
-| ready | plan | Ready for planning/assignment |
-| in-progress | execute | Active development |
-| blocked | execute | Blocked but in execute phase |
-| in-review | audit | Quality review |
-| done | complete | Work finished |
-
----
-
-## WIP Limits
-
-AgileFlow enforces Work-In-Progress (WIP) limits to prevent overload:
-
-- **Per Agent**: Max 2 stories in `in-progress` + `in-review`
-- **Per Epic**: Configurable, typically 5-10 concurrent stories
-
-**Violation handling**:
-```
-⚠️ WIP Limit Exceeded
-
-AG-UI has 3 stories in progress (limit: 2):
-  - US-0042: Login Form
-  - US-0043: Profile Page
-  - US-0044: Dashboard
-
-Complete or pause a story before starting new work.
-```
-
----
-
-## Lifecycle in status.json
-
-```json
-{
-  "stories": {
-    "US-0042": {
-      "id": "US-0042",
-      "title": "Login Form with Validation",
-      "epic": "EP-0010",
-      "owner": "AG-UI",
-      "status": "in-progress",
-      "phase": "execute",
-      "estimate": "2h",
-      "deps": ["US-0041"],
-      "created": "2026-01-20T10:00:00Z",
-      "updated": "2026-01-21T14:30:00Z",
-      "history": [
-        {"status": "draft", "ts": "2026-01-20T10:00:00Z"},
-        {"status": "ready", "ts": "2026-01-20T11:00:00Z"},
-        {"status": "in-progress", "ts": "2026-01-21T09:00:00Z"}
-      ]
-    }
-  }
-}
-```
-
----
-
-## Bus Messages
-
-State transitions are logged to `docs/09-agents/bus/log.jsonl`:
-
-```jsonl
-{"ts":"2026-01-21T09:00:00Z","type":"status","from":"AG-UI","to":"ALL","story":"US-0042","status":"in-progress","text":"Started work on login form"}
-{"ts":"2026-01-21T14:30:00Z","type":"status","from":"AG-UI","to":"ALL","story":"US-0042","status":"in-review","pr":"https://github.com/.../pull/42"}
-{"ts":"2026-01-21T16:00:00Z","type":"status","from":"AG-UI","to":"ALL","story":"US-0042","status":"done","text":"PR merged"}
-```
-
----
-
-## Related Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/agileflow:story` | Create new story |
-| `/agileflow:status` | Update story status |
-| `/agileflow:board` | View kanban board |
-| `/agileflow:blockers` | View blocked stories |
-| `/agileflow:story-validate` | Validate DoR |
-
----
-
-## Best Practices
-
-1. **Keep stories small**: 1-3 days of work maximum
-2. **Update status promptly**: Reflect actual work state
-3. **Document blockers**: Include reason and expected resolution
-4. **Respect WIP limits**: Complete before starting new
-5. **Use phase handoffs**: Capture context at transitions

package/src/core/templates/story-template.md

@@ -1,92 +0,0 @@
----
-story_id: {{STORY_ID}}
-epic: {{EPIC_ID}}
-title: {{TITLE}}
-owner: {{OWNER}}
-status: ready
-estimate: {{ESTIMATE}}
-created: {{CREATED}}
-updated: {{UPDATED}}
-dependencies: {{DEPENDENCIES}}
-tdd_mode: {{TDD_MODE}}
-test_file: {{TEST_FILE}}
----
-
-# {{STORY_ID}}: {{TITLE}}
-
-**Epic**: {{EPIC_ID}}
-**Owner**: {{OWNER}}
-**Estimate**: {{ESTIMATE}}
-{{TDD_BADGE}}
-
-## Description
-{{DESCRIPTION}}
-
-## Acceptance Criteria
-{{AC_BULLETS}}
-
-## Architecture Context
-<!-- AUTO-FILLED by epic-planner: Extract ONLY relevant architecture sections from docs/04-architecture/ -->
-<!-- Include file locations, data models, API endpoints, component specs, testing requirements -->
-<!-- Every technical detail MUST cite its source: [Source: architecture/api.md#endpoints] -->
-
-### Data Models & Schemas
-<!-- Specific schemas, validation rules, relationships this story uses -->
-
-### API Specifications
-<!-- Endpoint details, request/response formats, auth requirements -->
-
-### Component Specifications
-<!-- UI component details, props, state management -->
-
-### File Locations & Naming
-<!-- Exact paths where new code should be created -->
-
-### Testing Requirements
-<!-- Specific test cases, frameworks, patterns from testing-strategy.md -->
-
-### Technical Constraints
-<!-- Version requirements, performance considerations, security rules -->
-
-## Technical Notes
-<!-- Implementation hints, edge cases, specific approaches to use -->
-
-## Testing Strategy
-See: `docs/07-testing/test-cases/{{STORY_ID}}.md`
-{{TDD_TEST_FILE_REF}}
-
-## Dependencies
-{{DEPENDENCIES}}
-
-## Dev Agent Record
-<!-- POPULATED BY DEVELOPMENT AGENT DURING IMPLEMENTATION -->
-
-### Agent Model & Version
-<!-- Which AI model was used (e.g., claude-opus, gpt-4o, etc.) -->
-
-### Completion Notes
-<!-- What was actually built vs. what was planned -->
-<!-- Any deviations from acceptance criteria and why -->
-<!-- Actual implementation time vs. estimate -->
-
-### Issues Encountered
-<!-- Challenges faced and how they were resolved -->
-<!-- Bugs discovered and fixed -->
-<!-- Architectural decisions made during implementation -->
-
-### Lessons Learned
-<!-- Key insights for next story in this epic -->
-<!-- Patterns discovered that other stories should use -->
-<!-- Technical debt discovered -->
-
-### Files Modified
-<!-- List all files created, modified, or deleted -->
-<!-- Help future agents understand the scope -->
-
-### Debug References
-<!-- Links to debug logs, test runs, or decision traces -->
-
-## Previous Story Insights
-<!-- POPULATED FROM PREVIOUS STORY IN THIS EPIC -->
-<!-- Key learnings from {{PREV_STORY_ID}} that apply here -->
-<!-- Architectural patterns that worked/didn't work -->