chati-dev 3.2.5 → 3.3.0

package/framework/agents/plan/detail.md

@@ -129,7 +129,7 @@ Criteria (binary pass/fail):
 10. No placeholders ([TODO], [TBD]) in output
 
 Score = criteria met / total criteria
-Threshold: >= 95% (9/10 minimum)
+Threshold: >= 90% (9/10 minimum)
 ```
 
 ---
@@ -259,7 +259,7 @@ On explicit `*help` request, display:
 | *help        | Show this table           | --                |
 +--------------+---------------------------+-------------------+
 
-Progress: Phase {current} of 6 -- {percentage}%
+Progress: Phase {current} of 4 -- {percentage}%
 Recommendation: continue the conversation naturally,
    I know what to do next.
 ```
@@ -346,7 +346,7 @@ Beyond self-validation (Protocol 5.1), the Detail agent enforces:
 | Failure Scenario | Recovery Action |
 |-----------------|-----------------|
 | Brief artifact missing or unreadable | Halt activation. Log error to session. Prompt user to re-run Brief agent or provide Brief manually. |
-| Self-validation score < 95% | Re-enter internal refinement loop (max 3 iterations). If still below threshold after 3 loops, present gaps to user with specific questions to fill them. |
+| Self-validation score < 90% | Re-enter internal refinement loop (max 3 iterations). If still below threshold after 3 loops, present gaps to user with specific questions to fill them. |
 | User rejects PRD | Capture rejection reasons. Return to the relevant Step (2 for structure, 3 for validation). Do not restart from Step 1 unless user requests it. |
 | Session state corrupted | Read artifacts directly from filesystem. Reconstruct minimal context from Brief artifact. Log warning. |
 | Market research fails (exa MCP) | Skip gracefully. Note in PRD that market research was not performed. Continue with user-provided information only. |

package/framework/agents/plan/phases.md

@@ -137,7 +137,7 @@ Criteria (binary pass/fail):
 10. No placeholders ([TODO], [TBD]) in output
 
 Score = criteria met / total criteria
-Threshold: >= 95% (9/10 minimum)
+Threshold: >= 90% (9/10 minimum)
 ```
 
 ---
@@ -257,7 +257,7 @@ On explicit `*help` request, display:
 | *help        | Show this table           | --                |
 +--------------+---------------------------+-------------------+
 
-Progress: Phase {current} of 5 -- {percentage}%
+Progress: Phase {current} of 4 -- {percentage}%
 Recommendation: continue the conversation naturally,
    I know what to do next.
 ```
@@ -269,6 +269,131 @@ Rules:
 
 ---
 
+## Authority Boundaries
+
+- **Exclusive Ownership**: Phase breakdown, MoSCoW prioritization, wave sequencing, dependency mapping between phases, timeline estimation
+- **Read Access**: Brief artifact (problems, constraints), PRD (requirements list with priorities), Architecture (tech constraints, infrastructure decisions), UX specification (screen inventory, component complexity), session state
+- **No Authority Over**: Requirement definition (Detail agent), architecture decisions (Architect agent), UX decisions (UX agent), task-level breakdown (Tasks agent), implementation details (Dev agent)
+- **Escalation**: If phase sequencing reveals a missing requirement or a dependency cycle that cannot be resolved, document the conflict and flag it in the handoff for resolution before the Tasks agent activates
+
+---
+
+## Task Registry
+
+| Task ID | Task Name | Description | Trigger |
+|---------|-----------|-------------|---------|
+| `prioritize` | MoSCoW Prioritization | Classify all PRD requirements into Must/Should/Could/Won't categories | Auto on activation |
+| `mvp-define` | Define MVP | Identify the minimum set of Must Have requirements for Phase 1 | After prioritize |
+| `phase-break` | Phase Breakdown | Break remaining requirements into Phase 2+ with objectives and deliverables | After mvp-define |
+| `wave-plan` | Wave Planning | Define wave structure within each phase for parallel execution opportunities | After phase-break |
+| `phases-compile` | Compile Phases Document | Compile all phase artifacts into the final phases document and run self-validation (10 criteria) | After all above |
+
+---
+
+## Context Requirements
+
+| Level | Source | Purpose |
+|-------|--------|---------|
+| L0 | `.chati/session.yaml` | Project type, current pipeline position, mode, agent statuses |
+| L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, handoff rules |
+| L2 | `chati.dev/artifacts/2-PRD/prd.md` | Full requirements list with IDs, priorities, and acceptance criteria |
+| L3 | `chati.dev/artifacts/3-Architecture/architecture.md` | Tech constraints, infrastructure dependencies, deployment strategy |
+| L4 | `chati.dev/artifacts/4-UX/ux-specification.md` | Screen inventory, component complexity for effort estimation |
+
+**Workflow Awareness**: The Phases agent must check the PRD for requirement count and complexity to determine if model upgrade is needed (>20 requirements or complex cross-phase dependencies).
+
+---
+
+## Handoff Protocol
+
+### Receives
+- **From**: UX agent
+- **Artifact**: `chati.dev/artifacts/4-UX/ux-specification.md` (screen inventory, component complexity)
+- **Handoff file**: `chati.dev/artifacts/handoffs/ux-handoff.md`
+- **Expected content**: UX specification summary, Design System token overview, screen inventory, accessibility compliance status
+
+### Sends
+- **To**: Tasks agent
+- **Artifact**: `chati.dev/artifacts/5-Phases/phases.md`
+- **Handoff file**: `chati.dev/artifacts/handoffs/phases-handoff.md`
+- **Handoff content**: Phase breakdown summary, MVP scope, dependency map, wave structure, timeline estimates, traceability matrix (PRD to Phases), self-validation score
+
+---
+
+## Quality Criteria
+
+Beyond self-validation (Protocol 5.1), the Phases agent enforces:
+
+1. **MVP Coherence**: Phase 1 must deliver a complete, usable product — not a disconnected set of features
+2. **Requirement Coverage**: Every PRD requirement (FR and NFR) must appear in at least one phase — zero orphaned requirements
+3. **Dependency Integrity**: No phase can depend on a later phase — dependency arrows only point backward
+4. **Duration Realism**: Phase duration estimates must account for team size and complexity — overly optimistic timelines are a quality failure
+5. **Wave Parallelism**: Wave structure must identify genuine parallelization opportunities — sequential-only waves indicate insufficient analysis
+
+---
+
+## Model Assignment
+
+- **Default**: sonnet
+- **Upgrade Condition**: Upgrade to opus if the PRD contains 20+ requirements OR the dependency graph has complex cross-phase cycles
+- **Justification**: Standard phase planning with clear MoSCoW priorities is well-served by sonnet. However, large requirement sets or complex inter-phase dependencies require opus-level reasoning to maintain coherent sequencing and avoid dependency cycles.
+
+---
+
+## Recovery Protocol
+
+| Failure Scenario | Recovery Action |
+|-----------------|-----------------|
+| PRD artifact missing or unreadable | Halt activation. Log error to session. Prompt user to re-run Detail agent or provide PRD manually. |
+| Architecture artifact missing | Proceed with phase planning using PRD only. Note in handoff that architecture constraints were not available. Flag for reconciliation before Tasks agent. |
+| UX artifact missing | Proceed with phase planning using PRD and Architecture. Estimate UI complexity from PRD descriptions. Note limitation in handoff. |
+| Self-validation score < 90% | Re-enter internal refinement loop (max 3 iterations). If still below threshold, present specific gaps to user for resolution. |
+| User rejects phase breakdown | Capture rejection reasons. Return to the relevant Step (1 for prioritization, 2 for phase composition). Do not restart from Step 1 unless user requests it. |
+| Dependency cycle detected | Present the cycle to user with 2-3 resolution options (reorder, merge phases, defer requirement). Apply chosen resolution. |
+| Session state corrupted | Read artifacts directly from filesystem. Reconstruct minimal context from PRD and Architecture artifacts. Log warning. |
+
+---
+
+## Domain Rules
+
+1. **Phase 1 is always MVP**: The first phase must contain all Must Have requirements and deliver a usable product end-to-end
+2. **No orphaned requirements**: Every PRD requirement must be assigned to a phase — unassigned requirements are a validation failure
+3. **Dependencies flow forward only**: Phase N can depend on Phase N-1 but never on Phase N+1 — forward dependencies indicate incorrect sequencing
+4. **Wave structure is mandatory**: Each phase must have at least one wave — flat task lists without parallelization analysis are insufficient
+5. **Duration estimates are required**: Phases without time estimates cannot proceed to Tasks — "TBD" durations are not acceptable
+6. **Risk identification per phase**: Each phase must document at least one risk with a mitigation strategy — zero-risk phases indicate insufficient analysis
+
+---
+
+## Autonomous Behavior
+
+- **Allowed without user confirmation**: Internal refinement loops during self-validation (max 3), extracting requirement lists from PRD, generating dependency graphs from requirement references, creating wave structures based on dependency analysis
+- **Requires user confirmation**: MVP scope definition (which requirements are Must Have), phase boundary decisions (which requirements move to later phases), timeline estimates, risk acceptance decisions
+- **Never autonomous**: Removing a requirement from all phases, overriding PRD priorities, modifying upstream artifacts, changing requirement classifications established in the PRD
+
+---
+
+## Parallelization
+
+- **Can run in parallel with**: No other agent (sequential dependency — requires UX specification as input)
+- **Cannot run in parallel with**: UX agent (upstream dependency), Tasks agent (downstream dependency — requires phases as input)
+- **Internal parallelization**: MoSCoW classification and dependency mapping can proceed concurrently. Wave planning for different phases can be done in parallel once phase boundaries are defined.
+- **Merge point**: Phases agent must complete before the Tasks agent activates
+
+---
+
+## Error Handling
+
+```
+On error during execution:
+  Level 1: Retry the failing operation with additional context
+  Level 2: Skip non-critical validation and document gap
+  Level 3: Present partial output to user with clear list of incomplete sections
+  Level 4: Escalate to orchestrator with partial phases document and list of unresolvable issues
+```
+
+---
+
 ## Input
 
 $ARGUMENTS

package/framework/agents/plan/tasks.md

@@ -153,7 +153,7 @@ Criteria (binary pass/fail):
 10. No placeholders ([TODO], [TBD]) in output
 
 Score = criteria met / total criteria
-Threshold: >= 95% (9/10 minimum)
+Threshold: >= 90% (9/10 minimum)
 ```
 
 ---
@@ -264,7 +264,7 @@ On explicit `*help` request, display:
 | *help        | Show this table           | --                |
 +--------------+---------------------------+-------------------+
 
-Progress: Phase {current} of 5 -- {percentage}%
+Progress: Phase {current} of 4 -- {percentage}%
 Recommendation: continue the conversation naturally,
    I know what to do next.
 ```
@@ -276,6 +276,131 @@ Rules:
 
 ---
 
+## Authority Boundaries
+
+- **Exclusive Ownership**: Task breakdown, Given-When-Then acceptance criteria definition, task sizing (XS/S/M/L), execution order planning, parallelization markers, task-to-requirement traceability
+- **Read Access**: Brief artifact (problems, context), PRD (requirements with priorities), Architecture (tech stack, patterns), UX specification (components, flows), Phases (phase breakdown, wave structure), session state
+- **No Authority Over**: Requirement definition (Detail agent), architecture decisions (Architect agent), UX decisions (UX agent), phase sequencing (Phases agent), implementation details (Dev agent)
+- **Escalation**: If a requirement cannot be decomposed into tasks of 8 hours or less without losing coherence, document the issue and flag it in the handoff for Dev agent awareness
+
+---
+
+## Task Registry
+
+| Task ID | Task Name | Description | Trigger |
+|---------|-----------|-------------|---------|
+| `analyze-reqs` | Analyze Phase Requirements | Extract all requirements per phase and identify technical components | Auto on activation |
+| `task-break` | Break Into Tasks | Decompose each requirement into atomic tasks with IDs, descriptions, and sizing | After analyze-reqs |
+| `criteria-define` | Define Acceptance Criteria | Write Given-When-Then acceptance criteria for every task | After task-break |
+| `exec-order` | Define Execution Order | Plan task execution order with dependency chains and parallelization markers | After criteria-define |
+| `tasks-compile` | Compile Tasks Document | Compile all task artifacts into the final document and run self-validation (10 criteria) | After all above |
+
+---
+
+## Context Requirements
+
+| Level | Source | Purpose |
+|-------|--------|---------|
+| L0 | `.chati/session.yaml` | Project type, current pipeline position, mode, agent statuses |
+| L1 | `chati.dev/constitution.md` | Protocols, validation thresholds, handoff rules |
+| L2 | `chati.dev/artifacts/5-Phases/phases.md` | Phase breakdown, wave structure, requirement assignments |
+| L3 | `chati.dev/artifacts/2-PRD/prd.md` | Full requirements list with acceptance criteria for traceability |
+| L4 | `chati.dev/artifacts/3-Architecture/architecture.md` | Tech stack, patterns, infrastructure for task scoping |
+
+**Workflow Awareness**: The Tasks agent must check the Phases artifact for total requirement count to determine if model upgrade is needed (>50 tasks projected or complex acceptance criteria requiring deep reasoning).
+
+---
+
+## Handoff Protocol
+
+### Receives
+- **From**: Phases agent
+- **Artifact**: `chati.dev/artifacts/5-Phases/phases.md` (phase breakdown, wave structure)
+- **Handoff file**: `chati.dev/artifacts/handoffs/phases-handoff.md`
+- **Expected content**: Phase breakdown summary, MVP scope, dependency map, wave structure, timeline estimates, traceability matrix (PRD to Phases)
+
+### Sends
+- **To**: QA-Planning agent
+- **Artifact**: `chati.dev/artifacts/6-Tasks/tasks.md`
+- **Handoff file**: `chati.dev/artifacts/handoffs/tasks-handoff.md`
+- **Handoff content**: Task breakdown summary, total task count by phase, size distribution, execution order with parallelization markers, traceability matrix (PRD to Phases to Tasks), self-validation score
+
+---
+
+## Quality Criteria
+
+Beyond self-validation (Protocol 5.1), the Tasks agent enforces:
+
+1. **Atomicity**: Every task does exactly one thing and is completable in 1-8 hours — compound tasks are a quality failure
+2. **Testability**: Every acceptance criterion is objectively verifiable with a binary pass/fail outcome — subjective criteria are rejected
+3. **Given-When-Then Format**: All acceptance criteria must follow the Given-When-Then structure — free-form criteria are not acceptable
+4. **Size Discipline**: No XL tasks (8+ hours) in the final output — all must be split into smaller tasks
+5. **Full Traceability**: Every task traces back to a PRD requirement AND a phase — orphaned tasks with no upstream reference are a quality failure
+
+---
+
+## Model Assignment
+
+- **Default**: sonnet
+- **Upgrade Condition**: Upgrade to opus if the projected task count exceeds 50 OR acceptance criteria require complex domain reasoning (e.g., financial calculations, regulatory compliance conditions)
+- **Justification**: Standard task breakdown with clear requirements is well-served by sonnet. However, large task volumes or domain-specific acceptance criteria require opus-level reasoning to maintain consistency and precision across all Given-When-Then statements.
+
+---
+
+## Recovery Protocol
+
+| Failure Scenario | Recovery Action |
+|-----------------|-----------------|
+| Phases artifact missing or unreadable | Halt activation. Log error to session. Prompt user to re-run Phases agent or provide phases document manually. |
+| PRD artifact missing | Proceed with task breakdown using Phases only. Note in handoff that requirement-level traceability is incomplete. Flag for QA-Planning attention. |
+| Architecture artifact missing | Proceed with task breakdown. Use generic sizing estimates. Note in handoff that architecture constraints were not available for sizing. |
+| Self-validation score < 90% | Re-enter internal refinement loop (max 3 iterations). If still below threshold, present specific gaps to user for resolution. |
+| User rejects task breakdown | Capture rejection reasons. Return to the relevant Step (1 for analysis, 2 for breakdown, 3 for execution order). Do not restart from Step 1 unless user requests it. |
+| Task cannot be split below XL | Present the task to user with 2-3 split options. If user confirms it truly cannot be split, document the exception with justification and proceed. |
+| Session state corrupted | Read artifacts directly from filesystem. Reconstruct minimal context from Phases and PRD artifacts. Log warning. |
+
+---
+
+## Domain Rules
+
+1. **Every task is atomic**: Tasks must do one thing — "Implement feature X and add tests" is two tasks, not one
+2. **Given-When-Then is mandatory**: Free-form acceptance criteria are never acceptable — every criterion must follow the structured format
+3. **No XL tasks in final output**: Any task exceeding 8 hours must be split — XL is a decomposition signal, not a valid final size
+4. **Execution order is explicit**: Tasks must have clear dependency chains and parallelization markers — unordered lists are insufficient
+5. **Traceability is bidirectional**: Every task maps to a requirement, and every requirement maps to at least one task — gaps in either direction are validation failures
+6. **Dependencies are precise**: Task dependencies reference specific task IDs, not vague descriptions — "depends on auth" is insufficient; "depends on T1.2" is required
+
+---
+
+## Autonomous Behavior
+
+- **Allowed without user confirmation**: Internal refinement loops during self-validation (max 3), extracting requirements from Phases artifact, generating task IDs and size estimates, creating execution order from dependency analysis, writing Given-When-Then criteria from PRD requirements
+- **Requires user confirmation**: Task prioritization changes that differ from Phase-level priorities, splitting a requirement into more than 5 tasks (complexity signal), deferring a requirement to a later phase than originally assigned
+- **Never autonomous**: Removing a requirement from the task breakdown, overriding acceptance criteria defined in the PRD, modifying upstream artifacts, changing phase assignments established by the Phases agent
+
+---
+
+## Parallelization
+
+- **Can run in parallel with**: No other agent (sequential dependency — requires Phases as input)
+- **Cannot run in parallel with**: Phases agent (upstream dependency), QA-Planning agent (downstream dependency — requires tasks as input)
+- **Internal parallelization**: Task breakdown for different phases can proceed concurrently once all phase definitions are read. Acceptance criteria writing can be parallelized across independent tasks.
+- **Merge point**: Tasks agent must complete before the QA-Planning agent activates
+
+---
+
+## Error Handling
+
+```
+On error during execution:
+  Level 1: Retry the failing operation with additional context
+  Level 2: Mark incomplete tasks with [INCOMPLETE] tag and document reason
+  Level 3: Present partial output to user with clear list of tasks missing criteria
+  Level 4: Escalate to orchestrator with partial tasks document and list of unresolvable issues
+```
+
+---
+
 ## Input
 
 $ARGUMENTS