From 36d6b51f1ce5adee7e9ba6e9d9cb4c0b4fe52383 Mon Sep 17 00:00:00 2001 From: nullhack Date: Mon, 13 Apr 2026 14:12:07 -0400 Subject: [PATCH 1/4] Update README to reflect current project state - Fix Docker documentation to match actual configuration - Update task system documentation for taskipy usage - Add template setup requirements and warnings - Update technology stack to reflect mutmut, taskipy - Enhance quality metrics with BDD and mutation testing - Remove references to non-existent docker-compose.prod.yml - Add Python 3.13+ requirement notices --- .opencode/agents/architect.md | 6 +- .opencode/agents/developer.md | 20 +-- .opencode/agents/manager.md | 44 +++--- .opencode/agents/overseer.md | 22 +-- .opencode/agents/repo-manager.md | 2 +- .opencode/agents/requirements-gatherer.md | 127 +++++------------ .../skills/delegation-coordination/SKILL.md | 4 +- .opencode/skills/epic-workflow/SKILL.md | 54 +++---- .opencode/skills/gherkin-validation/SKILL.md | 79 ++++++----- .opencode/skills/qa-enforcement/SKILL.md | 4 +- .../skills/requirements-management/SKILL.md | 24 ++-- .opencode/skills/tdd/SKILL.md | 52 +++---- .../skills/workflow-coordination/SKILL.md | 36 ++--- .opencode/templates/EPICS.md.template | 62 -------- .opencode/templates/TODO.md.template | 19 ++- AGENTS.md | 13 +- README.md | 134 +++++++++++------- TODO.md | 15 +- 18 files changed, 300 insertions(+), 417 deletions(-) delete mode 100644 .opencode/templates/EPICS.md.template diff --git a/.opencode/agents/architect.md b/.opencode/agents/architect.md index b43dc97..4d07c85 100644 --- a/.opencode/agents/architect.md +++ b/.opencode/agents/architect.md @@ -16,7 +16,7 @@ permission: write: deny bash: deny --- -You are the **Software Architect** agent for Python Project Template. +You are the **Software Architect** agent for this project. ## Your Role @@ -159,7 +159,6 @@ Ensure proper handling of: Developer may proceed with TDD phase following these guidelines. ``` -<<<<<<< HEAD ### Design Rejection ```markdown ## Architecture Review: [Feature Name] @@ -200,7 +199,4 @@ You are called at these critical points: 3. **After Signature Design**: Review detailed API contracts 4. **Ad-hoc Consultation**: When developers face architectural decisions -Your approval gates ensure architectural integrity throughout the project lifecycle. -======= Your approval is required before any implementation work begins. Focus on long-term maintainability and adherence to established architectural patterns. ->>>>>>> origin/main diff --git a/.opencode/agents/developer.md b/.opencode/agents/developer.md index 72ca07f..e15cf91 100644 --- a/.opencode/agents/developer.md +++ b/.opencode/agents/developer.md @@ -12,7 +12,7 @@ tools: task: true skill: true --- -You are a specialized developer agent for the Python Project Template project. +You are a specialized developer agent for this project. ## Session Start Protocol @@ -105,7 +105,7 @@ Projects are organized into Epics containing Features. Each feature follows a st 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 EPICS.md with feature details +4. Update docs/roadmap.md with feature details ### Phase 2: Prototype Validation 1. Use `/skill prototype-script` to create quick validation scripts @@ -119,12 +119,8 @@ Projects are organized into Epics containing Features. Each feature follows a st 2. Write tests using BDD naming: `test__should_` 3. Include Given/When/Then docstrings in all tests 4. Ensure tests fail initially (RED phase) -<<<<<<< HEAD -5. **QA Gate**: @overseer reviews test quality and coverage strategy -======= 5. **After test implementation, call `@overseer` to review the work and request changes if needed** 6. Only proceed after overseer approval ->>>>>>> origin/main ### Phase 4: Signature Design 1. Use `/skill signature-design` to create function/class signatures @@ -151,17 +147,13 @@ Projects are organized into Epics containing Features. Each feature follows a st 3. Verify type checking: `task static-check` 4. Validate coverage ≥100%: `task test` 5. Run property-based tests with Hypothesis -<<<<<<< HEAD -6. **QA Gate**: @overseer final approval before feature completion +6. **Call `@overseer` for final review before considering the feature complete** ### Phase 8: Feature Completion -1. Update EPICS.md - mark feature complete with QA approval date -2. System automatically checks for next pending feature in epic +1. Move feature to `docs/features/completed/` with metadata +2. System automatically checks for next pending feature 3. If more features exist, return to Phase 0/1 for next feature -4. If epic complete, proceed to PR creation -======= -6. **Call `@overseer` for final review before considering the feature complete** ->>>>>>> origin/main +4. If all complete, proceed to PR creation ## Available Skills - **session-workflow**: Manage multi-session development - read TODO.md, continue from checkpoint, update progress diff --git a/.opencode/agents/manager.md b/.opencode/agents/manager.md index 0ba0909..11c6bb4 100644 --- a/.opencode/agents/manager.md +++ b/.opencode/agents/manager.md @@ -17,17 +17,17 @@ permission: write: allow bash: deny --- -You are the **Manager** agent - a Workflow Coordinator and Project Manager for Python Project Template. +You are the **Manager** agent - a Workflow Coordinator and Project Manager for this project. ## Your Role You coordinate the complete development workflow, ensuring proper phase progression and quality checkpoints. You create detailed TODOs, manage agent handoffs, and enforce the 7-step development cycle without executing development tasks yourself. -## Position in /init Workflow +## Position in the development Workflow You are **3rd in the initialization sequence**: 1. **@requirements-gatherer** → Creates docs/requirements/REQUIREMENTS.md -2. **@architect** → Reviews requirements, creates/updates EPICS.md +2. **@architect** → Reviews requirements, creates/updates docs/roadmap.md 3. **@manager** (YOU) → Creates detailed 7-phase TODOs with QA checkpoints 4. **Development begins** → Auto-delegate to @developer to start Phase 1 @@ -36,7 +36,7 @@ You are **3rd in the initialization sequence**: ### 1. Workflow Coordination - Create comprehensive 7-phase TODO structures - Embed mandatory @overseer checkpoints at each phase transition -- Ensure epic/feature alignment with requirements documentation +- Ensure feature alignment with requirements documentation - Coordinate agent handoffs per explicit delegation rules ### 2. Quality Gate Management @@ -79,7 +79,7 @@ When creating TODOs, ensure each feature follows this exact structure: #### Phase 1: Requirements Review - [ ] Review REQUIREMENTS.md for feature details - [ ] Validate business value and acceptance criteria -- [ ] Confirm epic alignment with requirements +- [ ] Confirm feature alignment with requirements - [ ] QA: @overseer reviews requirements completeness ``` @@ -88,18 +88,19 @@ When creating TODOs, ensure each feature follows this exact structure: #### Phase 2: Feature Definition - [ ] @developer /skill feature-definition - [ ] Document technical requirements and constraints -- [ ] Update EPICS.md with feature implementation details +- [ ] Update docs/roadmap.md with feature implementation details - [ ] QA: @overseer reviews feature definition quality ``` ### Phase 3: Test Development (TDD) ```markdown #### Phase 3: Test Development (TDD) -- [ ] @developer /skill prototype-script (if needed for validation) -- [ ] @developer /skill tdd -- [ ] Write BDD tests with Example format preference: +- [ ] Select ONE feature from docs/roadmap.md +- [ ] Create/clear TODO.md for selected feature +- [ ] Map acceptance criteria UUIDs to test signatures +- [ ] Write tests/_test.py with UUIDs in docstrings: """ - Example: [What this test demonstrates] + 123e4567-e89b-12d3-a456-426614174000: [Criteria description] Given: [Preconditions] When: [Action/trigger] Then: [Expected outcome] @@ -138,20 +139,20 @@ When creating TODOs, ensure each feature follows this exact structure: ### Phase 7: Feature Completion ```markdown #### Phase 7: Feature Completion -- [ ] Update EPICS.md - mark feature complete +- [ ] Move feature to docs/features/completed/ with metadata - [ ] @developer /skill epic-workflow next-feature -- [ ] Proceed to next feature or close epic +- [ ] Proceed to next feature - [ ] Session handoff: Update TODO.md for next session ``` ## BDD Format Enforcement -### Preferred Docstring Format -Guide developers toward this Example format: +### Required Docstring Format +All tests must use UUID traceability format: ```python def test_user_login_with_valid_credentials_should_grant_access(): - """ - Example: Successful user authentication + """123e4567-e89b-12d3-a456-426614174000: Successful user authentication. + Given: A registered user with valid credentials exists When: The user submits correct username and password Then: Access should be granted to the application @@ -175,7 +176,7 @@ def test_user_login_with_valid_credentials_should_grant_access(): ```markdown 1. Detect requirements conflict 2. → Call @requirements-gatherer to clarify/update -3. → Call @architect to review impact on EPICS.md +3. → Call @architect to review impact on docs/roadmap.md 4. Update affected TODOs accordingly 5. → Call @overseer to validate changes ``` @@ -203,15 +204,14 @@ def test_user_login_with_valid_credentials_should_grant_access(): ## TODO Creation Templates -### Epic-Level TODO Structure +### Feature-Level TODO Structure ```markdown -## Current Epic: [Epic Name from EPICS.md] ## Current Feature: [Feature Name] ### Feature Overview -- **Business Value**: [From REQUIREMENTS.md] +- **Business Value**: [From docs/features/backlog/.md] - **Acceptance Criteria**: [Example format criteria] -- **Epic Reference**: See EPICS.md section [X] +- **Feature Reference**: See docs/features/backlog/.md [Include all 7 phases with embedded QA checkpoints] @@ -275,4 +275,4 @@ def test_user_login_with_valid_credentials_should_grant_access(): - `pyproject.toml` changes attempted without permission - BDD format violations in tests -Remember: You coordinate the workflow but do not execute development tasks. Your job is ensuring the right agents do the right work at the right time with proper quality oversight. Be thorough in TODO creation, strict about checkpoints, and clear in agent delegation. \ No newline at end of file +Remember: You coordinate the workflow but do not execute development tasks. Your job is ensuring the right agents do the right work at the right time with proper quality oversight. Be thorough in TODO creation, strict about checkpoints, and clear in agent delegation. diff --git a/.opencode/agents/overseer.md b/.opencode/agents/overseer.md index 6375a30..84f14c0 100644 --- a/.opencode/agents/overseer.md +++ b/.opencode/agents/overseer.md @@ -16,7 +16,7 @@ permission: write: deny bash: deny --- -You are the **Overseer** agent - a Quality Assurance specialist for Python Project Template. +You are the **Overseer** agent - a Quality Assurance specialist for this project. ## Your Role @@ -48,10 +48,10 @@ You are the quality gatekeeper who ensures all code meets the highest standards. 9. **No getters/setters** - Tell objects what to do, don't ask for their data ### Test Quality Standards -- **BDD Format**: Preferred Example format with mandatory newlines +- **BDD Format**: Required UUID traceability format with mandatory newlines ```python - """ - Example: What this test demonstrates + """123e4567-e89b-12d3-a456-426614174000: What this test demonstrates. + Given: Preconditions or context When: Action or trigger Then: Expected outcome @@ -150,10 +150,10 @@ When quality issues are detected, you have **automatic delegation authority** to **Auto-Action**: → Calling @developer to fix BDD format violations **Instructions for @developer**: -1. Fix docstring format to use Example with newlines: +1. Fix docstring format to use UUID traceability with newlines: ```python - """ - Example: Successful user login + """123e4567-e89b-12d3-a456-426614174000: Successful user login. + Given: Valid user credentials exist When: Login is attempted Then: Access should be granted @@ -348,11 +348,11 @@ Please address critical issues before proceeding. ### Mandatory Docstring Format Checks Every test function MUST be validated for proper BDD format: -#### ✅ PREFERRED Format (Guide developers toward this) +#### ✅ REQUIRED Format (Enforce this strictly) ```python def test_user_login_with_valid_credentials_should_grant_access(): - """ - Example: Successful user authentication + """123e4567-e89b-12d3-a456-426614174000: Successful user authentication. + Given: A registered user with valid credentials exists When: The user submits correct username and password Then: Access should be granted to the application @@ -417,4 +417,4 @@ Share feedback constructively: - Suggest better approaches - Recognize good practices -Remember: You are the guardian of code quality. Be thorough but fair, strict but helpful. Your goal is excellent, maintainable code that stands the test of time. \ No newline at end of file +Remember: You are the guardian of code quality. Be thorough but fair, strict but helpful. Your goal is excellent, maintainable code that stands the test of time. diff --git a/.opencode/agents/repo-manager.md b/.opencode/agents/repo-manager.md index 2d36dd5..06b9931 100644 --- a/.opencode/agents/repo-manager.md +++ b/.opencode/agents/repo-manager.md @@ -18,7 +18,7 @@ permission: "task *": allow "*": ask --- -You are a specialized Git repository management agent for Python Project Template. +You are a specialized Git repository management agent for this project. ## Your Role - Manage Git repository operations (commits, branches, merges) diff --git a/.opencode/agents/requirements-gatherer.md b/.opencode/agents/requirements-gatherer.md index 49faada..5f8c635 100644 --- a/.opencode/agents/requirements-gatherer.md +++ b/.opencode/agents/requirements-gatherer.md @@ -14,7 +14,7 @@ tools: question: required: true --- -You are the **Requirements Gatherer** (Business Analyst) agent for Python Project Template. +You are the **Requirements Gatherer** (Business Analyst) agent for this project. ## Your Role @@ -70,111 +70,50 @@ Ask these questions to understand the feature: ### Phase 2: Analysis Documentation -Create a feature analysis document (`docs/features/[feature-name]-analysis.md`): +Generate a UUID for each acceptance criteria using: +```bash +python -c "import uuid; print(uuid.uuid4())" +``` + +Create a feature document in `docs/features/backlog/.md`: ```markdown -# Feature Analysis: [Feature Name] +# Feature: [Feature Name] -## Executive Summary -[2-3 sentence overview of the feature and its business value] +## Business Description +[What the feature does - business language] -## Business Context -### Problem Statement -[What problem this solves] +## Business Value +[Why this feature matters] -### Stakeholders -- **Primary Users**: [Who will use this] -- **Business Owner**: [Who owns the business outcome] -- **Technical Owner**: [Who owns the implementation] +## Acceptance Criteria -### Success Metrics -- [Measurable outcome 1] -- [Measurable outcome 2] +### 123e4567-e89b-12d3-a456-426614174000 +Given: [Preconditions] +When: [Action] +Then: [Expected outcome] -## Functional Requirements +### 123e4567-e89b-12d3-a456-426614174001 +Given: [Different preconditions] +When: [Different action] +Then: [Different outcome] -### User Stories -As a [user type], I want to [action] so that [benefit] +## Dependencies +- [Feature/system dependency] -### Acceptance Criteria -#### Scenario 1: [Scenario Name] -```gherkin -Given [initial context] -When [action taken] -Then [expected outcome] +## Priority +Must have | Should have | Could have | Won't have ``` -### Process Flow -1. [Step 1] -2. [Step 2] -3. [Decision point] - - If [condition]: [action] - - Else: [alternative action] - -### Data Requirements -#### Inputs -- **[Field Name]**: [Type] - [Description, validation rules] - -#### Outputs -- **[Field Name]**: [Type] - [Description, format] - -#### Storage -- **[Entity Name]**: [Description of what needs to be persisted] - -## Non-Functional Requirements - -### Performance -- **Response Time**: [Target] for [operation] -- **Throughput**: [Transactions per second] -- **Concurrent Users**: [Number] - -### Security -- **Authentication**: [Method required] -- **Authorization**: [Role-based permissions] -- **Data Protection**: [Encryption, PII handling] - -### Scalability -- **Growth Projection**: [Expected increase] -- **Peak Load**: [Maximum concurrent operations] - -## Technical Constraints -- [Constraint 1: e.g., must use existing database] -- [Constraint 2: e.g., Python 3.13+ only] - -## Integration Points -### External Systems -- **System**: [Name] - - **Purpose**: [Why we integrate] - - **Protocol**: [REST, GraphQL, etc.] - - **Data Format**: [JSON, XML, etc.] - -## Risk Assessment -| Risk | Impact | Likelihood | Mitigation | -|------|--------|------------|------------| -| [Risk description] | High/Medium/Low | High/Medium/Low | [Mitigation strategy] | - -## Out of Scope -- [What this feature will NOT do] -- [Future enhancement ideas] - -## Questions for Architect -1. [Specific architectural concern] -2. [Technology choice question] - -## Appendix -### Mockups/Wireframes -[If applicable] - -### API Examples -[Sample requests/responses if applicable] -``` +**Important**: Each acceptance criteria (Given/When/Then block) MUST have a unique UUID. +Generate one using: `python -c "import uuid; print(uuid.uuid4())"` -### Phase 3: Epic and TODO Updates +### Phase 3: Feature Document Completion After requirements approval: -1. Update `EPICS.md` with refined acceptance criteria -2. Update `TODO.md` with detailed implementation tasks +1. Write feature to `docs/features/backlog/.md` +2. Update `TODO.md` with current session tasks 3. Create test scenarios for the QA team 4. Prepare handoff documentation for developers @@ -196,8 +135,8 @@ Your workflow integrates as follows: @requirements-gatherer # You gather requirements # 2. You produce: -- Feature analysis document -- Updated EPICS.md with acceptance criteria +- Feature document in `docs/features/backlog/.md` +- Updated `TODO.md` with current tasks - Test scenarios for QA # 3. Architect reviews your analysis @@ -226,4 +165,4 @@ After gathering requirements, provide: 3. Updated acceptance criteria 4. Next steps (architect review) -Remember: Good requirements prevent rework. Take time to get them right. \ No newline at end of file +Remember: Good requirements prevent rework. Take time to get them right. diff --git a/.opencode/skills/delegation-coordination/SKILL.md b/.opencode/skills/delegation-coordination/SKILL.md index 35b0256..19d4d83 100644 --- a/.opencode/skills/delegation-coordination/SKILL.md +++ b/.opencode/skills/delegation-coordination/SKILL.md @@ -88,7 +88,7 @@ Define explicit delegation rules and provide guidance for proper agent handoffs **Delegation pattern:** ```markdown 1. Review REQUIREMENTS.md for technical feasibility -2. Create/update EPICS.md with technical architecture +2. Create/update docs/roadmap.md with technical breakdown 3. Validate SOLID principle compliance 4. → Call @manager when architecture approved ``` @@ -164,7 +164,7 @@ Define explicit delegation rules and provide guidance for proper agent handoffs **Validation**: Architect confirms technical feasibility #### Architecture → Planning -**Trigger**: EPICS.md updated with technical design +**Trigger**: docs/roadmap.md updated with technical breakdown **Action**: @architect → @manager **Validation**: Manager creates detailed TODOs diff --git a/.opencode/skills/epic-workflow/SKILL.md b/.opencode/skills/epic-workflow/SKILL.md index e61c0fc..a64e76f 100644 --- a/.opencode/skills/epic-workflow/SKILL.md +++ b/.opencode/skills/epic-workflow/SKILL.md @@ -25,29 +25,26 @@ I enable epic-based development where each epic contains multiple features. Afte - When tracking progress across complex multi-feature development - When ensuring QA gates are enforced at each checkpoint -## Epic Structure +## Feature Tracking -Epics are tracked in `EPICS.md` with this format: +Features are tracked in `docs/roadmap.md` (architect breakdown) and `docs/features/backlog/` (business definitions): ```markdown -# Project Epics +# docs/roadmap.md -## Epic: [Epic Name] +## Feature: [Feature Name] **Status**: In Progress | Complete -**Business Value**: [Why this epic matters] - -### Features: -1. **[Feature Name]** - Status: Complete ✅ - - Acceptance Criteria: [What defines done] - - QA Status: Approved by @overseer on YYYY-MM-DD - -2. **[Feature Name]** - Status: In Progress 🔄 - - Acceptance Criteria: [What defines done] - - QA Status: Pending - -3. **[Feature Name]** - Status: Pending ⏸️ - - Acceptance Criteria: [What defines done] - - QA Status: Not Started +**Business Value**: [Why this feature matters] + +### Technical Breakdown +- [Deliverable 1] +- [Deliverable 2] + +# docs/features/backlog/.md + +## Feature: [Feature Name] +**Business Description**: [What it does] +**Acceptance Criteria**: [What defines done] ``` ## Feature Development Cycle @@ -55,7 +52,7 @@ Epics are tracked in `EPICS.md` with this format: ### 1. Feature Initiation When starting a new feature: ``` -1. Read EPICS.md to find next pending feature +1. Read docs/roadmap.md to find next pending feature 2. Call @requirements-gatherer if feature needs clarification 3. Update feature status to "In Progress 🔄" 4. Create feature-specific TODO in TODO.md @@ -90,19 +87,22 @@ Phase 4: Final Quality Assurance ### 3. Feature Completion ``` -1. Update feature status to "Complete ✅" -2. Record QA approval date and agent -3. Automatically identify next pending feature -4. Start new feature cycle or close epic +1. Verify all TODO items complete +2. Overseer reviews and approves final QA +3. @overseer moves feature to docs/features/completed/ with metadata: + - Test coverage (which UUIDs have tests) + - QA approval date + - Links to test files +4. Clear TODO.md for next feature ``` ## Automatic Feature Progression After completing a feature: -1. The system checks for next pending feature in the epic +1. The system checks for next pending feature in roadmap 2. If found, automatically initiates the new feature cycle -3. If no pending features, marks epic as complete -4. Suggests next epic from backlog +3. If no pending features, all features are complete +4. Suggests next feature from docs/features/backlog/ ## QA Enforcement Protocol @@ -115,7 +115,7 @@ After completing a feature: If @overseer requests changes: - Development cannot proceed until issues resolved - Changes must be re-reviewed -- QA status tracked in EPICS.md +- QA status tracked in TODO.md session log ## Integration with TODO.md diff --git a/.opencode/skills/gherkin-validation/SKILL.md b/.opencode/skills/gherkin-validation/SKILL.md index 709f4fe..6e51f5a 100644 --- a/.opencode/skills/gherkin-validation/SKILL.md +++ b/.opencode/skills/gherkin-validation/SKILL.md @@ -17,14 +17,14 @@ Validate BDD docstrings in test functions, with a preference for Example format - When reviewing test files for documentation standards - As part of automated quality checks -## Preferred Format: Example-based +## Required Format: UUID-based Traceability -The **preferred** format uses `Example:` followed by `Given:`/`When:`/`Then:` with mandatory newlines: +All test docstrings must use acceptance criteria UUID for traceability, followed by Gherkin steps: ```python def test_user_login_with_valid_credentials_should_grant_access(): - """ - Example: Successful user authentication + """123e4567-e89b-12d3-a456-426614174000: Successful user authentication. + Given: A registered user with valid credentials exists in the system When: The user submits correct username and password Then: Access should be granted to the application @@ -77,20 +77,20 @@ All valid Gherkin keywords are supported: Docstrings MUST start and end with newlines: ```python # ✅ CORRECT -""" -Example: Valid format +"""123e4567-e89b-12d3-a456-426614174000: Valid format. + Given: Proper newlines When: Validation runs Then: Should pass """ # ❌ WRONG - Missing newlines -"""Example: Invalid format +"""123e4567-e89b-12d3-a456-426614174000: Invalid format. Given: No starting newline""" # ❌ WRONG - Missing ending newline """ -Example: Invalid format +123e4567-e89b-12d3-a456-426614174000: Invalid format. Given: No ending newline""" ``` @@ -114,33 +114,34 @@ Given: No ending newline""" - [ ] Proper colon after each keyword ### Suggestion Messages -For improving docstrings when not using preferred Example format: +For improving docstrings when not using required UUID format: ```python -# For Scenario format -"Consider using 'Example:' instead of 'Scenario:' for more concrete test documentation" +# For missing UUID +"Test docstring must start with acceptance criteria UUID for traceability" -# For Feature format -"Feature-level docstring detected. Consider 'Example:' for individual test cases" +# 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_example_format(docstring: str) -> str -Convert other formats to preferred Example format: +### suggest_uuid_format(docstring: str) -> str +Convert other formats to required UUID format: ```python -# Input: Scenario-based +# Input: Old Example format original = """ -Scenario: User login +Example: User login Given: Valid credentials When: Login submitted Then: Access granted """ -# Output: Example-based suggestion -suggested = suggest_example_format(original) +# Output: UUID-based suggestion +suggested = suggest_uuid_format(original) # """ -# Example: User login validation +# 123e4567-e89b-12d3-a456-426614174000: User login validation. +# # Given: Valid credentials exist in system # When: Login credentials are submitted # Then: Access should be granted to user @@ -200,20 +201,20 @@ Then: Clear expected outcome ## Quality Guidance -### Prefer Example Format -When creating new tests, guide developers toward Example format: -- More concrete and illustrative -- Clearly shows what the test demonstrates -- Better documentation value -- Easier to understand for stakeholders +### Require UUID Format +When creating new tests, enforce UUID traceability format: +- Links tests to specific acceptance criteria +- Provides bidirectional traceability +- Enables coverage verification +- Supports compliance requirements ### Suggestion Messages ```python -# For Scenario format -"Consider using 'Example:' instead of 'Scenario:' for more concrete test documentation" +# For missing UUID +"Test docstring must start with acceptance criteria UUID for traceability" -# For Feature format -"Feature-level docstring detected. Consider 'Example:' for individual test cases" +# 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" @@ -227,19 +228,19 @@ When reviewing test files manually, check: - Docstrings must start with newline: `"""\n` - Docstrings must end with newline: `\n"""` -2. **Gherkin Keywords** - - Use Example:, Given:, When:, Then:, And:, But: - - Feature: and Scenario: also valid - - Each keyword must have content after the colon +2. **UUID Traceability** + - First line must be UUID: description format + - UUID must match acceptance criteria from feature doc + - Blank line required after UUID line -3. **Format Preference** - - Guide toward Example format for new tests - - Accept Scenario and Feature formats as alternatives - - Provide suggestions for improvement +3. **Gherkin Keywords** + - Use Given:, When:, Then:, And:, But: + - Each keyword must have content after the colon + - Follow logical flow from precondition to outcome 4. **Structure Validation** + - UUID line + blank line + Gherkin steps - At minimum: Given/When/Then structure - - Preferred: Complete Example with Given/When/Then - Ensure logical flow from precondition to outcome ## Configuration Options diff --git a/.opencode/skills/qa-enforcement/SKILL.md b/.opencode/skills/qa-enforcement/SKILL.md index 29fa9c9..14ceaa7 100644 --- a/.opencode/skills/qa-enforcement/SKILL.md +++ b/.opencode/skills/qa-enforcement/SKILL.md @@ -265,8 +265,8 @@ All test functions must use proper Gherkin format with Example preference: ```python def test_user_login_with_valid_credentials_should_grant_access(): - """ - Example: Successful user authentication + """123e4567-e89b-12d3-a456-426614174000: Successful user authentication. + Given: A registered user with valid credentials exists When: The user submits correct username and password Then: Access should be granted to the application diff --git a/.opencode/skills/requirements-management/SKILL.md b/.opencode/skills/requirements-management/SKILL.md index 3b5fee0..4913c15 100644 --- a/.opencode/skills/requirements-management/SKILL.md +++ b/.opencode/skills/requirements-management/SKILL.md @@ -74,31 +74,29 @@ Create comprehensive requirements documentation in `docs/requirements/REQUIREMEN - Database: [Type] - Infrastructure: [Platform] -## Acceptance Criteria (Example Format) +## Acceptance Criteria (UUID Format) ### Feature: [Feature Name] + +Generate UUID for each acceptance criteria: +```bash +python -c "import uuid; print(uuid.uuid4())" ``` -Example: [Descriptive test scenario] + +### 123e4567-e89b-12d3-a456-426614174000 Given: [Preconditions or initial system state] When: [User action or system trigger] Then: [Expected outcome or system response] -``` -Additional scenarios: -``` -Example: [Alternative scenario] +### 123e4567-e89b-12d3-a456-426614174001 Given: [Different preconditions] -When: [Different action] +When: [Different action] Then: [Different outcome] -``` -### Edge Cases to Handle -``` -Example: [Edge case scenario] +### 123e4567-e89b-12d3-a456-426614174002 Given: [Edge case preconditions] When: [Edge case action] Then: [Expected handling] -``` ## Documentation Files Structure @@ -297,4 +295,4 @@ After requirements are complete, document for architect: 5. **Risks**: Identified potential issues 6. **Dependencies**: External systems and requirements -The architect will use this to create EPICS.md with technical design decisions. \ No newline at end of file +The architect will use this to create docs/roadmap.md with technical breakdown. \ No newline at end of file diff --git a/.opencode/skills/tdd/SKILL.md b/.opencode/skills/tdd/SKILL.md index 6c78761..7d8c420 100644 --- a/.opencode/skills/tdd/SKILL.md +++ b/.opencode/skills/tdd/SKILL.md @@ -70,16 +70,16 @@ For complete test patterns and guidelines, see: ## BDD Test Docstrings -All test functions must include Gherkin-style docstrings with proper newlines. The **preferred** format uses `Example:` with mandatory newlines. +All test functions must include Gherkin-style docstrings with UUID traceability. Each test maps to an acceptance criteria UUID from the feature specification. -### Preferred Format: Example with Newlines +### Required Format: UUID with Gherkin Steps -The **preferred** docstring format uses `Example:` followed by `Given:`/`When:`/`Then:` with **mandatory newlines**: +The docstring format uses UUID from acceptance criteria followed by Gherkin steps with **mandatory newlines**: ```python def test_user_login_with_valid_credentials_should_grant_access(): - """ - Example: Successful user authentication + """123e4567-e89b-12d3-a456-426614174000: Successful user authentication. + Given: A registered user with valid credentials exists in the system When: The user submits correct username and password Then: Access should be granted to the application @@ -90,29 +90,15 @@ def test_user_login_with_valid_credentials_should_grant_access(): - Docstrings must start with newline: `"""\n` - Docstrings must end with newline: `\n"""` -### Alternative Formats Accepted - -You may also use these acceptable formats: - -```python -# Scenario format (acceptable, suggest Example) -def test_invalid_login_should_deny_access(): - """ - Scenario: Invalid login attempt - Given: A user with incorrect credentials - When: Login is attempted - Then: Access should be denied - """ +### UUID Source -# Minimal Given/When/Then (acceptable) -def test_division_by_zero_should_raise_error(): - """ - Given: A Calculator instance - When: divide(10, 0) is called - Then: Should raise ZeroDivisionError - """ +The UUID comes from the acceptance criteria in `docs/features/backlog/.md`. Generate UUIDs using: +```bash +python -c "import uuid; print(uuid.uuid4())" ``` +Each acceptance criteria gets a unique UUID, and tests reference that UUID for traceability. + ### Why BDD Docstrings? 1. **pytest-html**: The HTML report displays docstrings as test names, making it easy to understand what each test verifies @@ -126,31 +112,29 @@ def test_division_by_zero_should_raise_error(): ```python # ✅ CORRECT def test_valid_case(): - """ - Example: Valid scenario + """123e4567-e89b-12d3-a456-426614174000: Valid scenario. + Given: Preconditions - When: Action occurs + When: Action Then: Expected outcome """ -# ❌ WRONG - Missing starting newline +# ❌ WRONG - Missing starting newline def test_invalid_case(): - """Example: Invalid scenario + """123e4567-e89b-12d3-a456-426614174000: Invalid scenario. Given: Preconditions""" # ❌ WRONG - Missing ending newline def test_invalid_case(): """ - Example: Invalid scenario + 123e4567-e89b-12d3-a456-426614174000: Invalid scenario. Given: Preconditions""" # ❌ WRONG - Both missing def test_invalid_case(): - """Example: Invalid scenario""" + """123e4567-e89b-12d3-a456-426614174000: Invalid scenario.""" ``` -### Examples - ### Why BDD Docstrings? 1. **pytest-html**: The HTML report displays docstrings as test names, making it easy to understand what each test verifies diff --git a/.opencode/skills/workflow-coordination/SKILL.md b/.opencode/skills/workflow-coordination/SKILL.md index 8e37726..eb0af3a 100644 --- a/.opencode/skills/workflow-coordination/SKILL.md +++ b/.opencode/skills/workflow-coordination/SKILL.md @@ -9,12 +9,12 @@ metadata: --- ## What I do -Manage the complete 7-step development cycle with proper phase progression, mandatory QA gates, and epic/TODO alignment with requirements. +Manage the complete 7-step development cycle with proper phase progression, mandatory QA gates, and feature/TODO alignment with requirements. ## When to use me - When coordinating feature development - During phase transitions in the development cycle -- When managing epic progression +- When managing feature progression - When validating workflow compliance ## 7-Phase Development Cycle @@ -29,7 +29,7 @@ Phase 1: Requirements Review ├── [ ] Review REQUIREMENTS.md for feature details ├── [ ] Verify business value alignment ├── [ ] Validate acceptance criteria completeness -├── [ ] Confirm epic alignment +├── [ ] Confirm feature alignment ├── [ ] Ensure Example format in acceptance criteria └── QA: @overseer reviews requirements ``` @@ -54,7 +54,7 @@ Phase 2: Feature Definition ├── [ ] Define scope boundaries ├── [ ] Identify integration points ├── [ ] Estimate effort -├── [ ] Update EPICS.md with feature details +├── [ ] Update docs/roadmap.md with feature details └── QA: @overseer reviews definition ``` @@ -74,9 +74,9 @@ Phase 2: Feature Definition Phase 3: Test Development (TDD) ├── [ ] /skill prototype-script (if validation needed) ├── [ ] /skill tdd -├── [ ] Write BDD tests with Example format: -│ """ -│ Example: [What test demonstrates] +├── [ ] Write BDD tests with UUID format: +│ """[UUID]: [Test description]. +│ │ Given: [Preconditions] │ When: [Action/trigger] │ Then: [Expected outcome] @@ -176,7 +176,7 @@ Phase 6: Final Quality Assurance ``` Phase 7: Feature Completion -├── [ ] Update EPICS.md - mark feature complete +├── [ ] Move feature to docs/features/completed/ ├── [ ] /skill epic-workflow next-feature ├── [ ] Move to next feature OR close epic ├── [ ] Update TODO.md @@ -201,7 +201,7 @@ Every phase includes mandatory @overseer review: ## QA Checkpoint Request: Phase [X] - [Feature Name] **Phase**: [X] - [Phase Name] -**Feature**: [Feature from EPICS.md] +**Feature**: [Feature from docs/roadmap.md] **QA Focus**: [What overseer should review] **Completed Tasks**: @@ -221,7 +221,7 @@ Every phase includes mandatory @overseer review: Each feature in TODO.md follows this structure: ```markdown -## Current Epic: [Epic Name from EPICS.md] +## Current Feature: [Feature from docs/roadmap.md] ## Current Feature: [Feature Name] ### Phase 1: Requirements Review @@ -231,7 +231,7 @@ Each feature in TODO.md follows this structure: ### Phase 2: Feature Definition - [ ] @developer /skill feature-definition -- [ ] Updates EPICS.md technical details +- [ ] Updates docs/roadmap.md technical details - [ ] QA: @overseer reviews definition quality [... all 7 phases ...] @@ -244,10 +244,10 @@ Each feature in TODO.md follows this structure: | 3 | @developer | In Progress | @overseer Pending | ``` -### EPICS Integration -- Epic progress updates EPICS.md status -- Feature completion marks in EPICS.md -- QA history logged in EPICS.md +### Roadmap Integration +- Feature progress updates docs/roadmap.md status +- Feature completion moves to docs/features/completed/ +- QA history tracked in TODO.md session log - Requirements traceability maintained ## Session Workflow Integration @@ -255,7 +255,7 @@ Each feature in TODO.md follows this structure: ### Start of Session ```markdown # 1. Read TODO.md - Understand current state -# 2. Read EPICS.md - Review epic progress +# 2. Read docs/roadmap.md - Review feature breakdown # 3. Identify current phase # 4. Continue from checkpoint ``` @@ -316,7 +316,7 @@ Each feature in TODO.md follows this structure: ### Pre-Development Validation - [ ] REQUIREMENTS.md exists in docs/requirements/ -- [ ] EPICS.md updated with technical design +- [ ] docs/roadmap.md updated with technical design - [ ] TODO.md created with 7-phase structure - [ ] QA checkpoints embedded @@ -329,7 +329,7 @@ Each feature in TODO.md follows this structure: ### Post-Development Validation - [ ] All phases complete - [ ] All QA approvals received -- [ ] EPICS.md marked complete +- [ ] docs/roadmap.md updated - [ ] TODO.md updated for session handoff Remember: The 7-phase development cycle ensures quality at every step. Never bypass QA checkpoints - they exist to maintain standards and catch issues early. \ No newline at end of file diff --git a/.opencode/templates/EPICS.md.template b/.opencode/templates/EPICS.md.template deleted file mode 100644 index 32552a8..0000000 --- a/.opencode/templates/EPICS.md.template +++ /dev/null @@ -1,62 +0,0 @@ -# Python Project Template - Epic Tracking - -This file tracks all epics and their features. Each feature goes through mandatory QA gates before proceeding to the next. - -**Status Legend**: ⏸️ Pending | 🔄 In Progress | ✅ Complete | ❌ Blocked - ---- - -## Epic: Project Foundation -**Status**: 🔄 In Progress -**Business Value**: Establish the core infrastructure and development workflows for the project - -### Features: -1. **Project Setup** - Status: ⏸️ Pending - - Acceptance Criteria: - - Development environment configured - - All dependencies installed and verified - - Base tests passing - - QA Status: Not Started - -2. **Development Workflow** - Status: ⏸️ Pending - - Acceptance Criteria: - - All agents and skills operational - - Epic/feature workflow established - - QA gates functioning - - QA Status: Not Started - ---- - -## Epic: [Your First Epic Name] -**Status**: ⏸️ Pending -**Business Value**: [Why this epic provides value to users/business] - -### Features: -1. **[Feature 1 Name]** - Status: ⏸️ Pending - - Acceptance Criteria: - - [Specific measurable criterion] - - [Another criterion] - - QA Status: Not Started - -2. **[Feature 2 Name]** - Status: ⏸️ Pending - - Acceptance Criteria: - - [Specific measurable criterion] - - [Another criterion] - - QA Status: Not Started - ---- - -## QA History - -| Date | Feature | Epic | QA Result | Reviewer | -|------|---------|------|-----------|----------| -| YYYY-MM-DD | Feature Name | Epic Name | Approved/Rejected | @overseer | - ---- - -## Notes - -- Each feature must pass all QA gates before marked complete -- Features automatically flow to the next upon completion -- Epics complete when all contained features are done -- Use `@developer /skill epic-workflow` to manage epic progression \ No newline at end of file diff --git a/.opencode/templates/TODO.md.template b/.opencode/templates/TODO.md.template index ba62283..7f63b19 100644 --- a/.opencode/templates/TODO.md.template +++ b/.opencode/templates/TODO.md.template @@ -1,7 +1,7 @@ # Python Project Template - Development TODO -This file tracks current feature development within epics. For epic/feature tracking, see EPICS.md. -Each session should read both TODO.md and EPICS.md to understand current state. +This file tracks current feature development. For full feature list, see docs/roadmap.md and docs/features/backlog/. +Each session should read TODO.md and docs/roadmap.md to understand current state. **Convention:** `[ ]` = pending, `[x]` = done, `[~]` = in progress, `[-]` = skipped @@ -9,15 +9,14 @@ Each session should read both TODO.md and EPICS.md to understand current state. --- -## Current Epic: Project Foundation ## Current Feature: Project Setup ### Phase 0: Initial Setup -- [x] Project created via cookiecutter template +- [x] Project created via template - [ ] Review and update `README.md` with project-specific description - [ ] Install dependencies: `uv venv && uv pip install -e '.[dev]'` - [ ] Verify base tests pass: `task test` -- [ ] Initialize EPICS.md with first business epic +- [ ] Create first feature in docs/features/backlog/ ### QA Checkpoint - [ ] @overseer: Review project setup completeness @@ -31,14 +30,14 @@ When starting a new feature, copy these phases: ### Phase 1: Requirements Gathering - [ ] @requirements-gatherer: Conduct stakeholder interview -- [ ] Create feature analysis document +- [ ] Create feature in docs/features/backlog/.md - [ ] Define acceptance criteria - [ ] QA: @overseer reviews requirements ### Phase 2: Feature Definition - [ ] @developer /skill feature-definition - [ ] Document technical requirements -- [ ] Update EPICS.md with feature details +- [ ] Update docs/roadmap.md with feature details ### Phase 3: Test Development - [ ] @developer /skill prototype-script (if needed) @@ -62,9 +61,9 @@ When starting a new feature, copy these phases: - [ ] QA: @overseer final approval ### Phase 7: Feature Completion -- [ ] Update EPICS.md - mark feature complete +- [ ] Move feature to docs/features/completed/ with metadata - [ ] @developer /skill epic-workflow next-feature -- [ ] Proceed to next feature or close epic +- [ ] Proceed to next feature --- @@ -72,7 +71,7 @@ When starting a new feature, copy these phases: | Date | Session Summary | |------------|----------------------------------------------------| -| (date) | Project scaffolded via cookiecutter, TODO created | +| (date) | Project scaffolded via template, TODO created | --- diff --git a/AGENTS.md b/AGENTS.md index a736da3..5c86c21 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,10 +8,13 @@ This project uses a **session workflow** that allows complex development to span ### How it works -1. **`TODO.md`** at the project root is the shared state between sessions -2. Every session starts by reading `TODO.md` to find the current phase -3. Every session ends by updating `TODO.md` with progress and handoff notes -4. This makes the project AI-agnostic: any agent, any time can continue +1. **`TODO.md`** at the project root is the current session work +2. **`docs/roadmap.md`** is the architect's technical breakdown of all features +3. **`docs/features/backlog/`** contains feature definitions (business language) +4. **`docs/features/completed/`** contains delivered features with test links +5. Every session starts by reading `TODO.md` and `docs/roadmap.md` +6. Every session ends by updating `TODO.md` with progress and handoff notes +7. This makes the project AI-agnostic: any agent, any time can continue ### Starting a new session ```bash @@ -25,7 +28,7 @@ This project includes custom skills for OpenCode: ### Session Management - **session-workflow**: Manage multi-session development - read TODO.md, continue from last checkpoint, update progress and hand off cleanly -- **epic-workflow**: Manage epic-based development with automatic feature progression and mandatory QA gates +- **epic-workflow**: Manage feature-based development with automatic progression and mandatory QA gates ### Workflow Coordination - **workflow-coordination**: Orchestrate 7-phase development cycle with agent delegation and checkpoint enforcement diff --git a/README.md b/README.md index 7761cdd..c7fba46 100644 --- a/README.md +++ b/README.md @@ -26,31 +26,41 @@ cd python-project-template # 2. Install UV package manager (if not installed) curl -LsSf https://astral.sh/uv/install.sh | sh -# 3. Customize the template for your project +# 3. **IMPORTANT**: Customize the template for your project python setup_project.py +# This interactive script will: +# - Rename directories from 'app' to your package name +# - Update pyproject.toml with your project details +# - Fix Docker configuration paths +# - Replace all template placeholders -# 4. Follow the Git configuration commands shown -# (setup_project.py will display the exact commands) +# 4. Follow the Git configuration commands shown by setup_project.py +# Example: git remote set-url origin https://github.com/yourname/yourproject -# 5. Initialize AI development environment (optional) -opencode && /init - -# 6. Setup development environment +# 5. Setup development environment uv venv && uv pip install -e '.[dev]' -# 7. Validate everything works +# 6. Validate everything works task test && task lint && task static-check + +# 7. Initialize AI development environment (optional) +opencode && /init ``` +**⚠️ Template State Notice**: This project is currently in "template state" with placeholder values. The `setup_project.py` script **must** be run to properly configure Docker, package paths, and project metadata before development. + +**Requirements**: Python 3.13+ and UV package manager are required. + ## 🎯 What This Template Provides This template creates a production-ready Python project with: ### 🔧 **Project Setup & Customization** - **Automated setup script** (`setup_project.py`) - Interactive customization with your project details -- **Smart folder renaming** - Automatically renames directories to match your project +- **Smart folder renaming** - Automatically renames `app/` directory to match your project +- **Docker path fixing** - Updates Docker configuration to match your project structure - **Git configuration** - Provides ready-to-use Git commands for remotes and user setup -- **Template processing** - Replaces all placeholders with your actual project information +- **Template processing** - Replaces all placeholders in pyproject.toml and configuration files ### 🤖 **AI-Enhanced Development Workflow** - **Multi-session continuity** - Projects span multiple AI sessions with shared state in `TODO.md` @@ -58,10 +68,11 @@ This template creates a production-ready Python project with: - **Skills system** - Modular workflows for TDD, feature definition, prototyping, and releases ### 🏗️ **Enterprise Architecture & Quality** -- **SOLID principles** - Enforced through AI architecture reviews -- **Object Calisthenics** - Clean, behavior-rich code patterns -- **100% test coverage** - TDD workflows with property-based testing (Hypothesis) -- **Zero-config tooling** - UV, Ruff, PyTest, PyRight pre-configured +- **SOLID principles** - Enforced through AI architecture reviews via OpenCode agents +- **Object Calisthenics** - Clean, behavior-rich code patterns enforced by QA workflows +- **100% test coverage** - TDD workflows with BDD docstrings and property-based testing (Hypothesis) +- **Mutation testing** - mutmut integration for test quality validation +- **Zero-config tooling** - UV, taskipy, Ruff, PyTest, Hypothesis, PyRight pre-configured ## 🤖 AI-Powered Development @@ -104,46 +115,63 @@ Complex projects are developed across multiple AI sessions. `TODO.md` at the roo ## 🏗️ Architecture & Standards - **🎯 SOLID Principles** - Single responsibility, dependency inversion, clean interfaces -- **🔧 Object Calisthenics** - No primitives, small classes, behavior-rich objects -- **🧪 TDD Testing** - 100% coverage requirement with property-based tests -- **⚡ Modern Toolchain** - UV, Ruff, PyTest, Hypothesis, PyRight -- **🚀 Smart Releases** - Calver versioning with AI-generated themed names +- **🔧 Object Calisthenics** - No primitives, small classes, behavior-rich objects +- **🧪 TDD Testing** - BDD-style tests with Given/When/Then docstrings, 100% coverage requirement +- **🔬 Property-Based Testing** - Hypothesis integration for robust edge case validation +- **🧬 Mutation Testing** - mutmut for genetic algorithm-based test quality assurance +- **⚡ Modern Toolchain** - UV, taskipy, Ruff, PyTest, Hypothesis, PyRight +- **🚀 Smart Releases** - Hybrid major.minor.calver versioning with AI-generated themed names ## 📋 Development Commands +This project uses **taskipy** for task automation (configured in `pyproject.toml`): + ```bash # Core development workflow -task run # Execute main application -task test # Run comprehensive test suite -task lint # Format and lint code -task static-check # Type safety validation -task doc-serve # Live pdoc documentation server -task doc-build # Build static pdoc API docs +task run # Execute version module (demo command) +task test # Run comprehensive test suite with coverage +task test-fast # Run fast tests only (skip slow tests) +task test-slow # Run only slow tests (marked with @pytest.mark.slow) +task lint # Format and lint code with ruff +task static-check # Type safety validation with pyright + +# Documentation +task doc-serve # Live pdoc documentation server (localhost:8080) +task doc-build # Build static pdoc API docs to docs/api/ task doc-publish # Publish API docs to GitHub Pages # Quality assurance -task test-report # Detailed coverage report -task mut-report # Mutation testing (optional) +task test-report # Detailed coverage report (included in task test) +task mut # Mutation testing with mutmut +task mut-clean # Reset mutation testing cache ``` ## 🐳 Docker Usage -Simple Docker setup for development with hot reload and integrated tooling. +**⚠️ Important**: Run `python setup_project.py` first to configure the template before using Docker. + +Docker provides development environment with hot reload and integrated tooling: ```bash -# Development workflows -docker-compose up # Hot reload development environment +# Development environment with hot reload +docker-compose up # Main application (ports 8000, 8080, 5678) + +# Specialized services (use profiles) docker-compose --profile test up # Run complete test suite -docker-compose --profile docs up # Documentation server (localhost:8080) +docker-compose --profile docs up # Documentation server (localhost:8080) docker-compose --profile quality up # Code quality checks (lint + typecheck) -# Build standalone image (after running setup_project.py) -docker build -t your-project-name . # Build development image +# Build standalone image +docker build -t your-project-name . # Build development image ``` -**Note**: Run `python setup_project.py` first to replace template variables before using Docker. +**Current Docker Configuration:** +- **Main service**: Hot reload development with volume mounts +- **Test profile**: Full test suite execution +- **Docs profile**: Live documentation server +- **Quality profile**: Linting and type checking -- **🛠️ Development**: Hot reload, separate services for testing/docs/quality checks +**Note**: The Docker configuration currently references template paths and requires `setup_project.py` to be run for proper functionality. @@ -152,37 +180,43 @@ docker build -t your-project-name . # Build development image | Category | Tools | |----------|-------| | **Package Management** | UV (blazing fast pip/poetry replacement) | +| **Task Automation** | taskipy (configured in pyproject.toml) | | **Code Quality** | Ruff (linting + formatting), PyRight (type checking) | | **Testing** | PyTest + Hypothesis (property-based testing), pytest-html (BDD reports) | -| **AI Integration** | OpenCode agents for development automation | -| **Documentation** | pdoc with search functionality | -| **Containerization** | Docker development environment with hot reload | +| **Mutation Testing** | mutmut (genetic algorithm-based mutation testing) | +| **Coverage** | pytest-cov (100% coverage requirement) | +| **AI Integration** | OpenCode agents and skills for development automation | +| **Documentation** | pdoc with search functionality and GitHub Pages publishing | +| **Containerization** | Docker development environment with hot reload and service profiles | ## 📈 Quality Metrics -- ✅ **100% Test Coverage** - Comprehensive test suite including edge cases -- ✅ **Static Type Safety** - Full type hints with protocol-based interfaces -- ✅ **Zero Linting Issues** - Automated formatting and style enforcement -- ✅ **Property-Based Testing** - Hypothesis for robust validation -- ✅ **Architecture Compliance** - AI-enforced SOLID principles +- ✅ **100% Test Coverage** - pytest-cov with fail-under=100 requirement +- ✅ **Static Type Safety** - PyRight type checking with full type hints +- ✅ **Zero Linting Issues** - Ruff automated formatting and Google-style conventions +- ✅ **Property-Based Testing** - Hypothesis integration for robust validation +- ✅ **Mutation Testing** - mutmut for genetic algorithm-based test quality validation +- ✅ **BDD Test Style** - Given/When/Then docstrings with pytest-html reporting +- ✅ **Architecture Compliance** - AI-enforced SOLID principles through OpenCode agents ## 🚀 Deployment Ready -Projects generated from this template include Docker support: +Projects generated from this template include Docker support for development: ```bash -# In your generated project +# After running setup_project.py in your configured project docker build -t your-project-name . -docker run your-project-name +docker run -p 8000:8000 your-project-name -# Docker Compose development -docker-compose up # Development environment -docker-compose --profile test up # Run tests +# Docker Compose development environment +docker-compose up # Development environment with hot reload +docker-compose --profile test up # Run test suite docker-compose --profile docs up # Documentation server +docker-compose --profile quality up # Code quality checks -# API documentation (generated projects) +# API documentation task doc-build # Generates docs/api/index.html -task doc-serve # http://localhost:8080 +task doc-serve # http://localhost:8080 (live server) ``` ## 🤝 Contributing diff --git a/TODO.md b/TODO.md index ba62283..a9b889d 100644 --- a/TODO.md +++ b/TODO.md @@ -1,7 +1,7 @@ # Python Project Template - Development TODO -This file tracks current feature development within epics. For epic/feature tracking, see EPICS.md. -Each session should read both TODO.md and EPICS.md to understand current state. +This file tracks current feature development. For full feature list, see docs/roadmap.md and docs/features/backlog/. +Each session should read TODO.md and docs/roadmap.md to understand current state. **Convention:** `[ ]` = pending, `[x]` = done, `[~]` = in progress, `[-]` = skipped @@ -9,15 +9,14 @@ Each session should read both TODO.md and EPICS.md to understand current state. --- -## Current Epic: Project Foundation ## Current Feature: Project Setup ### Phase 0: Initial Setup -- [x] Project created via cookiecutter template +- [x] Project created via template - [ ] Review and update `README.md` with project-specific description - [ ] Install dependencies: `uv venv && uv pip install -e '.[dev]'` - [ ] Verify base tests pass: `task test` -- [ ] Initialize EPICS.md with first business epic +- [ ] Create first feature in docs/features/backlog/ ### QA Checkpoint - [ ] @overseer: Review project setup completeness @@ -38,7 +37,7 @@ When starting a new feature, copy these phases: ### Phase 2: Feature Definition - [ ] @developer /skill feature-definition - [ ] Document technical requirements -- [ ] Update EPICS.md with feature details +- [ ] Update docs/roadmap.md with feature details ### Phase 3: Test Development - [ ] @developer /skill prototype-script (if needed) @@ -62,7 +61,7 @@ When starting a new feature, copy these phases: - [ ] QA: @overseer final approval ### Phase 7: Feature Completion -- [ ] Update EPICS.md - mark feature complete +- [ ] Move feature to docs/features/completed/ when done - [ ] @developer /skill epic-workflow next-feature - [ ] Proceed to next feature or close epic @@ -72,7 +71,7 @@ When starting a new feature, copy these phases: | Date | Session Summary | |------------|----------------------------------------------------| -| (date) | Project scaffolded via cookiecutter, TODO created | +| (date) | Project scaffolded via template, TODO created | --- From 4b8185de12e9d8a481ea8ca789e0f56babd40c3b Mon Sep 17 00:00:00 2001 From: nullhack Date: Mon, 13 Apr 2026 15:24:32 -0400 Subject: [PATCH 2/4] Implement architecture-first feature system with 8-phase development Major changes: - Migrate features/ to business/ and create architecture/ directories - Add architectural-analysis skill for @architect to create technical features - Update manager agent with test signature creation and folder organization - Convert epic-workflow to feature-selection with architecture-first priority - Update all references from 7-phase to 8-phase development cycle - Add hypothesis usage guidelines (@given, @example, assume) - Update workflow-coordination with new Architecture Analysis phase - Update TODO.md and AGENTS.md with new workflow description New workflow: 1. Requirements Review 2. Feature Definition 3. Architecture Analysis (NEW) 4. Test Development (TDD) 5. Design & Signatures 6. Implementation 7. Final Quality Assurance 8. Feature Completion Key features: - Architecture features prioritized for unit/smoke tests - Manager creates test signatures with UUIDs and raise NotImplementedError - Test folder structure mirrors source structure - Both feature types use UUID acceptance criteria - Independent lifecycle for architecture and business features --- .opencode/agents/developer.md | 4 +- .opencode/agents/manager.md | 136 ++++++--- .opencode/agents/requirements-gatherer.md | 6 +- .../skills/architectural-analysis/SKILL.md | 218 ++++++++++++++ .../skills/delegation-coordination/SKILL.md | 2 +- .opencode/skills/epic-workflow/SKILL.md | 270 ++++++++++-------- .opencode/skills/tdd/SKILL.md | 2 +- .../skills/workflow-coordination/SKILL.md | 95 +++--- AGENTS.md | 18 +- CHANGELOG.md | 2 +- TODO.md | 55 ++-- 11 files changed, 572 insertions(+), 236 deletions(-) create mode 100644 .opencode/skills/architectural-analysis/SKILL.md diff --git a/.opencode/agents/developer.md b/.opencode/agents/developer.md index e15cf91..22988b9 100644 --- a/.opencode/agents/developer.md +++ b/.opencode/agents/developer.md @@ -150,9 +150,9 @@ Projects are organized into Epics containing Features. Each feature follows a st 6. **Call `@overseer` for final review before considering the feature complete** ### Phase 8: Feature Completion -1. Move feature to `docs/features/completed/` with metadata +1. Move feature to `docs/features/[architecture|business]/completed/` with metadata 2. System automatically checks for next pending feature -3. If more features exist, return to Phase 0/1 for next feature +3. If more features exist, return to Phase 1 for next feature 4. If all complete, proceed to PR creation ## Available Skills diff --git a/.opencode/agents/manager.md b/.opencode/agents/manager.md index 11c6bb4..a7306c5 100644 --- a/.opencode/agents/manager.md +++ b/.opencode/agents/manager.md @@ -21,22 +21,22 @@ You are the **Manager** agent - a Workflow Coordinator and Project Manager for t ## Your Role -You coordinate the complete development workflow, ensuring proper phase progression and quality checkpoints. You create detailed TODOs, manage agent handoffs, and enforce the 7-step development cycle without executing development tasks yourself. +You coordinate the complete development workflow, ensuring proper phase progression and quality checkpoints. You create detailed TODOs, select features using architecture-first priority, create test signatures, and enforce the 8-step development cycle without executing development tasks yourself. ## Position in the development Workflow You are **3rd in the initialization sequence**: 1. **@requirements-gatherer** → Creates docs/requirements/REQUIREMENTS.md 2. **@architect** → Reviews requirements, creates/updates docs/roadmap.md -3. **@manager** (YOU) → Creates detailed 7-phase TODOs with QA checkpoints +3. **@manager** (YOU) → Selects features, creates 8-phase TODOs, creates test signatures 4. **Development begins** → Auto-delegate to @developer to start Phase 1 ## Core Responsibilities ### 1. Workflow Coordination -- Create comprehensive 7-phase TODO structures -- Embed mandatory @overseer checkpoints at each phase transition -- Ensure feature alignment with requirements documentation +- Select features using architecture-first priority from `docs/features/architecture/backlog/` then `docs/features/business/backlog/` +- Create comprehensive 8-phase TODO structures with embedded QA checkpoints +- Create test function signatures with UUIDs from feature acceptance criteria - Coordinate agent handoffs per explicit delegation rules ### 2. Quality Gate Management @@ -70,15 +70,70 @@ You coordinate but do not execute development. Delegate appropriately: - Architecture approval (from architect) - Quality standards (no shortcuts allowed) -## 7-Phase Development Cycle +## Feature Selection Strategy + +### Architecture-First Priority +1. **First**: Check `docs/features/architecture/backlog/` for technical features +2. **Second**: Check `docs/features/business/backlog/` for business features +3. **Rationale**: Architecture features drive unit/smoke tests, business features drive integration/system tests + +### Feature Types +Both feature types contain acceptance criteria with UUIDs, but differ in audience: +- **Architecture Features**: Technical language for developers (components, APIs, performance) +- **Business Features**: Stakeholder language for users (workflows, business value, user stories) + +## Test Signature Creation + +As part of TODO creation, manually create test function signatures from feature acceptance criteria: + +### Test Folder Structure Organization +Organize test files mirroring the source structure under `tests/`: +``` +tests/ +├── unit/ +│ ├── __init__.py +│ └── / +│ ├── __init__.py +│ └── _test.py +├── integration/ +│ ├── __init__.py +│ └── / +│ └── _test.py +├── system/ +│ ├── __init__.py +│ └── / +│ └── _test.py +└── conftest.py +``` + +### Test Signature Process +1. Read selected feature's acceptance criteria (both types have UUIDs) +2. Determine appropriate test location based on test type +3. Create test file structure as needed +4. For each UUID acceptance criteria, create test function: +```python +@pytest.mark.smoke # or appropriate mark based on test content +def test__should_() -> None: + """: + + Given: + When: + Then: + """ + raise NotImplementedError +``` +5. Use appropriate pytest marks based on test content (flexible, not feature type) +6. Use hypothesis `@given()` for pure functions when appropriate + +## 8-Phase Development Cycle When creating TODOs, ensure each feature follows this exact structure: ### Phase 1: Requirements Review ```markdown #### Phase 1: Requirements Review -- [ ] Review REQUIREMENTS.md for feature details -- [ ] Validate business value and acceptance criteria +- [ ] Review feature details from docs/features/[architecture|business]/backlog/ +- [ ] Validate acceptance criteria completeness and UUID traceability - [ ] Confirm feature alignment with requirements - [ ] QA: @overseer reviews requirements completeness ``` @@ -86,31 +141,35 @@ When creating TODOs, ensure each feature follows this exact structure: ### Phase 2: Feature Definition ```markdown #### Phase 2: Feature Definition -- [ ] @developer /skill feature-definition -- [ ] Document technical requirements and constraints -- [ ] Update docs/roadmap.md with feature implementation details +- [ ] Read and understand feature acceptance criteria +- [ ] Identify technical scope and integration points +- [ ] Confirm feature is ready for test signature creation - [ ] QA: @overseer reviews feature definition quality ``` -### Phase 3: Test Development (TDD) +### Phase 3: Architecture Analysis +```markdown +#### Phase 3: Architecture Analysis +- [ ] @architect /skill architectural-analysis (if architecture feature) +- [ ] Analyze component responsibilities and interfaces +- [ ] Document architectural decisions (ADRs) if significant +- [ ] Define technical acceptance criteria for test signatures +- [ ] QA: @overseer reviews architectural soundness +``` + +### Phase 4: Test Development (TDD) ```markdown -#### Phase 3: Test Development (TDD) -- [ ] Select ONE feature from docs/roadmap.md -- [ ] Create/clear TODO.md for selected feature -- [ ] Map acceptance criteria UUIDs to test signatures -- [ ] Write tests/_test.py with UUIDs in docstrings: - """ - 123e4567-e89b-12d3-a456-426614174000: [Criteria description] - Given: [Preconditions] - When: [Action/trigger] - Then: [Expected outcome] - """ -- [ ] QA: @overseer reviews test quality and BDD compliance +#### Phase 4: Test Development (TDD) +- [ ] @developer creates test function signatures from feature UUIDs +- [ ] Maps acceptance criteria to test functions with BDD docstrings +- [ ] Writes tests//_test.py with raise NotImplementedError +- [ ] Use @pytest.mark based on test content, hypothesis for pure functions +- [ ] QA: @overseer reviews test signatures and BDD compliance ``` -### Phase 4: Design & Architecture +### Phase 5: Design & Signatures ```markdown -#### Phase 4: Design & Architecture +#### Phase 5: Design & Signatures - [ ] @developer /skill signature-design - [ ] Design interfaces with proper type hints and protocols - [ ] @architect reviews and approves design @@ -118,28 +177,29 @@ When creating TODOs, ensure each feature follows this exact structure: - [ ] QA: @overseer validates SOLID principle compliance ``` -### Phase 5: Implementation +### Phase 6: Implementation ```markdown -#### Phase 5: Implementation +#### Phase 6: Implementation - [ ] @developer /skill implementation - [ ] Implement using TDD methodology (Red-Green-Refactor) +- [ ] Replace NotImplementedError with actual test logic - [ ] Ensure all tests pass with proper coverage - [ ] QA: @overseer reviews SOLID/DRY/KISS/YAGNI compliance ``` -### Phase 6: Final Quality Assurance +### Phase 7: Final Quality Assurance ```markdown -#### Phase 6: Final Quality Assurance +#### Phase 7: Final Quality Assurance - [ ] @developer /skill code-quality - [ ] Run all quality checks: `task lint`, `task static-check`, `task test` - [ ] Verify 100% test coverage maintained - [ ] QA: @overseer final approval before feature completion ``` -### Phase 7: Feature Completion +### Phase 8: Feature Completion ```markdown -#### Phase 7: Feature Completion -- [ ] Move feature to docs/features/completed/ with metadata +#### Phase 8: Feature Completion +- [ ] Move feature to docs/features/[architecture|business]/completed/ - [ ] @developer /skill epic-workflow next-feature - [ ] Proceed to next feature - [ ] Session handoff: Update TODO.md for next session @@ -209,16 +269,16 @@ def test_user_login_with_valid_credentials_should_grant_access(): ## Current Feature: [Feature Name] ### Feature Overview -- **Business Value**: [From docs/features/backlog/.md] +- **Business Value**: [From docs/features/business/backlog/.md] - **Acceptance Criteria**: [Example format criteria] -- **Feature Reference**: See docs/features/backlog/.md +- **Feature Reference**: See docs/features/business/backlog/.md or docs/features/architecture/backlog/.md -[Include all 7 phases with embedded QA checkpoints] +[Include all 8 phases with embedded QA checkpoints] ### QA History for Feature - [ ] Phase 1 QA: ⏸️ Pending @overseer review -- [ ] Phase 3 QA: ⏸️ Pending @overseer test review -- [ ] Phase 4 QA: ⏸️ Pending @overseer design review +- [ ] Phase 3 QA: ⏸️ Pending @overseer architectural review +- [ ] Phase 4 QA: ⏸️ Pending @overseer test review - [ ] Phase 5 QA: ⏸️ Pending @overseer implementation review - [ ] Phase 6 QA: ⏸️ Pending @overseer final approval ``` diff --git a/.opencode/agents/requirements-gatherer.md b/.opencode/agents/requirements-gatherer.md index 5f8c635..55f815b 100644 --- a/.opencode/agents/requirements-gatherer.md +++ b/.opencode/agents/requirements-gatherer.md @@ -75,7 +75,7 @@ Generate a UUID for each acceptance criteria using: python -c "import uuid; print(uuid.uuid4())" ``` -Create a feature document in `docs/features/backlog/.md`: +Create a feature document in `docs/features/business/backlog/.md`: ```markdown # Feature: [Feature Name] @@ -112,7 +112,7 @@ Generate one using: `python -c "import uuid; print(uuid.uuid4())"` After requirements approval: -1. Write feature to `docs/features/backlog/.md` +1. Write feature to `docs/features/business/backlog/.md` 2. Update `TODO.md` with current session tasks 3. Create test scenarios for the QA team 4. Prepare handoff documentation for developers @@ -135,7 +135,7 @@ Your workflow integrates as follows: @requirements-gatherer # You gather requirements # 2. You produce: -- Feature document in `docs/features/backlog/.md` +- Feature document in `docs/features/business/backlog/.md` - Updated `TODO.md` with current tasks - Test scenarios for QA diff --git a/.opencode/skills/architectural-analysis/SKILL.md b/.opencode/skills/architectural-analysis/SKILL.md new file mode 100644 index 0000000..ac5b59f --- /dev/null +++ b/.opencode/skills/architectural-analysis/SKILL.md @@ -0,0 +1,218 @@ +--- +name: architectural-analysis +description: Create technical architecture features that complement business features with system design and architectural decisions +license: MIT +compatibility: opencode +metadata: + audience: architects + workflow: architecture-analysis +--- + +## What I do + +Create architecture features in `docs/features/architecture/backlog/` that complement business features with technical requirements, system design decisions, and architectural acceptance criteria using UUID traceability. + +## When to use me + +- After business features are defined in `docs/features/business/backlog/` +- When technical requirements need to be derived from business needs +- To create architectural decisions that guide implementation +- To define technical acceptance criteria that drive unit and smoke tests + +## Architecture Feature Creation Process + +### 1. Business Feature Analysis +Read business features from `docs/features/business/backlog/` to understand: +- User requirements and business value +- Functional requirements +- Non-functional requirements (performance, security, scalability) +- Integration points and dependencies + +### 2. Technical Requirements Derivation +Transform business needs into technical requirements: +- **Component Responsibilities**: What technical components are needed? +- **Data Flow**: How does information move through the system? +- **Integration Patterns**: How do components communicate? +- **Cross-cutting Concerns**: Security, logging, validation, error handling + +### 3. Architecture Feature Structure + +Create architecture features using this template: + +```markdown +# [Architecture Feature Name] + +## Overview +**Purpose**: Technical capability that supports business feature(s) +**Business Context**: Which business features this architecture supports +**Technical Scope**: What technical concerns this addresses + +## Component Design +### [ComponentName] +**Responsibility**: Single, clear purpose +**Interface**: Input/output contracts +**Dependencies**: What this component needs + +### [AnotherComponent] +**Responsibility**: Different single purpose +**Interface**: Clean contracts +**Dependencies**: Minimal coupling + +## Architecture Decisions (ADRs) + +### Decision: [Technology/Pattern Choice] +**Context**: Why this decision was needed +**Options**: What alternatives were considered +**Choice**: What was selected and why +**Consequences**: Trade-offs and implications + +## Technical Acceptance Criteria + +### [UUID generated with python -c "import uuid; print(uuid.uuid4())"] +Given: [Technical preconditions - system state, configuration, data setup] +When: [Technical action - API call, system event, component interaction] +Then: [Technical outcome - response format, state change, behavior] + +### [Another UUID] +Given: [Different technical scenario] +When: [Different technical trigger] +Then: [Expected technical result] +``` + +### 4. UUID Generation for Acceptance Criteria + +Generate UUIDs for each technical acceptance criteria: +```bash +python -c "import uuid; print(uuid.uuid4())" +``` + +Each acceptance criteria gets a unique UUID for test traceability. + +### 5. Technical Focus Areas + +Architecture features should address: + +**System Design**: +- Component boundaries and responsibilities +- Interface definitions and contracts +- Data transformation strategies +- Error handling patterns + +**Quality Attributes**: +- Performance targets and strategies +- Security architecture decisions +- Scalability patterns +- Reliability mechanisms + +**Integration Architecture**: +- API design and contracts +- Message formats and protocols +- Database schema and access patterns +- External service integration + +**Implementation Guidance**: +- Design patterns to use +- Code organization principles +- Testing strategies +- Development constraints + +### 6. Architecture Feature Naming + +Use descriptive technical names that complement business features: +- Business: "User Authentication" +- Architecture: "JWT Token Management System" + +- Business: "Product Catalog Search" +- Architecture: "Full-Text Search Index Architecture" + +### 7. Quality Gates + +Before completing architecture feature: +- [ ] All technical acceptance criteria have UUIDs +- [ ] Component responsibilities are single-purpose +- [ ] Architecture decisions are documented with rationale +- [ ] Technical requirements trace back to business needs +- [ ] Integration points are explicitly defined +- [ ] Cross-cutting concerns are addressed + +## Integration with Development Workflow + +### Phase 3: Architecture Analysis +1. **Read business features** from `docs/features/business/backlog/` +2. **Analyze technical needs** and architectural requirements +3. **Create architecture features** in `docs/features/architecture/backlog/` +4. **Document ADRs** for significant technical decisions +5. **Generate technical acceptance criteria** with UUIDs + +### Handoff to Phase 4 +Architecture features provide: +- **Technical acceptance criteria** for unit/smoke test creation +- **Component specifications** for interface design +- **Integration contracts** for system testing +- **Architectural constraints** for implementation guidance + +## Example Architecture Feature + +```markdown +# Database Connection Pool Management + +## Overview +**Purpose**: Reliable database connection management for high-concurrency applications +**Business Context**: Supports "User Authentication" and "Data Synchronization" business features +**Technical Scope**: Connection lifecycle, resource management, error recovery + +## Component Design +### ConnectionPool +**Responsibility**: Manage pool of reusable database connections +**Interface**: get_connection() -> Connection, release_connection(conn: Connection) +**Dependencies**: Database driver, configuration service + +### ConnectionValidator +**Responsibility**: Verify connection health before use +**Interface**: is_valid(conn: Connection) -> bool +**Dependencies**: Database connection interface + +## Architecture Decisions (ADRs) + +### Decision: Use HikariCP-style connection pooling +**Context**: Need reliable connection management under high load +**Options**: Simple connection per request, basic pooling, advanced pooling with validation +**Choice**: Advanced pooling with health checks and automatic recovery +**Consequences**: Higher complexity but better reliability and performance + +## Technical Acceptance Criteria + +### a1b2c3d4-e5f6-7890-abcd-ef1234567890 +Given: Database connection pool configured for 100 connections with health checks enabled +When: Application requests 150 concurrent connections under normal load +Then: Pool should serve connections without blocking and maintain response time < 10ms + +### b2c3d4e5-f6g7-8901-bcde-f23456789012 +Given: Database becomes temporarily unavailable +When: Connection pool detects failed connections during health check +Then: Failed connections should be marked invalid and new connections attempted automatically + +### c3d4e5f6-g7h8-9012-cdef-g34567890123 +Given: Connection pool at 90% capacity +When: New connection requests arrive +Then: Pool should create new connections up to maximum limit and queue excess requests +``` + +## Output Location + +Architecture features are created in: +``` +docs/features/architecture/backlog/[feature-name]/ +├── architecture-feature.md # Main architecture specification +└── technical-acceptance-criteria.md # Detailed UUID criteria (if needed separately) +``` + +## Success Criteria + +Architecture feature is complete when: +- [ ] Technical requirements derived from business features +- [ ] All components have single responsibilities +- [ ] Architecture decisions documented with ADRs +- [ ] Technical acceptance criteria have UUIDs +- [ ] Integration points explicitly defined +- [ ] Ready for manager to create test signatures \ No newline at end of file diff --git a/.opencode/skills/delegation-coordination/SKILL.md b/.opencode/skills/delegation-coordination/SKILL.md index 19d4d83..76785e2 100644 --- a/.opencode/skills/delegation-coordination/SKILL.md +++ b/.opencode/skills/delegation-coordination/SKILL.md @@ -102,7 +102,7 @@ Define explicit delegation rules and provide guidance for proper agent handoffs **Delegation pattern:** ```markdown -1. Create comprehensive 7-phase TODOs +1. Create comprehensive 8-phase TODOs 2. Embed mandatory @overseer checkpoints 3. Coordinate agent handoffs at phase transitions 4. → Call @developer to start Phase 1 diff --git a/.opencode/skills/epic-workflow/SKILL.md b/.opencode/skills/epic-workflow/SKILL.md index a64e76f..e44d6a8 100644 --- a/.opencode/skills/epic-workflow/SKILL.md +++ b/.opencode/skills/epic-workflow/SKILL.md @@ -1,175 +1,201 @@ --- name: epic-workflow -description: Manage epic-based development with features, QA checkpoints, and automatic progression to next features +description: Select and manage features from architecture and business backlogs with architecture-first prioritization license: MIT compatibility: opencode metadata: audience: developers - workflow: epic-management + workflow: feature-selection --- ## What I do -I enable epic-based development where each epic contains multiple features. After completing a feature and passing QA, I automatically progress to the next feature in the epic. This creates a continuous development flow with quality checkpoints. +I manage feature selection and progression using an architecture-first approach. I select features from either `docs/features/architecture/backlog/` or `docs/features/business/backlog/`, prioritizing architecture features for unit/smoke test development. ## Key Concepts -- **Epic**: A major capability containing multiple related features -- **Feature**: A single implementable unit with clear acceptance criteria -- **QA Checkpoint**: Mandatory review by the overseer agent after each phase -- **Feature Cycle**: Requirements → TDD → Implementation → QA → Next Feature +- **Architecture Features**: Technical requirements that drive unit and smoke tests +- **Business Features**: User-facing requirements that drive integration and system tests +- **Feature → TODO**: Direct selection of features for immediate development +- **Architecture-First**: Priority selection from architecture backlog for foundational testing +- **Independent Lifecycle**: Architecture and business features complete separately ## When to use me -- When starting a new epic with multiple features +- When selecting the next feature for development - When completing a feature and ready to move to the next -- When tracking progress across complex multi-feature development -- When ensuring QA gates are enforced at each checkpoint +- When managing feature progression through backlog → completed +- When ensuring architecture-driven development approach -## Feature Tracking +## Feature Selection Strategy -Features are tracked in `docs/roadmap.md` (architect breakdown) and `docs/features/backlog/` (business definitions): +### Priority Order +1. **First Priority**: `docs/features/architecture/backlog/` (technical features) +2. **Second Priority**: `docs/features/business/backlog/` (business features) -```markdown -# docs/roadmap.md +### Rationale +- **Architecture features** → unit tests, smoke tests (foundational) +- **Business features** → integration tests, system tests (require foundation) -## Feature: [Feature Name] -**Status**: In Progress | Complete -**Business Value**: [Why this feature matters] +## Feature Directory Structure -### Technical Breakdown -- [Deliverable 1] -- [Deliverable 2] +``` +docs/features/ +├── architecture/ +│ ├── backlog/ # Technical features awaiting development +│ │ └── / +│ │ └── architecture-feature.md +│ └── completed/ # Technical features delivered +│ └── / +└── business/ + ├── backlog/ # Business features awaiting development + │ └── / + │ └── business-feature.md + └── completed/ # Business features delivered + └── / +``` + +## Feature Selection Commands -# docs/features/backlog/.md +### `next-feature` - Select Next Feature for Development +Selects the next feature using architecture-first priority: -## Feature: [Feature Name] -**Business Description**: [What it does] -**Acceptance Criteria**: [What defines done] +```bash +@developer /skill epic-workflow next-feature ``` -## Feature Development Cycle +**Selection Logic:** +1. Check `docs/features/architecture/backlog/` for available features +2. If architecture features exist: Select first architecture feature +3. If no architecture features: Check `docs/features/business/backlog/` +4. If business features exist: Select first business feature +5. If no features exist: Prompt for feature creation -### 1. Feature Initiation -When starting a new feature: +**Output:** +- Updates TODO.md with selected feature +- Creates 8-phase development plan +- Provides feature summary and acceptance criteria + +### `complete-feature` - Move Feature to Completed +Moves current feature from backlog to completed: + +```bash +@developer /skill epic-workflow complete-feature ``` -1. Read docs/roadmap.md to find next pending feature -2. Call @requirements-gatherer if feature needs clarification -3. Update feature status to "In Progress 🔄" -4. Create feature-specific TODO in TODO.md + +**Completion Logic:** +- Moves feature from `backlog/` to `completed/` in appropriate directory +- Updates TODO.md status +- Clears current feature from active development +- Ready for next feature selection + +### `status` - Show Feature Pipeline Status +Displays current feature pipeline: + +```bash +@developer /skill epic-workflow status ``` -### 2. Feature Implementation Phases +**Output:** +- Current feature in development (from TODO.md) +- Available architecture features count +- Available business features count +- Recently completed features -Each feature follows these mandatory phases with QA checkpoints: +## Integration with 8-Phase Workflow +Feature selection integrates with the 8-phase development cycle: + +### Feature Selection → TODO Creation ``` -Phase 1: Requirements Analysis -- @requirements-gatherer collects detailed requirements -- Creates feature analysis document -- @architect reviews and approves design -- QA Checkpoint: @overseer reviews requirements completeness - -Phase 2: Test-Driven Development -- @developer /skill tdd -- Write comprehensive tests -- QA Checkpoint: @overseer reviews test quality - -Phase 3: Implementation -- @developer /skill implementation -- Implement to pass tests -- QA Checkpoint: @overseer reviews SOLID/DRY/KISS compliance - -Phase 4: Final Quality Assurance -- @developer /skill code-quality -- All quality checks must pass -- QA Checkpoint: @overseer final approval +1. Feature selected (architecture-first priority) +2. TODO.md updated with: + - Phase 1: Requirements Review + - Phase 2: Feature Definition + - Phase 3: Architecture Analysis + - Phase 4: Test Development (TDD) + - Phase 5: Design & Signatures + - Phase 6: Implementation + - Phase 7: Final Quality Assurance + - Phase 8: Feature Completion +3. @manager creates test signatures from feature acceptance criteria +4. @developer implements through phases ``` -### 3. Feature Completion +### Feature Completion → Next Selection ``` -1. Verify all TODO items complete -2. Overseer reviews and approves final QA -3. @overseer moves feature to docs/features/completed/ with metadata: - - Test coverage (which UUIDs have tests) - - QA approval date - - Links to test files -4. Clear TODO.md for next feature +1. All 8 phases completed with @overseer approvals +2. Feature moved from backlog/ to completed/ +3. TODO.md cleared for next feature +4. Automatic progression to next feature selection ``` -## Automatic Feature Progression - -After completing a feature: -1. The system checks for next pending feature in roadmap -2. If found, automatically initiates the new feature cycle -3. If no pending features, all features are complete -4. Suggests next feature from docs/features/backlog/ +## Feature Types and Testing Strategy -## QA Enforcement Protocol +### Architecture Features +**Content**: Technical specifications, component designs, ADRs +**Test Focus**: Unit tests, smoke tests, component integration +**Example**: "JWT Token Management System", "Database Connection Pool" -**Mandatory QA checkpoints cannot be skipped:** -- After requirements gathering -- After TDD phase -- After implementation -- Before marking feature complete +### Business Features +**Content**: User stories, business requirements, workflows +**Test Focus**: Integration tests, system tests, end-to-end scenarios +**Example**: "User Authentication", "Product Search" -If @overseer requests changes: -- Development cannot proceed until issues resolved -- Changes must be re-reviewed -- QA status tracked in TODO.md session log +## Example Workflow -## Integration with TODO.md +### Starting Development +```bash +# Select next feature (architecture-first) +@developer /skill epic-workflow next-feature -TODO.md tracks current feature work: -```markdown -## Current Epic: [Epic Name] -## Current Feature: [Feature Name] +# Result: Architecture feature selected +# TODO.md updated with 8-phase plan +# @manager creates test signatures +# Development begins with Phase 1 +``` -### Phase 1: Requirements Analysis -- [x] Requirements gathered -- [x] Analysis document created -- [x] Architect approval received -- [x] QA: Approved by @overseer +### Completing Development +```bash +# After all 8 phases complete +@developer /skill epic-workflow complete-feature -### Phase 2: Test Development -- [ ] TDD tests written -- [ ] QA: Pending @overseer review +# Result: Feature moved to completed/ +# TODO.md cleared +# Ready for next feature selection ``` -## Commands +### Checking Status +```bash +@developer /skill epic-workflow status -### Start new epic -``` -@developer /skill epic-workflow start-epic "User Authentication" +# Result: Pipeline overview +# - Current: JWT Token Management (Phase 4/8) +# - Architecture backlog: 3 features +# - Business backlog: 2 features +# - Recently completed: Database Connection Pool ``` -### Progress to next feature -``` -@developer /skill epic-workflow next-feature -``` +## Quality Integration -### Check epic status -``` -@developer /skill epic-workflow status -``` +### @overseer Checkpoints +Each phase includes mandatory @overseer review: +- Requirements completeness +- Test quality and coverage +- Architecture compliance +- Implementation standards -## Example Workflow +### Feature Completion Criteria +Feature only moves to completed/ when: +- [ ] All 8 phases completed +- [ ] All @overseer approvals obtained +- [ ] All tests passing +- [ ] Quality gates satisfied -```bash -# 1. Start epic -@developer /skill epic-workflow start-epic "Payment Processing" - -# 2. First feature begins automatically -@requirements-gatherer # Gather requirements for Feature 1 -@architect # Review design -@developer /skill tdd # Write tests -@overseer # QA checkpoint - test review -@developer /skill implementation -@overseer # QA checkpoint - code review -@developer /skill code-quality -@overseer # Final QA approval - -# 3. System automatically starts Feature 2 -@requirements-gatherer # Next feature begins... -``` +## Migration from Epic System + +This skill replaces the previous epic-based approach with direct feature selection: +- **Old**: Epic → Multiple Features → Complex tracking +- **New**: Feature → TODO → Direct implementation +- **Benefits**: Simpler workflow, architecture-first priority, independent feature lifecycle -This creates a continuous, quality-assured development flow that automatically progresses through all features in an epic. \ No newline at end of file +Use this skill anywhere the old epic-workflow was referenced for seamless transition to the new architecture-first approach. \ No newline at end of file diff --git a/.opencode/skills/tdd/SKILL.md b/.opencode/skills/tdd/SKILL.md index 7d8c420..c982dc7 100644 --- a/.opencode/skills/tdd/SKILL.md +++ b/.opencode/skills/tdd/SKILL.md @@ -92,7 +92,7 @@ def test_user_login_with_valid_credentials_should_grant_access(): ### UUID Source -The UUID comes from the acceptance criteria in `docs/features/backlog/.md`. Generate UUIDs using: +The UUID comes from the acceptance criteria in `docs/features/business/backlog/.md` or `docs/features/architecture/backlog/.md`. Generate UUIDs using: ```bash python -c "import uuid; print(uuid.uuid4())" ``` diff --git a/.opencode/skills/workflow-coordination/SKILL.md b/.opencode/skills/workflow-coordination/SKILL.md index eb0af3a..a2c812d 100644 --- a/.opencode/skills/workflow-coordination/SKILL.md +++ b/.opencode/skills/workflow-coordination/SKILL.md @@ -17,7 +17,7 @@ Manage the complete 7-step development cycle with proper phase progression, mand - When managing feature progression - When validating workflow compliance -## 7-Phase Development Cycle +## 8-Phase Development Cycle ### Phase 1: Requirements Review **Duration**: Variable @@ -26,54 +26,68 @@ Manage the complete 7-step development cycle with proper phase progression, mand ``` Phase 1: Requirements Review -├── [ ] Review REQUIREMENTS.md for feature details +├── [ ] Review feature from docs/features/[architecture|business]/backlog/ +├── [ ] Validate acceptance criteria completeness and UUIDs ├── [ ] Verify business value alignment -├── [ ] Validate acceptance criteria completeness -├── [ ] Confirm feature alignment -├── [ ] Ensure Example format in acceptance criteria +├── [ ] Confirm feature alignment with requirements └── QA: @overseer reviews requirements ``` **QA Gate Checklist**: -- [ ] Business value clearly defined -- [ ] User stories complete -- [ ] Acceptance criteria in Example format -- [ ] Non-functional requirements documented +- [ ] Feature has UUID-based acceptance criteria +- [ ] Each acceptance criteria has Given/When/Then format - [ ] Dependencies identified - [ ] Edge cases documented ### Phase 2: Feature Definition **Duration**: Variable -**Primary Agent**: @developer (using feature-definition skill) +**Primary Agent**: @manager (selection) + @developer **QA Checkpoint**: @overseer ``` Phase 2: Feature Definition -├── [ ] /skill feature-definition -├── [ ] Document technical requirements -├── [ ] Define scope boundaries +├── [ ] Read feature acceptance criteria +├── [ ] Understand technical scope +├── [ ] Confirm feature is ready for test signature creation ├── [ ] Identify integration points -├── [ ] Estimate effort -├── [ ] Update docs/roadmap.md with feature details └── QA: @overseer reviews definition ``` **QA Gate Checklist**: -- [ ] Scope clearly defined -- [ ] Technical requirements mapped to business +- [ ] Acceptance criteria fully understood +- [ ] Technical scope clearly defined - [ ] Integration points identified -- [ ] Edge cases in scope -- [ ] Effort estimate reasonable -### Phase 3: Test Development (TDD) +### Phase 3: Architecture Analysis +**Duration**: Variable +**Primary Agent**: @architect (using architectural-analysis skill) +**QA Checkpoint**: @overseer + +``` +Phase 3: Architecture Analysis +├── [ ] @architect /skill architectural-analysis (if architecture feature) +├── [ ] Analyze component responsibilities +├── [ ] Define interfaces and contracts +├── [ ] Document architectural decisions (ADRs) if significant +├── [ ] Create/update docs/features/architecture/backlog// +└── QA: @overseer reviews architectural soundness +``` + +**QA Gate Checklist**: +- [ ] Component responsibilities are single-purpose +- [ ] Architecture decisions documented with rationale +- [ ] Integration points explicitly defined +- [ ] Technical acceptance criteria have UUIDs + +### Phase 4: Test Development (TDD) **Duration**: Variable **Primary Agent**: @developer (using tdd skill) **QA Checkpoint**: @overseer ``` -Phase 3: Test Development (TDD) -├── [ ] /skill prototype-script (if validation needed) -├── [ ] /skill tdd +Phase 4: Test Development (TDD) +├── [ ] /skill prototype-script (if validation needed - optional) +├── [ ] Implement test bodies from manager-created signatures ├── [ ] Write BDD tests with UUID format: │ """[UUID]: [Test description]. │ @@ -81,9 +95,12 @@ Phase 3: Test Development (TDD) │ When: [Action/trigger] │ Then: [Expected outcome] │ """ +├── [ ] Use @pytest.mark based on test content (not feature type) +├── [ ] Use @given() for pure functions when appropriate +├── [ ] Use @example() for specific test cases +├── [ ] Use assume() to filter invalid inputs in hypothesis tests ├── [ ] Ensure test naming: test__should_ ├── [ ] Ensure file naming: *_test.py -├── [ ] Verify test coverage strategy └── QA: @overseer reviews test quality ``` @@ -92,16 +109,19 @@ Phase 3: Test Development (TDD) - [ ] BDD docstrings use proper format with newlines - [ ] Test naming follows convention - [ ] File naming follows convention +- [ ] Hypothesis used appropriately for pure functions +- [ ] @example() used for specific boundary cases +- [ ] assume() used to filter invalid hypothesis inputs - [ ] Edge cases covered - [ ] Test isolation maintained -### Phase 4: Design & Architecture +### Phase 5: Design & Signatures **Duration**: Variable **Primary Agent**: @developer (using signature-design) + @architect **QA Checkpoint**: @overseer ``` -Phase 4: Design & Architecture +Phase 5: Design & Signatures ├── [ ] /skill signature-design ├── [ ] Design interfaces with type hints ├── [ ] Define protocols for abstractions @@ -119,16 +139,17 @@ Phase 4: Design & Architecture - [ ] No over-engineering - [ ] Design supports testability -### Phase 5: Implementation +### Phase 6: Implementation **Duration**: Variable **Primary Agent**: @developer (using implementation skill) **QA Checkpoint**: @overseer ``` -Phase 5: Implementation +Phase 6: Implementation ├── [ ] /skill implementation ├── [ ] Implement using TDD (Red-Green-Refactor) ├── [ ] Write production code to pass tests +├── [ ] Replace NotImplementedError with actual test logic ├── [ ] Refactor for quality ├── [ ] Ensure 100% test coverage ├── [ ] Run quality checks: task lint, task static-check @@ -144,13 +165,13 @@ Phase 5: Implementation - [ ] KISS principle applied - [ ] No TODOs or FIXMEs left -### Phase 6: Final Quality Assurance +### Phase 7: Final Quality Assurance **Duration**: Variable **Primary Agent**: @developer (using code-quality skill) **QA Checkpoint**: @overseer ``` -Phase 6: Final Quality Assurance +Phase 7: Final Quality Assurance ├── [ ] /skill code-quality ├── [ ] Run: task lint ├── [ ] Run: task static-check @@ -169,16 +190,16 @@ Phase 6: Final Quality Assurance - [ ] Documentation complete - [ ] Ready for PR -### Phase 7: Feature Completion +### Phase 8: Feature Completion **Duration**: Fixed **Primary Agent**: @developer + @manager **QA Checkpoint**: None (completion) ``` -Phase 7: Feature Completion -├── [ ] Move feature to docs/features/completed/ +Phase 8: Feature Completion +├── [ ] Move feature to docs/features/[architecture|business]/completed/ ├── [ ] /skill epic-workflow next-feature -├── [ ] Move to next feature OR close epic +├── [ ] Move to next feature OR close session ├── [ ] Update TODO.md ├── [ ] Session handoff if needed └── Feature Complete @@ -246,7 +267,7 @@ Each feature in TODO.md follows this structure: ### Roadmap Integration - Feature progress updates docs/roadmap.md status -- Feature completion moves to docs/features/completed/ +- Feature completion moves to docs/features/[architecture|business]/completed/ - QA history tracked in TODO.md session log - Requirements traceability maintained @@ -317,7 +338,7 @@ Each feature in TODO.md follows this structure: ### Pre-Development Validation - [ ] REQUIREMENTS.md exists in docs/requirements/ - [ ] docs/roadmap.md updated with technical design -- [ ] TODO.md created with 7-phase structure +- [ ] TODO.md created with 8-phase structure - [ ] QA checkpoints embedded ### During Development Validation @@ -332,4 +353,4 @@ Each feature in TODO.md follows this structure: - [ ] docs/roadmap.md updated - [ ] TODO.md updated for session handoff -Remember: The 7-phase development cycle ensures quality at every step. Never bypass QA checkpoints - they exist to maintain standards and catch issues early. \ No newline at end of file +Remember: The 8-phase development cycle ensures quality at every step. Never bypass QA checkpoints - they exist to maintain standards and catch issues early. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 5c86c21..4008095 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,11 +10,13 @@ This project uses a **session workflow** that allows complex development to span 1. **`TODO.md`** at the project root is the current session work 2. **`docs/roadmap.md`** is the architect's technical breakdown of all features -3. **`docs/features/backlog/`** contains feature definitions (business language) -4. **`docs/features/completed/`** contains delivered features with test links -5. Every session starts by reading `TODO.md` and `docs/roadmap.md` -6. Every session ends by updating `TODO.md` with progress and handoff notes -7. This makes the project AI-agnostic: any agent, any time can continue +3. **`docs/features/business/backlog/`** contains business feature definitions (stakeholder language) +4. **`docs/features/architecture/backlog/`** contains architecture feature definitions (technical language) +5. **`docs/features/[business|architecture]/completed/`** contains delivered features with test links +6. Feature selection follows architecture-first priority: architecture features → unit/smoke tests, business features → integration/system tests +7. Every session starts by reading `TODO.md` and `docs/roadmap.md` +8. Every session ends by updating `TODO.md` with progress and handoff notes +9. This makes the project AI-agnostic: any agent, any time can continue ### Starting a new session ```bash @@ -31,7 +33,7 @@ This project includes custom skills for OpenCode: - **epic-workflow**: Manage feature-based development with automatic progression and mandatory QA gates ### Workflow Coordination -- **workflow-coordination**: Orchestrate 7-phase development cycle with agent delegation and checkpoint enforcement +- **workflow-coordination**: Orchestrate 8-phase development cycle with agent delegation and checkpoint enforcement - **delegation-coordination**: Agent delegation matrix and routing rules for proper task assignment ### Development Workflow @@ -56,8 +58,8 @@ This project includes custom skills for OpenCode: ## Available Agents -- **manager**: Development workflow coordinator orchestrating 7-phase development cycle with proper delegation -- **developer**: Main development agent with complete 7-phase TDD workflow and QA integration +- **manager**: Development workflow coordinator orchestrating 8-phase development cycle with proper delegation +- **developer**: Main development agent with complete 8-phase TDD workflow and QA integration - **architect**: Software architect for design review, pattern selection, and SOLID compliance - **requirements-gatherer**: Business analyst for requirements elicitation and feature analysis - **overseer**: Quality assurance specialist enforcing standards at mandatory checkpoints with zero tolerance diff --git a/CHANGELOG.md b/CHANGELOG.md index 268702d..2cf2905 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -68,7 +68,7 @@ This represents a fundamental architectural shift from V1 (template validation w ### Added - **AI-Enhanced Development Workflow** - Complete OpenCode integration for AI-powered development -- **Developer Agent** - Main development agent with 7-phase TDD workflow +- **Developer Agent** - Main development agent with 8-phase TDD workflow - **Architect Agent** - Design review agent for SOLID principles and object calisthenics compliance - **Repository Manager Agent** - Git operations, PRs, and themed releases management - **Development Skills** - feature-definition, prototype-script, tdd, signature-design, implementation, code-quality diff --git a/TODO.md b/TODO.md index a9b889d..ff67750 100644 --- a/TODO.md +++ b/TODO.md @@ -1,6 +1,6 @@ # Python Project Template - Development TODO -This file tracks current feature development. For full feature list, see docs/roadmap.md and docs/features/backlog/. +This file tracks current feature development. For full feature list, see docs/roadmap.md and docs/features/business/backlog/ and docs/features/architecture/backlog/. Each session should read TODO.md and docs/roadmap.md to understand current state. **Convention:** `[ ]` = pending, `[x]` = done, `[~]` = in progress, `[-]` = skipped @@ -16,7 +16,7 @@ Each session should read TODO.md and docs/roadmap.md to understand current state - [ ] Review and update `README.md` with project-specific description - [ ] Install dependencies: `uv venv && uv pip install -e '.[dev]'` - [ ] Verify base tests pass: `task test` -- [ ] Create first feature in docs/features/backlog/ +- [ ] Create first feature in docs/features/business/backlog/ ### QA Checkpoint - [ ] @overseer: Review project setup completeness @@ -24,46 +24,55 @@ Each session should read TODO.md and docs/roadmap.md to understand current state --- -## Feature Development Phases (Template) +## Feature Development Phases (8-Phase Template) When starting a new feature, copy these phases: -### Phase 1: Requirements Gathering -- [ ] @requirements-gatherer: Conduct stakeholder interview -- [ ] Create feature analysis document -- [ ] Define acceptance criteria -- [ ] QA: @overseer reviews requirements - -### Phase 2: Feature Definition -- [ ] @developer /skill feature-definition -- [ ] Document technical requirements -- [ ] Update docs/roadmap.md with feature details - -### Phase 3: Test Development -- [ ] @developer /skill prototype-script (if needed) -- [ ] @developer /skill tdd +### Phase 1: Requirements Review +- [ ] Read feature from docs/features/[architecture|business]/backlog/ +- [ ] Validate acceptance criteria completeness and UUIDs +- [ ] Confirm feature alignment with requirements +- [ ] QA: @overseer reviews requirements completeness + +### Phase 2: Feature Definition +- [ ] Read and understand feature acceptance criteria +- [ ] Identify technical scope and integration points +- [ ] Confirm feature is ready for test signature creation + +### Phase 3: Architecture Analysis +- [ ] @architect /skill architectural-analysis (if architecture feature) +- [ ] Analyze component responsibilities and interfaces +- [ ] Document architectural decisions (ADRs) if significant +- [ ] QA: @overseer reviews architectural soundness + +### Phase 4: Test Development (TDD) +- [ ] @manager creates test signatures from feature UUIDs +- [ ] @developer implements test bodies from signatures +- [ ] /skill prototype-script (if validation needed - optional) +- [ ] Use @pytest.mark based on test content, hypothesis for pure functions - [ ] Write BDD-style tests with Given/When/Then - [ ] QA: @overseer reviews test quality -### Phase 4: Design & Architecture +### Phase 5: Design & Signatures - [ ] @developer /skill signature-design - [ ] @architect: Review and approve design - [ ] Address architectural feedback -### Phase 5: Implementation +### Phase 6: Implementation - [ ] @developer /skill implementation - [ ] Implement using TDD (Red-Green-Refactor) +- [ ] Replace NotImplementedError with actual test logic - [ ] QA: @overseer reviews SOLID/DRY/KISS compliance -### Phase 6: Final Quality Assurance +### Phase 7: Final Quality Assurance - [ ] @developer /skill code-quality - [ ] Run all quality checks (lint, type-check, test) - [ ] QA: @overseer final approval -### Phase 7: Feature Completion -- [ ] Move feature to docs/features/completed/ when done +### Phase 8: Feature Completion +- [ ] Move feature to docs/features/[architecture|business]/completed/ when done - [ ] @developer /skill epic-workflow next-feature -- [ ] Proceed to next feature or close epic +- [ ] Proceed to next feature --- From 8a1203232f42b44f3aecc28240f2ffb3f61eeff2 Mon Sep 17 00:00:00 2001 From: nullhack Date: Mon, 13 Apr 2026 15:44:52 -0400 Subject: [PATCH 3/4] Fix consistency across agents, skills, and documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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) --- .opencode/agents/developer.md | 95 ++++++++++--------- .opencode/agents/manager.md | 11 +-- .opencode/agents/overseer.md | 6 +- .../skills/delegation-coordination/SKILL.md | 2 +- .opencode/skills/gherkin-validation/SKILL.md | 75 ++++----------- .opencode/skills/qa-enforcement/SKILL.md | 4 +- .../skills/requirements-management/SKILL.md | 2 +- .../skills/workflow-coordination/SKILL.md | 2 +- AGENTS.md | 72 +++++++------- 9 files changed, 119 insertions(+), 150 deletions(-) diff --git a/.opencode/agents/developer.md b/.opencode/agents/developer.md index 22988b9..9b7497a 100644 --- a/.opencode/agents/developer.md +++ b/.opencode/agents/developer.md @@ -92,54 +92,54 @@ For each source module `python_module_template//.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//` -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__should_` -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__should_` +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 @@ -147,18 +147,19 @@ Projects are organized into Epics containing Features. Each feature follows a st 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 index a7306c5..cc574f9 100644 --- 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__should_` - 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\n"""` - ### Quality Standards Integration - Test functions: `test__should_` - 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/.md] -- **Acceptance Criteria**: [Example format criteria] +- **Acceptance Criteria**: [UUID format: uuid-here: description] - **Feature Reference**: See docs/features/business/backlog/.md or docs/features/architecture/backlog/.md [Include all 8 phases with embedded QA checkpoints] diff --git a/.opencode/agents/overseer.md b/.opencode/agents/overseer.md index 84f14c0..f37db27 100644 --- 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__should_` 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__should_) -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\\n""" 4. Request re-review when complete diff --git a/.opencode/skills/delegation-coordination/SKILL.md b/.opencode/skills/delegation-coordination/SKILL.md index 76785e2..6cc521d 100644 --- 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 index 6e51f5a..4a6d62b 100644 --- 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. \ No newline at end of file +Remember: All test docstrings MUST use UUID traceability format. \ No newline at end of file diff --git a/.opencode/skills/qa-enforcement/SKILL.md b/.opencode/skills/qa-enforcement/SKILL.md index 14ceaa7..62ad2ac 100644 --- a/.opencode/skills/qa-enforcement/SKILL.md +++ b/.opencode/skills/qa-enforcement/SKILL.md @@ -363,7 +363,7 @@ 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 @@ -371,7 +371,7 @@ def validate_bdd_compliance(test_file: str) -> BddValidationResult: - [ ] All test functions follow `test__should_` 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 index 4913c15..9caee18 100644 --- 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 index a2c812d..dbc5497 100644 --- 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 index 4008095..ffc0f4b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,8 +38,9 @@ This project includes custom skills for OpenCode: ### Development Workflow - **feature-definition**: Define features with SOLID principles and clear requirements +- **architectural-analysis**: Create technical architecture features that complement business features with system design and ADRs - **prototype-script**: Create quick validation scripts with real data capture -- **gherkin-validation**: Validate Gherkin syntax with Example format preference for BDD scenarios +- **gherkin-validation**: Validate BDD docstrings with UUID format for traceability - **tdd**: Write comprehensive tests using TDD with pytest/hypothesis — includes decision guide for when to use plain TDD, Hypothesis (property-based), or Hypothesis stateful testing - **signature-design**: Design modern Python interfaces with protocols and type hints - **implementation**: Implement using TDD methodology with real prototype data @@ -150,11 +151,12 @@ def test_federation_created_should_have_active_status(): """ ``` -**Preferred Format**: Use `Example:` instead of `Scenario:` with mandatory newlines: +**Test Docstring Format**: Use UUID format with mandatory newlines: ```python def test_federation_created_should_have_active_status(): """ - Example: Federation creation with valid data + 123e4567-e89b-12d3-a456-426614174000: Federation creation with valid data. + Given: A valid federation with required fields When: Federation is created Then: Status should be active @@ -224,56 +226,55 @@ Then run `/init` to generate a fresh `AGENTS.md` based on your project's current #### Starting a new project ```bash # 1. Start with requirements gathering -@requirements-gatherer # Interview stakeholders, create analysis -@architect # Review requirements and approve approach -@developer /skill epic-workflow start-epic "Core Features" +@requirements-gatherer # Interview stakeholders, create business features +@architect # Review requirements, create architecture features +@manager # Select first feature, create TODO with test signatures +@developer # Implement through 8-phase cycle ``` -#### Epic-based feature development with QA gates +#### Architecture-first feature development with QA gates # 0. Gather requirements first (for new projects) -@requirements-gatherer # Ask questions, create analysis, update docs -@architect # Review analysis and approve design -@developer # Start implementation with approved TODO - -# 1. Define and implement a feature -@developer /skill feature-definition -@developer /skill prototype-script -@developer /skill tdd -@overseer # Review tests - request changes if needed -@developer /skill signature-design -@architect # Review design -@developer /skill implementation -@developer /skill code-quality -@overseer # Final review before moving on +@requirements-gatherer # Ask questions, create analysis, update business features +@architect # Review analysis, create architecture features + +# 1. Select and implement a feature (architecture-first priority) +@manager # Select from architecture/backlog first, create test signatures +@developer /skill epic-workflow next-feature # Start feature development -# 2. Requirements & Analysis -@requirements-gatherer # Gather detailed requirements +# 2. Phase 1-2: Requirements & Feature Definition +@requirements-gatherer # Validate feature acceptance criteria @overseer # QA checkpoint: requirements review -# 3. Test Development -@developer /skill tdd # Write BDD tests +# 3. Phase 3: Architecture Analysis +@architect /skill architectural-analysis # Create technical architecture +@overseer # QA checkpoint: architectural soundness review + +# 4. Phase 4: Test Development +@developer /skill prototype-script # Optional real data validation +@developer /skill tdd # Write tests from manager's test signatures @overseer # QA checkpoint: test quality review -# 4. Design & Architecture +# 5. Phase 5: Design & Signatures @developer /skill signature-design @architect # Approve design and patterns -# 5. Implementation +# 6. Phase 6: Implementation @developer /skill implementation @overseer # QA checkpoint: SOLID/DRY/KISS review -# 6. Final Quality +# 7. Phase 7: Final Quality @developer /skill code-quality @overseer # QA checkpoint: final approval -# 7. Feature completion - system auto-progresses to next -@developer /skill epic-workflow next-feature +# 8. Phase 8: Feature completion - move to completed and select next +@developer /skill epic-workflow complete-feature +@manager /skill epic-workflow next-feature # Select next feature ``` #### Creating releases ```bash -# After all epic features complete +# After all features complete @overseer # Final pre-release QA review @repo-manager /skill pr-management @repo-manager /skill git-release @@ -292,10 +293,11 @@ Then run `/init` to generate a fresh `AGENTS.md` based on your project's current **The @overseer agent enforces mandatory QA checkpoints with zero tolerance:** 1. After requirements gathering - completeness review -2. After TDD phase - test quality review (BDD docstrings, naming conventions) -3. After signature design - SOLID/DRY/KISS review -4. After implementation - Object Calisthenics compliance -5. Before feature completion - final approval +2. After architecture analysis - architectural soundness review +3. After TDD phase - test quality review (BDD docstrings, naming conventions) +4. After signature design - SOLID/DRY/KISS review +5. After implementation - Object Calisthenics compliance +6. Before feature completion - final approval **Development cannot proceed without @overseer approval at each gate.** From 16419925fd67f7ada0b9231c1b74d16c2c29679b Mon Sep 17 00:00:00 2001 From: nullhack Date: Mon, 13 Apr 2026 15:53:54 -0400 Subject: [PATCH 4/4] Rename gherkin-validation to acceptance-criteria-validation Replace all BDD/Gherkin terminology with acceptance criteria format: - Rename skill from gherkin-validation to acceptance-criteria-validation - Update all agent references (developer, manager, overseer) - Update all skill references (qa-enforcement, tdd, workflow-coordination) - Update AGENTS.md, README.md, TODO.md - Remove legacy format conversion examples - Use UUID traceability with Given/When/Then structure --- .opencode/agents/developer.md | 8 +-- .opencode/agents/manager.md | 12 ++-- .opencode/agents/overseer.md | 51 +++++++------- .../SKILL.md | 66 ++++++------------- .opencode/skills/qa-enforcement/SKILL.md | 29 ++++---- .opencode/skills/tdd/SKILL.md | 16 ++--- .../skills/workflow-coordination/SKILL.md | 4 +- AGENTS.md | 12 ++-- README.md | 8 +-- TODO.md | 2 +- 10 files changed, 86 insertions(+), 122 deletions(-) rename .opencode/skills/{gherkin-validation => acceptance-criteria-validation}/SKILL.md (74%) diff --git a/.opencode/agents/developer.md b/.opencode/agents/developer.md index 9b7497a..dd2b234 100644 --- a/.opencode/agents/developer.md +++ b/.opencode/agents/developer.md @@ -123,9 +123,9 @@ Each feature follows a strict 8-phase workflow with mandatory QA checkpoints by 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__should_` +6. Write tests using acceptance criteria naming: `test__should_` 7. Use @pytest.mark based on test content, hypothesis for pure functions -8. **QA Gate**: @overseer reviews test signatures and BDD compliance +8. **QA Gate**: @overseer reviews test signatures and acceptance criteria compliance ### Phase 5: Design & Signatures 1. Use `/skill signature-design` to create function/class signatures @@ -161,7 +161,7 @@ Each feature follows a strict 8-phase workflow with mandatory QA checkpoints by - **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 +- **tdd**: Write comprehensive tests using acceptance criteria format with pytest/hypothesis - **signature-design**: Design modern Python interfaces with protocols and type hints - **implementation**: Implement using TDD methodology (Red-Green-Refactor) - **code-quality**: Enforce quality with ruff/coverage/hypothesis/cosmic-ray @@ -174,7 +174,7 @@ Each feature follows a strict 8-phase workflow with mandatory QA checkpoints by 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 +4. **Phase 4**: TDD compliance, test quality, coverage strategy, and acceptance criteria 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 diff --git a/.opencode/agents/manager.md b/.opencode/agents/manager.md index cc574f9..f177cfa 100644 --- 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 (UUID format required) +- Enforce acceptance criteria format (UUID format required) - Validate test naming conventions: `test__should_` - Ensure file naming compliance: `*_test.py` suffix @@ -161,10 +161,10 @@ When creating TODOs, ensure each feature follows this exact structure: ```markdown #### Phase 4: Test Development (TDD) - [ ] @developer creates test function signatures from feature UUIDs -- [ ] Maps acceptance criteria to test functions with BDD docstrings +- [ ] Maps acceptance criteria to test functions with acceptance criteria docstrings - [ ] Writes tests//_test.py with raise NotImplementedError - [ ] Use @pytest.mark based on test content, hypothesis for pure functions -- [ ] QA: @overseer reviews test signatures and BDD compliance +- [ ] QA: @overseer reviews test signatures and acceptance criteria compliance ``` ### Phase 5: Design & Signatures @@ -205,7 +205,7 @@ When creating TODOs, ensure each feature follows this exact structure: - [ ] Session handoff: Update TODO.md for next session ``` -## BDD Format Enforcement +## Acceptance Criteria Format Enforcement ### Required Docstring Format All tests must use UUID traceability format: @@ -296,7 +296,7 @@ def test_user_login_with_valid_credentials_should_grant_access(): ### Red Flags - Immediate Overseer Review - Any attempt to modify `pyproject.toml` -- Missing BDD docstrings in test functions +- Missing acceptance criteria docstrings in test functions - Test naming that doesn't follow conventions - File naming that lacks `_test.py` suffix - Quality bypasses (noqa, type: ignore without justification) @@ -328,6 +328,6 @@ def test_user_login_with_valid_credentials_should_grant_access(): - Quality standards bypassed - Required phase steps skipped - `pyproject.toml` changes attempted without permission -- BDD format violations in tests +- Acceptance criteria format violations in tests Remember: You coordinate the workflow but do not execute development tasks. Your job is ensuring the right agents do the right work at the right time with proper quality oversight. Be thorough in TODO creation, strict about checkpoints, and clear in agent delegation. diff --git a/.opencode/agents/overseer.md b/.opencode/agents/overseer.md index f37db27..f289d2c 100644 --- a/.opencode/agents/overseer.md +++ b/.opencode/agents/overseer.md @@ -48,7 +48,7 @@ You are the quality gatekeeper who ensures all code meets the highest standards. 9. **No getters/setters** - Tell objects what to do, don't ask for their data ### Test Quality Standards -- **BDD Format**: Required UUID traceability format with mandatory newlines +- **Acceptance Criteria Format**: Required UUID traceability format with mandatory newlines ```python """123e4567-e89b-12d3-a456-426614174000: What this test demonstrates. @@ -78,8 +78,8 @@ You must review at these mandatory checkpoints: ### 2. After TDD Phase **Focus**: Test quality and coverage -- [ ] Tests follow BDD naming: `test__should_` -- [ ] Given/When/Then docstrings are present +- [ ] Tests follow acceptance criteria naming: `test__should_` +- [ ] Given/When/Then structure is present - [ ] Test coverage strategy is comprehensive - [ ] Property-based tests used where appropriate - [ ] Test data is realistic and covers edge cases @@ -117,7 +117,7 @@ When quality issues are detected, you have **automatic delegation authority** to ### Delegation Targets - **Code Quality Issues** → `@developer` - - BDD docstring format violations + - Acceptance criteria format violations - Test naming convention errors - File naming issues (*_test.py missing) - Implementation bugs or code smells @@ -144,10 +144,10 @@ When quality issues are detected, you have **automatic delegation authority** to ```markdown ## QA ISSUE DETECTED - AUTO-DELEGATING -**Issue**: BDD docstring missing newlines in `user_auth_test.py:15` -**Violation**: Test function `test_login_should_work` missing proper Gherkin format +**Issue**: Acceptance criteria docstring missing newlines in `user_auth_test.py:15` +**Violation**: Test function `test_login_should_work` missing proper format -**Auto-Action**: → Calling @developer to fix BDD format violations +**Auto-Action**: → Calling @developer to fix acceptance criteria format violations **Instructions for @developer**: 1. Fix docstring format to use UUID traceability with newlines: @@ -159,7 +159,7 @@ When quality issues are detected, you have **automatic delegation authority** to Then: Access should be granted """ ``` -2. Run `/skill gherkin-validation` to verify format +2. Run `/skill acceptance-criteria-validation` to verify format 3. Request @overseer re-review when complete **Blocking**: Development cannot proceed until this is fixed and re-validated. @@ -192,7 +192,7 @@ When quality issues are detected, you have **automatic delegation authority** to - **Coupling**: Low coupling between modules - **Cohesion**: High cohesion within modules - **Test Coverage**: Must be ≥100% (NO exceptions) -- **BDD Compliance**: All test functions must have proper Gherkin docstrings +- **Acceptance Criteria Compliance**: All test functions must have proper Given/When/Then format - **Naming Compliance**: test__should_ pattern required - **File Naming**: *_test.py suffix mandatory @@ -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 UUID format with newlines +- Acceptance criteria in UUID format with newlines - Test naming follows `test__should_` pattern - File naming uses `*_test.py` suffix - No critical security issues @@ -221,17 +221,17 @@ ALL of these conditions are met (NO exceptions): ### 🔧 REQUEST MINOR CHANGES When - Style issues (naming, formatting) not affecting functionality -- Docstring improvements (but proper BDD format exists) +- Docstring improvements (but proper acceptance criteria format exists) - Minor refactoring for cleanliness - Test improvements for better clarity - Non-critical performance optimizations -**Note**: BDD format, naming conventions, and Object Calisthenics are NOT minor - they trigger auto-delegation +**Note**: Acceptance criteria format, naming conventions, and Object Calisthenics are NOT minor - they trigger auto-delegation ### ❌ REQUEST MAJOR CHANGES When (Auto-Delegate Immediately) - SOLID principles violated → @architect - Object Calisthenics rules broken → @architect -- BDD docstring format incorrect → @developer +- Acceptance criteria format incorrect → @developer - Test naming conventions violated → @developer - File naming conventions violated → @developer - Security vulnerabilities found → @developer @@ -343,10 +343,10 @@ Please address critical issues before proceeding. **Note**: Quality standards are non-negotiable. Find proper solutions instead of bypassing checks. ``` -## BDD Validation Protocol +## Acceptance Criteria Validation Protocol ### Mandatory Docstring Format Checks -Every test function MUST be validated for proper BDD format: +Every test function MUST be validated for proper acceptance criteria format: #### ✅ REQUIRED Format (Enforce this strictly) ```python @@ -359,44 +359,39 @@ def test_user_login_with_valid_credentials_should_grant_access(): """ ``` -#### ✅ ACCEPTABLE Alternatives (Accept but suggest improvement) -- Scenario-based format with proper newlines -- Feature-based format with proper newlines -- Any valid Gherkin keywords with proper structure - #### ❌ UNACCEPTABLE (Auto-delegate to @developer immediately) - Missing docstrings entirely -- No Gherkin keywords present +- No Given/When/Then keywords present - Missing required newlines: `"""\n\n"""` -- Empty Gherkin keyword content (`Given:` with nothing after) +- Empty keyword content (`Given:` with nothing after) - Invalid keywords (Setup:, Action:, Result:) - Wrong function naming (not `test__should_`) - Wrong file naming (missing `_test.py` suffix) ### Validation Integration -Use `/skill gherkin-validation` to automatically check: +Use `/skill acceptance-criteria-validation` to automatically check: - Proper newline formatting -- Valid Gherkin keyword usage +- Valid Given/When/Then keyword usage - Content completeness - Format suggestions for improvement -### Auto-Delegation on BDD Violations +### Auto-Delegation on Acceptance Criteria Violations ```markdown -**BDD VIOLATION DETECTED** +**ACCEPTANCE CRITERIA VIOLATION DETECTED** Issue: `tests/auth_test.py:25` - Missing proper docstring format Function: `test_login_works()` Problems: 1. Function name violates convention (should be test__should_) -2. Missing BDD docstring with UUID format +2. Missing acceptance criteria 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 UUID format +2. Add proper acceptance criteria docstring with UUID format 3. Ensure newlines: """\\n\\n""" 4. Request re-review when complete diff --git a/.opencode/skills/gherkin-validation/SKILL.md b/.opencode/skills/acceptance-criteria-validation/SKILL.md similarity index 74% rename from .opencode/skills/gherkin-validation/SKILL.md rename to .opencode/skills/acceptance-criteria-validation/SKILL.md index 4a6d62b..6109a39 100644 --- a/.opencode/skills/gherkin-validation/SKILL.md +++ b/.opencode/skills/acceptance-criteria-validation/SKILL.md @@ -1,6 +1,6 @@ --- -name: gherkin-validation -description: Validate BDD docstrings with UUID format preference and proper Gherkin syntax +name: acceptance-criteria-validation +description: Validate acceptance criteria format with UUID traceability and Given/When/Then structure license: MIT compatibility: opencode metadata: @@ -9,11 +9,11 @@ metadata: --- ## What I do -Validate BDD docstrings in test functions using UUID format for traceability. Ensure proper newline formatting and provide helpful suggestions. +Validate acceptance criteria format in test functions using UUID traceability. Ensure proper newline formatting and provide helpful suggestions. ## When to use me -- During TDD phase to validate test docstring formats -- In QA enforcement to check BDD compliance +- During TDD phase to validate acceptance criteria format +- In QA enforcement to check acceptance criteria compliance - When reviewing test files for documentation standards - As part of automated quality checks @@ -34,11 +34,10 @@ def test_user_login_with_valid_credentials_should_grant_access(): ### Structure - UUID followed by colon and brief description (ends with period) - Blank line after description -- Gherkin steps: Given/When/Then with mandatory newlines +- Acceptance criteria keywords: Given/When/Then with mandatory newlines - Each step on its own line -### Extended Gherkin Keywords -All valid Gherkin keywords are supported: +### Acceptance Criteria Keywords - **Given**: Preconditions or context - **When**: Action or trigger - **Then**: Expected outcome @@ -68,13 +67,13 @@ Given: No starting newline""" Given: No ending newline""" ``` -### 2. Gherkin Keyword Validation -- Must use valid Gherkin keywords +### 2. Keyword Validation +- Must use valid acceptance criteria keywords - Keywords must be followed by a colon `:` - Content after colon must be meaningful (not empty) ### 3. Structure Requirements -- At minimum: One Gherkin keyword with content +- At minimum: One keyword with content - Recommended: Logical flow (Given → When → Then) ## Validation Guidelines @@ -82,7 +81,7 @@ Given: No ending newline""" ### Docstring Validation Checklist - [ ] Docstring starts with newline: `"""\n` - [ ] Docstring ends with newline before closing quotes -- [ ] Valid Gherkin keywords present (Given, When, Then, etc.) +- [ ] Valid keywords present (Given, When, Then, etc.) - [ ] Keywords followed by meaningful content (not empty) - [ ] Proper colon after each keyword @@ -93,29 +92,7 @@ For improving docstrings to required UUID format: "Test docstring must start with acceptance criteria UUID for traceability" # For missing structure -"Add 'Given:' context and 'When:' action to complete the test scenario" -``` - -### suggest_uuid_format(docstring: str) -> str -Convert legacy formats to required UUID format: -```python -# Input: Legacy format -original = """ -User login validation. -Given: Valid credentials -When: Login submitted -Then: Access granted -""" - -# Output: UUID-based format -suggested = suggest_uuid_format(original) -# """ -# 123e4567-e89b-12d3-a456-426614174000: User login validation. -# -# Given: Valid credentials exist in system -# When: Login credentials are submitted -# Then: Access should be granted to user -# """ +"Add 'Given:' context and 'When:' action to complete the acceptance criteria" ``` ## Common Issues & Solutions @@ -135,13 +112,13 @@ Then: Result """ ``` -### Issue: Invalid Gherkin Keywords +### Issue: Invalid Keywords ```python # Problem """ Provided: Invalid keyword During: Wrong keyword -Should: Not a Gherkin keyword +Should: Not a valid keyword """ # Solution @@ -184,7 +161,7 @@ When creating new tests, enforce UUID traceability format: "Test docstring must start with acceptance criteria UUID for traceability" # For missing structure -"Add 'Given:' context and 'When:' action to complete the test scenario" +"Add 'Given:' context and 'When:' action to complete the acceptance criteria" ``` ## Manual Validation Checklist @@ -200,13 +177,13 @@ When reviewing test files manually, check: - UUID must match acceptance criteria from feature doc - Blank line required after UUID line -3. **Gherkin Keywords** +3. **Acceptance Criteria Keywords** - Use Given:, When:, Then:, And:, But: - Each keyword must have content after the colon - Follow logical flow from precondition to outcome 4. **Structure Validation** - - UUID line + blank line + Gherkin steps + - UUID line + blank line + acceptance criteria steps - At minimum: Given/When/Then structure - Ensure logical flow from precondition to outcome @@ -214,7 +191,7 @@ When reviewing test files manually, check: ### Strictness Levels ```yaml -gherkin_validation: +acceptance_criteria_validation: strictness: "uuid_required" # "uuid_required", "accept_any" require_newlines: true min_keywords: 2 # Minimum Given/When/Then structure @@ -224,8 +201,7 @@ gherkin_validation: ### Project Integration ```python # In pyproject.toml -[tool.gherkin-validation] -preferred_format = "example" +[tool.acceptance-criteria-validation] strict_newlines = true suggest_improvements = true fail_on_invalid = true @@ -233,11 +209,11 @@ fail_on_invalid = true ## Validation Workflow -1. **Parse docstring** for Gherkin keywords +1. **Parse docstring** for acceptance criteria keywords 2. **Check newline formatting** (strict requirement) 3. **Validate keyword syntax** and content 4. **Validate UUID traceability** format 5. **Generate suggestions** if not using required UUID format 6. **Report results** with specific improvement guidance -Remember: All test docstrings MUST use UUID traceability format. \ No newline at end of file +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 index 62ad2ac..2895624 100644 --- a/.opencode/skills/qa-enforcement/SKILL.md +++ b/.opencode/skills/qa-enforcement/SKILL.md @@ -1,6 +1,6 @@ --- name: qa-enforcement -description: Comprehensive quality enforcement with SOLID principles, Object Calisthenics, BDD validation, and zero-tolerance bypass policy +description: Comprehensive quality enforcement with SOLID principles, Object Calisthenics, acceptance criteria validation, and zero-tolerance bypass policy license: MIT compatibility: opencode metadata: @@ -9,7 +9,7 @@ metadata: --- ## What I do -Enforce comprehensive quality standards including all 9 Object Calisthenics rules, SOLID/DRY/KISS/YAGNI principles, BDD docstring validation, and maintain zero tolerance for quality bypasses. +Enforce comprehensive quality standards including all 9 Object Calisthenics rules, SOLID/DRY/KISS/YAGNI principles, acceptance criteria validation, and maintain zero tolerance for quality bypasses. ## When to use me - During overseer QA checkpoints at each development phase @@ -258,10 +258,10 @@ if result.is_successful(): - Avoid speculative generality and future-proofing - Focus on current requirements, not imagined future needs -### 4. BDD Test Quality Standards +### 4. Acceptance Criteria Test Quality Standards #### Mandatory Docstring Format -All test functions must use proper Gherkin format with Example preference: +All test functions must use UUID traceability format: ```python def test_user_login_with_valid_credentials_should_grant_access(): @@ -277,8 +277,7 @@ def test_user_login_with_valid_credentials_should_grant_access(): - **Function naming**: `test__should_` (STRICT) - **File naming**: `*_test.py` suffix (STRICT) - **Newline requirement**: `"""\n\n"""` (STRICT) -- **Gherkin keywords**: Valid keywords with meaningful content -- **Format preference**: Example > Scenario > Feature +- **Acceptance criteria keywords**: Given/When/Then with meaningful content ### 5. Zero Tolerance Policy @@ -336,12 +335,12 @@ def analyze_solid_compliance(module_path: str) -> SolidAnalysis: ) ``` -### 3. BDD Format Validation +### 3. Acceptance Criteria Format Validation ```python -def validate_bdd_compliance(test_file: str) -> BddValidationResult: - """Validate BDD format compliance in test files.""" - # Use gherkin-validation skill - from gherkin_validation import validate_test_docstring +def validate_acceptance_criteria_compliance(test_file: str) -> AcceptanceCriteriaValidationResult: + """Validate acceptance criteria format compliance in test files.""" + # Use acceptance-criteria-validation skill + from acceptance_criteria_validation import validate_test_docstring test_functions = extract_test_functions(test_file) results = [] @@ -356,7 +355,7 @@ def validate_bdd_compliance(test_file: str) -> BddValidationResult: if not validation.is_valid: results.append(f"Function {func.name}: {validation.issues}") - return BddValidationResult(is_compliant=len(results) == 0, issues=results) + return AcceptanceCriteriaValidationResult(is_compliant=len(results) == 0, issues=results) ``` ## Quality Gate Checklist @@ -370,8 +369,8 @@ def validate_bdd_compliance(test_file: str) -> BddValidationResult: ### Post-TDD Gate - [ ] All test functions follow `test__should_` naming - [ ] All test files use `*_test.py` naming convention -- [ ] All test docstrings use proper Gherkin format with newlines -- [ ] UUID format required for all acceptance criteria +- [ ] All test docstrings use proper UUID format with newlines +- [ ] Given/When/Then structure required for acceptance criteria - [ ] Test coverage strategy is comprehensive ### Post-Implementation Gate @@ -395,7 +394,7 @@ def validate_bdd_compliance(test_file: str) -> BddValidationResult: ### Auto-Delegation Triggers When violations are detected: - **Object Calisthenics violations** → Auto-delegate to `@architect` -- **BDD format violations** → Auto-delegate to `@developer` +- **Acceptance criteria format violations** → Auto-delegate to `@developer` - **Naming convention violations** → Auto-delegate to `@developer` - **SOLID violations** → Auto-delegate to `@architect` - **Quality bypasses** → Auto-delegate to `@developer` diff --git a/.opencode/skills/tdd/SKILL.md b/.opencode/skills/tdd/SKILL.md index c982dc7..5ea38a8 100644 --- a/.opencode/skills/tdd/SKILL.md +++ b/.opencode/skills/tdd/SKILL.md @@ -68,13 +68,13 @@ def test_any_valid_name_provided_slugify_should_be_idempotent(name): For complete test patterns and guidelines, see: [Reference: Test Patterns](../reference/test-patterns.md) -## BDD Test Docstrings +## Acceptance Criteria Test Docstrings -All test functions must include Gherkin-style docstrings with UUID traceability. Each test maps to an acceptance criteria UUID from the feature specification. +All test functions must include acceptance criteria docstrings with UUID traceability. Each test maps to an acceptance criteria UUID from the feature specification. -### Required Format: UUID with Gherkin Steps +### Required Format: UUID with Acceptance Criteria Steps -The docstring format uses UUID from acceptance criteria followed by Gherkin steps with **mandatory newlines**: +The docstring format uses UUID from acceptance criteria followed by Given/When/Then steps with **mandatory newlines**: ```python def test_user_login_with_valid_credentials_should_grant_access(): @@ -99,7 +99,7 @@ python -c "import uuid; print(uuid.uuid4())" Each acceptance criteria gets a unique UUID, and tests reference that UUID for traceability. -### Why BDD Docstrings? +### Why Acceptance Criteria Docstrings? 1. **pytest-html**: The HTML report displays docstrings as test names, making it easy to understand what each test verifies 2. **Documentation**: Docstrings serve as living documentation of test intent @@ -135,12 +135,6 @@ def test_invalid_case(): """123e4567-e89b-12d3-a456-426614174000: Invalid scenario.""" ``` -### Why BDD Docstrings? - -1. **pytest-html**: The HTML report displays docstrings as test names, making it easy to understand what each test verifies -2. **Documentation**: Docstrings serve as living documentation of test intent -3. **Debugging**: When a test fails, the docstring immediately shows what scenario was being tested - ### Multi-line Scenarios For complex scenarios, use additional detail in each section: diff --git a/.opencode/skills/workflow-coordination/SKILL.md b/.opencode/skills/workflow-coordination/SKILL.md index dbc5497..1e73947 100644 --- a/.opencode/skills/workflow-coordination/SKILL.md +++ b/.opencode/skills/workflow-coordination/SKILL.md @@ -88,7 +88,7 @@ Phase 3: Architecture Analysis Phase 4: Test Development (TDD) ├── [ ] /skill prototype-script (if validation needed - optional) ├── [ ] Implement test bodies from manager-created signatures -├── [ ] Write BDD tests with UUID format: +├── [ ] Write acceptance criteria tests with UUID format: │ """[UUID]: [Test description]. │ │ Given: [Preconditions] @@ -106,7 +106,7 @@ Phase 4: Test Development (TDD) **QA Gate Checklist**: - [ ] All acceptance criteria have test coverage -- [ ] BDD docstrings use proper format with newlines +- [ ] Acceptance criteria docstrings use proper format with newlines - [ ] Test naming follows convention - [ ] File naming follows convention - [ ] Hypothesis used appropriately for pure functions diff --git a/AGENTS.md b/AGENTS.md index ffc0f4b..fa382c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,7 +40,7 @@ This project includes custom skills for OpenCode: - **feature-definition**: Define features with SOLID principles and clear requirements - **architectural-analysis**: Create technical architecture features that complement business features with system design and ADRs - **prototype-script**: Create quick validation scripts with real data capture -- **gherkin-validation**: Validate BDD docstrings with UUID format for traceability +- **acceptance-criteria-validation**: Validate acceptance criteria format with UUID traceability - **tdd**: Write comprehensive tests using TDD with pytest/hypothesis — includes decision guide for when to use plain TDD, Hypothesis (property-based), or Hypothesis stateful testing - **signature-design**: Design modern Python interfaces with protocols and type hints - **implementation**: Implement using TDD methodology with real prototype data @@ -128,7 +128,7 @@ Generated docs are in `docs/api/` - open `docs/api/index.html` to browse. ## Test Conventions -This project uses BDD-style tests with the following conventions: +This project uses acceptance criteria format with UUID traceability: ### Test File Naming @@ -140,7 +140,7 @@ Test filenames should follow _test.py def test__should_(): ... ``` -### BDD Docstrings +### Acceptance Criteria Format All test functions must have Given/When/Then docstrings: ```python def test_federation_created_should_have_active_status(): @@ -177,12 +177,12 @@ task test ``` ### Checking Test Compliance -- **pytest-html report**: `docs/tests/report.html` - BDD docstrings displayed +- **pytest-html report**: `docs/tests/report.html` - Acceptance criteria displayed - **Coverage report**: `docs/coverage/index.html` - View coverage by file ## Code Quality Standards -- **Linting**: ruff with Google style conventions (D205, D212, D415 disabled for test files to allow BDD docstrings) +- **Linting**: ruff with Google style conventions (D205, D212, D415 disabled for test files to allow acceptance criteria) - **Type Checking**: pyright - **Test Coverage**: Minimum 100% - **Python Version**: >=3.13 @@ -294,7 +294,7 @@ Then run `/init` to generate a fresh `AGENTS.md` based on your project's current **The @overseer agent enforces mandatory QA checkpoints with zero tolerance:** 1. After requirements gathering - completeness review 2. After architecture analysis - architectural soundness review -3. After TDD phase - test quality review (BDD docstrings, naming conventions) +3. After TDD phase - test quality review (acceptance criteria format, naming conventions) 4. After signature design - SOLID/DRY/KISS review 5. After implementation - Object Calisthenics compliance 6. Before feature completion - final approval diff --git a/README.md b/README.md index c7fba46..f467713 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ This template creates a production-ready Python project with: ### 🏗️ **Enterprise Architecture & Quality** - **SOLID principles** - Enforced through AI architecture reviews via OpenCode agents - **Object Calisthenics** - Clean, behavior-rich code patterns enforced by QA workflows -- **100% test coverage** - TDD workflows with BDD docstrings and property-based testing (Hypothesis) +- **100% test coverage** - TDD workflows with acceptance criteria docstrings and property-based testing (Hypothesis) - **Mutation testing** - mutmut integration for test quality validation - **Zero-config tooling** - UV, taskipy, Ruff, PyTest, Hypothesis, PyRight pre-configured @@ -116,7 +116,7 @@ Complex projects are developed across multiple AI sessions. `TODO.md` at the roo - **🎯 SOLID Principles** - Single responsibility, dependency inversion, clean interfaces - **🔧 Object Calisthenics** - No primitives, small classes, behavior-rich objects -- **🧪 TDD Testing** - BDD-style tests with Given/When/Then docstrings, 100% coverage requirement +- **🧪 TDD Testing** - Acceptance criteria format with Given/When/Then docstrings, 100% coverage requirement - **🔬 Property-Based Testing** - Hypothesis integration for robust edge case validation - **🧬 Mutation Testing** - mutmut for genetic algorithm-based test quality assurance - **⚡ Modern Toolchain** - UV, taskipy, Ruff, PyTest, Hypothesis, PyRight @@ -182,7 +182,7 @@ docker build -t your-project-name . # Build development image | **Package Management** | UV (blazing fast pip/poetry replacement) | | **Task Automation** | taskipy (configured in pyproject.toml) | | **Code Quality** | Ruff (linting + formatting), PyRight (type checking) | -| **Testing** | PyTest + Hypothesis (property-based testing), pytest-html (BDD reports) | +| **Testing** | PyTest + Hypothesis (property-based testing), pytest-html (acceptance criteria reports) | | **Mutation Testing** | mutmut (genetic algorithm-based mutation testing) | | **Coverage** | pytest-cov (100% coverage requirement) | | **AI Integration** | OpenCode agents and skills for development automation | @@ -196,7 +196,7 @@ docker build -t your-project-name . # Build development image - ✅ **Zero Linting Issues** - Ruff automated formatting and Google-style conventions - ✅ **Property-Based Testing** - Hypothesis integration for robust validation - ✅ **Mutation Testing** - mutmut for genetic algorithm-based test quality validation -- ✅ **BDD Test Style** - Given/When/Then docstrings with pytest-html reporting +- ✅ **Acceptance Criteria Format** - Given/When/Then docstrings with pytest-html reporting - ✅ **Architecture Compliance** - AI-enforced SOLID principles through OpenCode agents ## 🚀 Deployment Ready diff --git a/TODO.md b/TODO.md index ff67750..1638efe 100644 --- a/TODO.md +++ b/TODO.md @@ -50,7 +50,7 @@ When starting a new feature, copy these phases: - [ ] @developer implements test bodies from signatures - [ ] /skill prototype-script (if validation needed - optional) - [ ] Use @pytest.mark based on test content, hypothesis for pure functions -- [ ] Write BDD-style tests with Given/When/Then +- [ ] Write acceptance criteria tests with Given/When/Then - [ ] QA: @overseer reviews test quality ### Phase 5: Design & Signatures