Fix consistency across agents, skills, and documentation

nullhack · nullhack · commit 8a1203232f42 · 2026-04-13T15:44:52.000-04:00
- Update workflow-coordination from 7-step to 8-phase development
- Add architectural-analysis skill to AGENTS.md skills list
- Fix developer agent phase numbering (Phase 0 → Phase 1-8)
- Add Phase 3: Architecture Analysis to developer workflow
- Clarify manager creates test signatures before developer implements
- Update BDD format to UUID traceability format exclusively
- Remove all Example: format references, use UUID format only
- Add TDD compliance to QA checkpoints in Phase 4
- Update gherkin-validation to UUID-required strictness mode
- Fix QA checkpoints across overseer, qa-enforcement, requirements-management
- Update example workflows in AGENTS.md to reflect 8-phase system
- Add architecture analysis phase to QA protocol (6 checkpoints)
diff --git a/.opencode/agents/developer.md b/.opencode/agents/developer.md
@@ -92,73 +92,74 @@ For each source module `python_module_template/<path>/<module>.py`, create a cor
 
 ## Development Workflow with Mandatory QA Gates
 
-### Epic-Based Development Flow
-Projects are organized into Epics containing Features. Each feature follows a strict workflow with mandatory QA checkpoints by the @overseer agent. Development cannot proceed without QA approval at each gate.
-
-### Phase 0: Requirements Gathering (New Features)
-1. **@requirements-gatherer** conducts stakeholder interviews
-2. Creates detailed feature analysis document
-3. Defines acceptance criteria in Given/When/Then format
-4. **QA Gate**: @overseer reviews requirements completeness
-
-### Phase 1: Feature Definition
-1. Use `/skill feature-definition` to refine technical requirements
-2. Create clear functional and non-functional requirements  
-3. Follow SOLID principles and object calisthenics in planning
-4. Update docs/roadmap.md with feature details
-
-### Phase 2: Prototype Validation
-1. Use `/skill prototype-script` to create quick validation scripts
-2. Test API responses, data flows, and core functionality
-3. **COPY output values directly into test file as fixtures/constants**
-4. **DELETE the prototype directory**: `rm -rf prototypes/<name>/`
-5. Prototypes are disposable - tests should be self-contained
-
-### Phase 3: Test-Driven Development
-1. Use `/skill tdd` to create comprehensive test suite
-2. Write tests using BDD naming: `test_<condition>_should_<outcome>`
-3. Include Given/When/Then docstrings in all tests
-4. Ensure tests fail initially (RED phase)
-5. **After test implementation, call `@overseer` to review the work and request changes if needed**
-6. Only proceed after overseer approval
-
-### Phase 4: Signature Design  
+### 8-Phase Development Workflow
+Each feature follows a strict 8-phase workflow with mandatory QA checkpoints by the @overseer agent. Development cannot proceed without QA approval at each gate.
+
+### Phase 1: Requirements Review
+**@manager coordinates, @requirements-gatherer executes**
+1. Review feature details from docs/features/[architecture|business]/backlog/
+2. Validate acceptance criteria completeness and UUID traceability
+3. **QA Gate**: @overseer reviews requirements completeness
+
+### Phase 2: Feature Definition
+**@manager coordinates**
+1. Read and understand feature acceptance criteria
+2. Identify technical scope and integration points
+3. Confirm feature is ready for test signature creation
+4. **QA Gate**: @overseer reviews feature definition quality
+
+### Phase 3: Architecture Analysis
+**@architect executes using /skill architectural-analysis**
+1. Analyze component responsibilities and interfaces
+2. Document architectural decisions (ADRs) if significant
+3. Define technical acceptance criteria for test signatures
+4. **QA Gate**: @overseer reviews architectural soundness
+
+### Phase 4: Test Development (Manager Creates Signatures First)
+**@manager creates signatures, @developer implements**
+**IMPORTANT**: @manager creates test signatures BEFORE @developer implements tests
+1. @manager reads feature acceptance criteria (UUIDs)
+2. @manager creates test function signatures with `raise NotImplementedError`
+3. @manager organizes test folder structure mirroring source
+4. @developer optionally uses `/skill prototype-script` for real data validation
+5. @developer implements test bodies to replace NotImplementedError
+6. Write tests using BDD naming: `test_<condition>_should_<outcome>`
+7. Use @pytest.mark based on test content, hypothesis for pure functions
+8. **QA Gate**: @overseer reviews test signatures and BDD compliance
+
+### Phase 5: Design & Signatures
 1. Use `/skill signature-design` to create function/class signatures
 2. Design interfaces using modern Python (protocols, type hints)
 3. Include complete Google docstrings with real examples
 4. Follow object calisthenics principles
-
-### Phase 5: Architecture Review
-1. Call **@architect** to review the design
-2. Present feature definition, test plan, and proposed signatures
-3. Wait for approval before proceeding to implementation
-4. Address any architectural concerns raised
+5. **QA Gate**: @overseer validates SOLID principle compliance
 
 ### Phase 6: Implementation
 1. Use `/skill implementation` to implement using TDD approach
 2. Implement one method at a time, ensuring tests pass (GREEN phase)
 3. Refactor for quality while keeping tests green (REFACTOR phase)
 4. Follow the exact signatures approved by architect
-5. **QA Gate**: @overseer reviews SOLID/DRY/KISS compliance
+5. **QA Gate**: @overseer reviews SOLID/DRY/KISS/YAGNI compliance
 
 ### Phase 7: Final Quality Assurance
 1. Use `/skill code-quality` to run all quality checks
 2. Ensure linting passes: `task lint`
 3. Verify type checking: `task static-check`
 4. Validate coverage ≥100%: `task test`
 5. Run property-based tests with Hypothesis
-6. **Call `@overseer` for final review before considering the feature complete**
+6. **QA Gate**: @overseer final approval
 
 ### Phase 8: Feature Completion
 1. Move feature to `docs/features/[architecture|business]/completed/` with metadata
-2. System automatically checks for next pending feature
+2. @developer /skill epic-workflow next-feature
 3. If more features exist, return to Phase 1 for next feature
 4. If all complete, proceed to PR creation
 
 ## Available Skills
 - **session-workflow**: Manage multi-session development - read TODO.md, continue from checkpoint, update progress
-- **epic-workflow**: Manage epic-based development with automatic feature progression and QA gates
+- **epic-workflow**: Manage feature-based development with automatic feature progression and QA gates
 - **feature-definition**: Define features with SOLID principles and clear acceptance criteria
+- **architectural-analysis**: Create technical architecture features with system design and ADRs
 - **prototype-script**: Create validation scripts for real data capture
 - **tdd**: Write comprehensive tests using BDD format with pytest/hypothesis
 - **signature-design**: Design modern Python interfaces with protocols and type hints
@@ -170,10 +171,14 @@ Projects are organized into Epics containing Features. Each feature follows a st
 ## Mandatory QA Workflow
 
 **CRITICAL**: The @overseer agent must approve your work at these checkpoints:
-1. **After Requirements**: Requirements completeness and testability
-2. **After TDD**: Test quality, coverage strategy, and BDD compliance  
-3. **After Implementation**: SOLID/DRY/KISS principles and code quality
-4. **Before Feature Complete**: Final quality gate and standards verification
+1. **Phase 1**: Requirements completeness and traceability
+2. **Phase 2**: Feature definition quality
+3. **Phase 3**: Architectural soundness
+4. **Phase 4**: TDD compliance, test quality, coverage strategy, and BDD compliance  
+5. **Phase 5**: SOLID principle compliance
+6. **Phase 6**: SOLID/DRY/KISS/YAGNI principles and code quality
+7. **Phase 7**: Final quality gate and standards verification
+8. **Phase 8**: Feature completion approval
 
 **You cannot proceed without @overseer approval**. If changes are requested:
 - Address all critical issues first
diff --git a/.opencode/agents/manager.md b/.opencode/agents/manager.md
@@ -47,7 +47,7 @@ You are **3rd in the initialization sequence**:
 
 ### 3. Project Protection
 - **CRITICAL**: Never modify `pyproject.toml` without explicit user permission
-- Enforce BDD docstring standards (prefer Example format)
+- Enforce BDD docstring standards (UUID format required)
 - Validate test naming conventions: `test_<condition>_should_<outcome>`
 - Ensure file naming compliance: `*_test.py` suffix
 
@@ -219,16 +219,11 @@ def test_user_login_with_valid_credentials_should_grant_access():
     """
 ```
 
-### Alternative Formats Accepted
-- Scenario-based Gherkin (suggest conversion to Example)
-- Feature-based Gherkin (guide toward Example for test cases)
-- Any valid Gherkin with proper newlines: `"""\n<content>\n"""`
-
 ### Quality Standards Integration
 - Test functions: `test_<condition>_should_<outcome>`
 - Test files: `*_test.py` suffix required
 - Newlines mandatory: Start and end docstrings with newlines
-- Content required: No empty Gherkin keywords
+- UUID required: Every acceptance criteria gets unique UUID from feature
 
 ## Agent Coordination Workflows
 
@@ -270,7 +265,7 @@ def test_user_login_with_valid_credentials_should_grant_access():
 
 ### Feature Overview
 - **Business Value**: [From docs/features/business/backlog/<feature>.md]
-- **Acceptance Criteria**: [Example format criteria]
+- **Acceptance Criteria**: [UUID format: uuid-here: description]
 - **Feature Reference**: See docs/features/business/backlog/<feature>.md or docs/features/architecture/backlog/<feature>.md
 
 [Include all 8 phases with embedded QA checkpoints]
diff --git a/.opencode/agents/overseer.md b/.opencode/agents/overseer.md
@@ -211,7 +211,7 @@ ALL of these conditions are met (NO exceptions):
 - All checklist items pass completely
 - No SOLID principle violations
 - All 9 Object Calisthenics rules satisfied
-- BDD docstrings in preferred Example format with newlines
+- BDD docstrings in UUID format with newlines
 - Test naming follows `test_<condition>_should_<outcome>` pattern
 - File naming uses `*_test.py` suffix
 - No critical security issues
@@ -389,14 +389,14 @@ Function: `test_login_works()`
 
 Problems:
 1. Function name violates convention (should be test_<condition>_should_<outcome>)
-2. Missing BDD docstring with Example format
+2. Missing BDD docstring with UUID format
 3. No Given/When/Then structure
 
 → AUTO-DELEGATING to @developer
 
 Instructions:
 1. Rename function to descriptive format
-2. Add proper BDD docstring with Example format
+2. Add proper BDD docstring with UUID format
 3. Ensure newlines: """\\n<content>\\n"""
 4. Request re-review when complete
 
diff --git a/.opencode/skills/delegation-coordination/SKILL.md b/.opencode/skills/delegation-coordination/SKILL.md
@@ -74,7 +74,7 @@ Define explicit delegation rules and provide guidance for proper agent handoffs
 ```markdown
 1. Complete stakeholder interviews
 2. Create docs/requirements/REQUIREMENTS.md
-3. Generate acceptance criteria with Example format
+3. Generate acceptance criteria with UUID format
 4. → Call @architect for technical review
 ```
 
diff --git a/.opencode/skills/gherkin-validation/SKILL.md b/.opencode/skills/gherkin-validation/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: gherkin-validation
-description: Validate BDD docstrings with Example format preference and proper Gherkin syntax
+description: Validate BDD docstrings with UUID format preference and proper Gherkin syntax
 license: MIT
 compatibility: opencode
 metadata:
@@ -9,7 +9,7 @@ metadata:
 ---
 
 ## What I do
-Validate BDD docstrings in test functions, with a preference for Example format while accepting any valid Gherkin syntax. Ensure proper newline formatting and provide helpful suggestions.
+Validate BDD docstrings in test functions using UUID format for traceability. Ensure proper newline formatting and provide helpful suggestions.
 
 ## When to use me
 - During TDD phase to validate test docstring formats
@@ -19,7 +19,7 @@ Validate BDD docstrings in test functions, with a preference for Example format
 
 ## Required Format: UUID-based Traceability
 
-All test docstrings must use acceptance criteria UUID for traceability, followed by Gherkin steps:
+All test docstrings MUST use acceptance criteria UUID for traceability:
 
 ```python
 def test_user_login_with_valid_credentials_should_grant_access():
@@ -31,45 +31,19 @@ def test_user_login_with_valid_credentials_should_grant_access():
     """
 ```
 
-## Alternative Formats Accepted
-
-### Scenario-based Format
-```python
-def test_invalid_login_should_reject_access():
-    """
-    Scenario: Invalid login attempt
-    Given: A user with incorrect credentials
-    When: Login is attempted
-    Then: Access should be denied
-    And: Error message should be displayed
-    """
-```
-
-### Feature-based Format
-```python
-def test_password_reset_flow_should_work():
-    """
-    Feature: Password reset functionality
-    Scenario: User requests password reset
-    Given: A registered user exists
-    When: Password reset is requested
-    Then: Reset email should be sent
-    And: Temporary token should be generated
-    """
-```
+### Structure
+- UUID followed by colon and brief description (ends with period)
+- Blank line after description
+- Gherkin steps: Given/When/Then with mandatory newlines
+- Each step on its own line
 
 ### Extended Gherkin Keywords
 All valid Gherkin keywords are supported:
-- **Feature**: High-level description
-- **Scenario**: Specific test case
-- **Example**: Concrete illustration (preferred)
 - **Given**: Preconditions or context
-- **When**: Actions or events
-- **Then**: Expected outcomes
-- **And**: Additional conditions/actions/outcomes
-- **But**: Negative conditions/actions/outcomes
-- **Background**: Common setup for multiple scenarios
-- **Rule**: Business rule description
+- **When**: Action or trigger
+- **Then**: Expected outcome
+- **And**: Additional conditions
+- **But**: Contradiction conditions
 
 ## Validation Rules
 
@@ -102,7 +76,6 @@ Given: No ending newline"""
 ### 3. Structure Requirements
 - At minimum: One Gherkin keyword with content
 - Recommended: Logical flow (Given → When → Then)
-- Example format preferred but not required
 
 ## Validation Guidelines
 
@@ -114,30 +87,27 @@ Given: No ending newline"""
 - [ ] Proper colon after each keyword
 
 ### Suggestion Messages
-For improving docstrings when not using required UUID format:
+For improving docstrings to required UUID format:
 ```python
 # For missing UUID
 "Test docstring must start with acceptance criteria UUID for traceability"
 
-# For old Example format  
-"Convert 'Example:' to UUID format: 'uuid: description.' with blank line before Gherkin steps"
-
 # For missing structure
 "Add 'Given:' context and 'When:' action to complete the test scenario"
 ```
 
 ### suggest_uuid_format(docstring: str) -> str
-Convert other formats to required UUID format:
+Convert legacy formats to required UUID format:
 ```python
-# Input: Old Example format
+# Input: Legacy format
 original = """
-Example: User login
+User login validation.
 Given: Valid credentials
 When: Login submitted
 Then: Access granted
 """
 
-# Output: UUID-based suggestion
+# Output: UUID-based format
 suggested = suggest_uuid_format(original)
 # """
 # 123e4567-e89b-12d3-a456-426614174000: User login validation.
@@ -213,9 +183,6 @@ When creating new tests, enforce UUID traceability format:
 # For missing UUID
 "Test docstring must start with acceptance criteria UUID for traceability"
 
-# For old Example format  
-"Convert 'Example:' to UUID format with blank line before Gherkin steps"
-
 # For missing structure
 "Add 'Given:' context and 'When:' action to complete the test scenario"
 ```
@@ -248,7 +215,7 @@ When reviewing test files manually, check:
 ### Strictness Levels
 ```yaml
 gherkin_validation:
-  strictness: "prefer_example"  # "prefer_example", "accept_any", "require_example"
+  strictness: "uuid_required"  # "uuid_required", "accept_any"
   require_newlines: true
   min_keywords: 2  # Minimum Given/When/Then structure
   allow_empty_sections: false
@@ -269,8 +236,8 @@ fail_on_invalid = true
 1. **Parse docstring** for Gherkin keywords
 2. **Check newline formatting** (strict requirement)
 3. **Validate keyword syntax** and content
-4. **Determine format type** (Example, Scenario, Feature, etc.)
-5. **Generate suggestions** if not using preferred format
+4. **Validate UUID traceability** format
+5. **Generate suggestions** if not using required UUID format
 6. **Report results** with specific improvement guidance
 
-Remember: The goal is to guide developers toward the preferred Example format while maintaining flexibility and not breaking existing valid Gherkin documentation.
+Remember: All test docstrings MUST use UUID traceability format.
diff --git a/.opencode/skills/qa-enforcement/SKILL.md b/.opencode/skills/qa-enforcement/SKILL.md
@@ -363,15 +363,15 @@ def validate_bdd_compliance(test_file: str) -> BddValidationResult:
 
 ### Pre-Implementation Gate
 - [ ] Requirements align with business value
-- [ ] Acceptance criteria use Example format
+- [ ] Acceptance criteria use UUID format
 - [ ] Technical design follows SOLID principles
 - [ ] Architecture supports Object Calisthenics compliance
 
 ### Post-TDD Gate  
 - [ ] All test functions follow `test_<condition>_should_<outcome>` naming
 - [ ] All test files use `*_test.py` naming convention
 - [ ] All test docstrings use proper Gherkin format with newlines
-- [ ] Example format preferred, alternatives acceptable
+- [ ] UUID format required for all acceptance criteria
 - [ ] Test coverage strategy is comprehensive
 
 ### Post-Implementation Gate
diff --git a/.opencode/skills/requirements-management/SKILL.md b/.opencode/skills/requirements-management/SKILL.md
@@ -115,7 +115,7 @@ docs/requirements/
 ### Before Interview
 1. **Research**: Understand the domain and problem space
 2. **Prepare Questions**: Business value, user needs, constraints
-3. **Set Expectations**: Explain Example format for acceptance criteria
+3. **Set Expectations**: Explain UUID format for acceptance criteria
 
 ### Interview Questions Template
 1. "What problem are you trying to solve?"
diff --git a/.opencode/skills/workflow-coordination/SKILL.md b/.opencode/skills/workflow-coordination/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: workflow-coordination
-description: Enforce 7-step development cycle with proper phase progression and QA gates
+description: Enforce 8-phase development cycle with proper phase progression and QA gates
 license: MIT
 compatibility: opencode
 metadata:
diff --git a/AGENTS.md b/AGENTS.md
