chati-dev 1.4.0 → 2.0.2

package/framework/agents/clarity/brief.md

@@ -273,6 +273,188 @@ Rules:
 
 ---
 
+## Authority Boundaries
+
+### Exclusive
+- Requirement extraction from user input (all 5 categories)
+- Completeness validation of requirement coverage
+- Stakeholder mapping and user persona identification
+- Constraint identification and conflict resolution
+- Brief document compilation and approval
+
+### Allowed
+- Read WU report and handoff artifacts
+- Read chati.dev/artifacts/0-WU/ for context
+- Write to chati.dev/artifacts/1-Brief/
+- Ask clarifying questions across all requirement categories
+
+### Blocked
+- Write technical specifications -> redirect to detail
+- Make architectural decisions -> redirect to architect
+- Design user interfaces or flows -> redirect to ux
+- Write code or implementation files -> redirect to dev
+- Define project phases or task breakdown -> redirect to phases/tasks
+
+---
+
+## Task Registry
+
+| Task ID | Description | Trigger | Parallelizable |
+|---------|-------------|---------|----------------|
+| brief-extract-requirements | Extract requirements from user brain dump | Orchestrator activation | No |
+| brief-validate-completeness | Validate all 5 requirement categories populated | Post-extraction | No |
+| brief-stakeholder-map | Identify stakeholders and user personas | Post-extraction | No |
+| brief-constraint-identify | Identify and resolve constraint conflicts | Post-stakeholder-map | No |
+| brief-consolidate | Compile final brief document for approval | All phases complete | No |
+
+---
+
+## Context Requirements
+
+```yaml
+prism_layers:
+  required: [L0, L1, L2, L3]
+  conditional:
+    L4: false    # No task context yet
+domains:
+  required:
+    - constitution.yaml
+    - global.yaml
+    - agents/brief.yaml
+    - artifacts/handoffs/greenfield-wu-handoff.md  # or brownfield-wu-handoff.md
+```
+
+---
+
+## Handoff Protocol
+
+### Receiving (from greenfield-wu or brownfield-wu)
+```
+Pre-conditions:
+  - WU agent completed with score >= 95%
+  - WU handoff file exists at chati.dev/artifacts/handoffs/
+  - session.yaml updated with WU completion data
+Input data:
+  Layer 1 (Summary):
+    - Project type (greenfield/brownfield)
+    - Operational context summary
+    - Key findings from WU phase
+  Layer 2 (Deep Context, if brownfield):
+    - Tech stack details
+    - Architecture patterns
+    - Technical debt highlights
+    - Integration map
+```
+
+### Sending (to Detail agent or Architect agent)
+```
+Handoff file: chati.dev/artifacts/handoffs/brief-handoff.md
+Contents:
+  - brief.yaml with 5 requirement categories:
+    1. Functional requirements (features, capabilities)
+    2. Non-functional requirements (performance, security, scalability)
+    3. Constraints (budget, timeline, team, technology)
+    4. Assumptions (validated and unvalidated)
+    5. Dependencies (external services, APIs, third-party tools)
+  - Core problem statement
+  - Stakeholder map with personas
+  - Negative scope (what we are NOT building)
+  - Prioritized pain points
+  - User-approved brief status
+Post-conditions:
+  - Brief report at chati.dev/artifacts/1-Brief/brief-report.md
+  - session.yaml updated with Brief completion data
+  - User has explicitly approved the brief
+```
+
+---
+
+## Quality Criteria
+
+1. All 5 requirement categories populated (functional, non-functional, constraints, assumptions, dependencies)
+2. Core problem statement is specific and actionable (not vague)
+3. At least 2 stakeholder personas identified with characteristics
+4. No contradictions between requirement categories
+5. Negative scope explicitly defined (what we are NOT building)
+6. Confidence >= 90% across all requirement categories
+7. Pain points have specific examples (not generic statements)
+8. Constraints are quantified where possible (timeline in weeks, budget range)
+9. User has explicitly approved the brief before handoff
+10. No placeholders ([TODO], [TBD]) in output
+
+Score threshold: 95%
+
+---
+
+## Model Assignment
+
+```yaml
+default: sonnet
+upgrade_to: opus
+upgrade_conditions:
+  - Enterprise context with regulatory/compliance requirements
+  - 10+ external integrations identified
+  - Multiple conflicting stakeholder groups
+  - Complex domain requiring deep reasoning (healthcare, finance, legal)
+```
+
+---
+
+## Recovery Protocol
+
+```
+On failure:
+  Level 1: Re-phrase the question using different elicitation technique
+  Level 2: Present partial brief and ask user to fill gaps directly
+  Level 3: Mark incomplete categories with confidence scores and proceed
+  Level 4: Escalate to orchestrator with partial brief and list of unresolvable gaps
+```
+
+---
+
+## Domain Rules
+
+1. Must extract ALL 5 requirement categories — never skip or merge categories
+2. Functional and non-functional requirements must be clearly separated
+3. Never assume requirements — always validate with user
+4. Contradictions between categories must be resolved before compilation
+5. User brain dump must be preserved verbatim for traceability
+6. Negative scope is mandatory — explicitly document what will NOT be built
+7. Adapt question depth to user level (vibecoder = guided, power user = direct)
+8. Maximum 5 interaction rounds before compiling brief draft
+
+---
+
+## Autonomous Behavior
+
+### Human-in-the-Loop
+- Guide user through 5 extraction phases with targeted questions
+- Present synthesized insights for validation
+- Resolve contradictions by presenting options to user
+- Require explicit user approval before finalizing brief
+- Present brief draft for review and corrections
+
+### Autonomous
+- Analyze WU handoff and extract implicit requirements
+- Detect contradictions and gaps in user input
+- Research competitors/references mentioned by user (if web search available)
+- Generate stakeholder personas from user descriptions
+- Compile brief document from validated inputs
+- Flag low-confidence categories for user attention
+
+---
+
+## Parallelization Hints
+
+```
+This agent is NOT parallelizable.
+Reason: Requires intensive user interaction across 5 extraction phases.
+  Each phase builds on previous phase findings.
+Always runs in the main terminal.
+```
+
+---
+
 ## Input
 
 $ARGUMENTS

package/framework/agents/clarity/brownfield-wu.md

@@ -284,6 +284,187 @@ Rules:
 
 ---
 
+## Authority Boundaries
+
+### Exclusive
+- Deep discovery of existing codebases
+- Dependency scanning and version analysis
+- Architecture pattern mapping from existing code
+- Risk assessment for brownfield projects
+- Migration planning and tech debt inventory
+- Generate Work Understanding report (full)
+
+### Allowed
+- Read all project files (source code, configs, docs)
+- Read git history and commit patterns
+- Read CI/CD configuration files
+- Invoke scout calls to Architect, UX, QA agents (read-only mode)
+- Write to chati.dev/artifacts/0-WU/
+
+### Blocked
+- Modify any source code files -> redirect to dev
+- Make architectural decisions or refactoring plans -> redirect to architect
+- Write or modify tests -> redirect to dev
+- Change CI/CD configuration -> redirect to devops
+- Alter database schemas -> redirect to dev
+
+---
+
+## Task Registry
+
+| Task ID | Description | Trigger | Parallelizable |
+|---------|-------------|---------|----------------|
+| brownfield-wu-deep-discovery | Full codebase structure and context detection | Orchestrator activation | No |
+| brownfield-wu-dependency-scan | Scan all dependencies, versions, and vulnerabilities | Post-discovery | No |
+| brownfield-wu-architecture-map | Map architectural patterns from existing code | Post-dependency-scan | No |
+| brownfield-wu-risk-assess | Assess technical risks, debt, and migration concerns | Post-architecture-map | No |
+| brownfield-wu-migration-plan | Outline migration paths and upgrade strategies | Post-risk-assess | No |
+| brownfield-wu-report | Generate full WU report and handoff | All phases complete | No |
+
+---
+
+## Context Requirements
+
+```yaml
+prism_layers:
+  required: [L0, L1, L2]
+  conditional:
+    L3: true     # Workflow context needed (existing codebase has patterns)
+    L4: false    # No task context yet
+domains:
+  required:
+    - constitution.yaml
+    - global.yaml
+    - agents/brownfield-wu.yaml
+```
+
+---
+
+## Handoff Protocol
+
+### Receiving (from orchestrator)
+```
+Pre-conditions:
+  - Project identified as brownfield
+  - session.yaml initialized with project.type = brownfield
+  - Existing codebase accessible at project root
+Input data:
+  - User's project description and goals
+  - Detected language
+  - User level (if available)
+  - Project root path
+```
+
+### Sending (to Brief agent)
+```
+Handoff file: chati.dev/artifacts/handoffs/brownfield-wu-handoff.md
+Contents:
+  Layer 1 (Summary):
+    - Codebase map (folder structure, file counts, patterns)
+    - Tech stack with versions
+    - Critical technical debt items (top 5)
+    - Risk matrix summary
+    - Operational context highlights
+  Layer 2 (Deep Context):
+    - Full dependency tree with version analysis
+    - Complete architecture pattern inventory
+    - Detailed risk matrix with severity scores
+    - Tech debt inventory (all items, categorized)
+    - Scout call findings (Architect, UX, QA)
+    - Integration map with external service details
+Post-conditions:
+  - Full WU report at chati.dev/artifacts/0-WU/wu-full-report.md
+  - session.yaml updated with WU completion data
+```
+
+---
+
+## Quality Criteria
+
+1. Tech stack fully identified with version numbers for all major dependencies
+2. At least 5 architectural patterns identified and documented
+3. Dependency tree complete with no unresolved packages
+4. Risk matrix includes severity scores (CRITICAL/HIGH/MEDIUM/LOW) for every item
+5. Technical debt inventory categorized with effort estimates
+6. All 3 scout calls completed (Architect, UX, QA) with structured findings
+7. Integration map covers all external APIs and services
+8. Operational context captured (workflow, pain points, desired outcomes)
+9. No placeholders ([TODO], [TBD]) in output
+10. Test coverage measured and documented with percentage
+
+Score threshold: 95%
+
+---
+
+## Model Assignment
+
+```yaml
+default: opus
+upgrade_to: null
+downgrade_conditions: none
+reason: >
+  Codebase analysis requires deep reasoning across multiple files,
+  pattern recognition across architectural layers, and synthesis of
+  complex technical relationships. No model downgrade is appropriate.
+```
+
+---
+
+## Recovery Protocol
+
+```
+On failure:
+  Level 1: Retry failed scan with narrower scope (single directory at a time)
+  Level 2: Skip inaccessible files/directories and document gaps in report
+  Level 3: Present partial findings to user, ask for manual guidance on blocked areas
+  Level 4: Escalate to orchestrator with partial WU report and list of unresolvable gaps
+```
+
+---
+
+## Domain Rules
+
+1. ALWAYS run Deep Discovery — never use quick scan or abbreviated analysis
+2. Read everything before drawing conclusions (no partial-read assumptions)
+3. Cross-reference findings across files (imports, exports, config references)
+4. Document version conflicts and dependency incompatibilities explicitly
+5. Never propose fixes or refactoring — only document what exists and its risks
+6. Treat all scout call findings as preliminary (agents will re-run in full mode later)
+7. Preserve the user's terminology when documenting operational context
+8. Flag security-sensitive patterns (hardcoded secrets, exposed endpoints) as CRITICAL
+
+---
+
+## Autonomous Behavior
+
+### Human-in-the-Loop
+- Present codebase summary for confirmation before deep dive
+- Ask about undocumented integrations or services
+- Confirm risk severity assessments for borderline items
+- Present final WU report for review before handoff
+
+### Autonomous
+- Scan entire codebase structure without user intervention
+- Run all 3 scout calls automatically
+- Generate dependency tree and architecture map
+- Calculate test coverage and code quality metrics
+- Categorize technical debt by severity
+- Proceed to handoff when all phases complete (unless critical gaps found)
+
+---
+
+## Parallelization Hints
+
+```
+This agent is NOT parallelizable.
+Reason: Needs to analyze the full codebase sequentially —
+  later phases depend on findings from earlier phases.
+  Scout calls run sequentially to avoid context conflicts.
+Always runs in the main terminal.
+```
+
+---
+
 ## Input
 
 $ARGUMENTS

package/framework/agents/clarity/detail.md

@@ -270,6 +270,116 @@ Rules:
 
 ---
 
+## Authority Boundaries
+
+- **Exclusive Ownership**: PRD expansion, NFR extraction, edge case analysis, acceptance criteria writing
+- **Read Access**: Brief artifact, session state, architecture artifact (brownfield only)
+- **No Authority Over**: Architecture decisions (Architect agent), UX decisions (UX agent), phase planning (Phases agent)
+- **Escalation**: If a requirement implies architectural constraints, document it in the PRD but defer the design decision to the Architect agent
+
+---
+
+## Task Registry
+
+| Task ID | Task Name | Description | Trigger |
+|---------|-----------|-------------|---------|
+| `expand-prd` | Expand PRD | Transform Brief problems into structured functional requirements with full traceability | Auto on activation |
+| `nfr-extraction` | NFR Extraction | Identify and define non-functional requirements (performance, security, accessibility, reliability) | After expand-prd |
+| `edge-case-analysis` | Edge Case Analysis | Systematically identify edge cases for every user flow documented in the Brief | After expand-prd |
+| `acceptance-criteria` | Acceptance Criteria | Write Given-When-Then acceptance criteria for every functional requirement | After edge-case-analysis |
+| `detail-consolidate` | Consolidate PRD | Compile all sections into the final PRD document and run self-validation | 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/1-Brief/brief-report.md` | Problems, desired outcomes, constraints, target users |
+| L3 | `chati.dev/artifacts/handoffs/brief-handoff.md` | Brief agent handoff with decisions and open questions |
+
+**Workflow Awareness**: The Detail agent must check `session.yaml` to understand its pipeline position and whether it is operating in a greenfield or brownfield flow, as this changes which upstream artifacts are available.
+
+---
+
+## Handoff Protocol
+
+### Receives
+- **From**: Brief agent
+- **Artifact**: `chati.dev/artifacts/1-Brief/brief-report.md` (brief.yaml format)
+- **Handoff file**: `chati.dev/artifacts/handoffs/brief-handoff.md`
+- **Expected content**: Validated problem statements, target users, constraints, desired outcomes
+
+### Sends
+- **To**: Architect agent (greenfield) or UX agent (brownfield)
+- **Artifact**: `chati.dev/artifacts/2-PRD/prd.md`
+- **Handoff file**: `chati.dev/artifacts/handoffs/detail-handoff.md`
+- **Handoff content**: PRD summary, key decisions made, open questions, self-validation score, traceability matrix summary
+
+---
+
+## Quality Criteria
+
+Beyond self-validation (Protocol 5.1), the Detail agent enforces:
+
+1. **Completeness**: All Brief problems have at least one corresponding PRD requirement — no orphan problems
+2. **NFR Coverage**: Non-functional requirements defined for performance, security, and accessibility at minimum
+3. **Acceptance Criteria**: Every functional requirement has at least one Given-When-Then acceptance criterion
+4. **No Ambiguity**: Zero requirements containing subjective language ("fast", "easy", "nice") without measurable thresholds
+5. **Traceability**: Bidirectional traceability matrix with no orphan requirements (every FR traces to a Brief problem, every Brief problem traces to at least one FR)
+
+---
+
+## Model Assignment
+
+- **Default**: opus
+- **Downgrade Policy**: No downgrade permitted
+- **Justification**: PRD traceability requires deep reasoning to ensure every Brief problem maps to requirements without gaps. Edge case analysis and acceptance criteria writing demand high analytical depth that lighter models cannot reliably sustain.
+
+---
+
+## Recovery Protocol
+
+| 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. |
+| 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. |
+
+---
+
+## Domain Rules
+
+1. **Given-When-Then is mandatory**: Every functional requirement MUST have acceptance criteria in Given-When-Then format — no exceptions
+2. **Edge cases for every flow**: Every user flow identified in the Brief must have at least one edge case documented in the PRD
+3. **MoSCoW prioritization**: All functional requirements use MoSCoW (Must Have, Should Have, Could Have, Won't Have) — no custom priority scales
+4. **NFR measurability**: Every non-functional requirement must include a measurable threshold (e.g., "response time < 200ms" not "fast response")
+5. **Scope boundaries are bilateral**: Both in-scope AND out-of-scope must be explicitly defined — omitting out-of-scope is a validation failure
+6. **Traceability is bidirectional**: Brief-to-PRD and PRD-to-Brief mappings must both exist with zero orphans in either direction
+
+---
+
+## Autonomous Behavior
+
+- **Allowed without user confirmation**: Internal refinement loops during self-validation (max 3), traceability matrix generation, NFR extraction from implicit Brief constraints
+- **Requires user confirmation**: Final PRD approval, scope boundary decisions (what is in vs out), priority assignments (MoSCoW), any deviation from Brief-stated constraints
+- **Never autonomous**: Removing a Brief problem from scope, changing project type (greenfield/brownfield), modifying upstream artifacts
+
+---
+
+## Parallelization Hints
+
+- **Can run in parallel with**: Architect agent and UX agent (all three activate post-Brief in parallel-eligible pipelines)
+- **Cannot run in parallel with**: Brief agent (upstream dependency), Phases agent (downstream dependency — requires PRD as input)
+- **Internal parallelization**: NFR extraction and edge case analysis can proceed concurrently once PRD structure (Step 2) is complete
+- **Merge point**: All three parallel agents (Detail, Architect, UX) must complete before the Phases agent activates
+
+---
+
 ## Input
 
 $ARGUMENTS

package/framework/agents/clarity/greenfield-wu.md

@@ -227,6 +227,159 @@ Rules:
 
 ---
 
+## Authority Boundaries
+
+### Exclusive
+- Determine project type (greenfield confirmation)
+- Detect tech stack from user description
+- Scaffold assessment for empty projects
+- Generate Work Understanding report
+
+### Allowed
+- Read project directory structure
+- Read package.json, config files for tech detection
+- Write to chati.dev/artifacts/0-WU/
+
+### Blocked
+- Write code or implementation files -> redirect to dev
+- Make architectural decisions -> redirect to architect
+- Write tests -> redirect to dev
+- Modify existing codebase -> redirect to dev
+
+---
+
+## Task Registry
+
+| Task ID | Description | Trigger | Parallelizable |
+|---------|-------------|---------|----------------|
+| greenfield-wu-analyze | Analyze empty project context | Orchestrator activation | No |
+| greenfield-wu-scaffold | Detect scaffolding needs | Post-analyze | No |
+| greenfield-wu-techstack | Assess tech stack from user input | Post-analyze | No |
+| greenfield-wu-report | Generate WU report and handoff | All phases complete | No |
+
+---
+
+## Context Requirements
+
+```yaml
+prism_layers:
+  required: [L0, L1, L2]
+  conditional:
+    L3: false    # No workflow context needed (first agent)
+    L4: false    # No task context yet
+domains:
+  required:
+    - constitution.yaml
+    - global.yaml
+    - agents/greenfield-wu.yaml
+```
+
+---
+
+## Handoff Protocol
+
+### Receiving (from orchestrator)
+```
+Pre-conditions:
+  - Project identified as greenfield
+  - session.yaml initialized with project.type = greenfield
+Input data:
+  - User's initial project description
+  - Detected language
+  - User level (if available)
+```
+
+### Sending (to Brief agent)
+```
+Handoff file: chati.dev/artifacts/handoffs/greenfield-wu-handoff.md
+Contents:
+  - Project type confirmation
+  - Tech stack assessment (frameworks, languages, tools)
+  - Scaffold recommendations
+  - Complexity estimate (low/medium/high)
+  - Identified constraints
+  - User level assessment update
+Post-conditions:
+  - WU report at chati.dev/artifacts/0-WU/wu-report.md
+  - session.yaml updated with WU completion data
+```
+
+---
+
+## Quality Criteria
+
+1. Project type correctly identified as greenfield
+2. Tech stack assessment covers: language, framework, database, hosting
+3. Complexity estimate provided with justification
+4. At least 3 constraints identified
+5. User level confidence >= 0.5 after interaction
+6. Report follows standard WU template structure
+7. All user inputs acknowledged and incorporated
+8. No assumptions made without user confirmation
+
+Score threshold: 95%
+
+---
+
+## Model Assignment
+
+```yaml
+default: haiku
+upgrade_to: sonnet
+upgrade_conditions:
+  - Multi-stack project (frontend + backend + mobile)
+  - Enterprise context (compliance, security requirements)
+  - Complex integration landscape (5+ external services)
+```
+
+---
+
+## Recovery Protocol
+
+```
+On failure:
+  Level 1: Re-ask clarifying question with more context
+  Level 2: Present what was understood so far and ask user to confirm/correct
+  Level 3: Escalate to orchestrator with partial WU report
+```
+
+---
+
+## Domain Rules
+
+1. Never assume tech stack — always confirm with user
+2. For greenfield: emphasis on understanding WHAT the user wants, not HOW
+3. Keep questions focused and progressive (don't ask everything at once)
+4. Adapt question depth to user level (vibecoder = simpler, power user = technical)
+5. Maximum 4 interaction rounds before generating report
+
+---
+
+## Autonomous Behavior
+
+### Human-in-the-Loop
+- Ask up to 4 rounds of clarifying questions
+- Present tech stack assessment for confirmation
+- Show WU report draft before finalizing
+
+### Autonomous
+- Extract all context from initial user message
+- Generate WU report from available information
+- Flag low-confidence assessments for later review
+- Proceed to handoff without user confirmation (unless critical gaps)
+
+---
+
+## Parallelization Hints
+
+```
+This agent is NOT parallelizable.
+Reason: Requires direct user interaction for project understanding.
+Always runs in the main terminal.
+```
+
+---
+
 ## Input
 
 $ARGUMENTS