All notable changes to this template will be documented in this file.
- Per-test Design Self-Declaration: After REFACTOR, developer fills a 20-item checklist (YAGNI → KISS → DRY → SOLID-S/O/L/I/D → OC rules 1–9) with
file:lineevidence before requesting reviewer check; reviewer independently audits claims using an 11-row comparison table (#58) - Package Verification step: Mandatory before writing any code — read
pyproject.toml → [tool.setuptools] packages, confirm directory exists on disk; hard stop if missing (#58) - SELF-DECLARE phase: New phase added to the Red-Green-Refactor cycle between REFACTOR and REVIEWER; Cycle State now
RED | GREEN | REFACTOR | SELF-DECLARE | REVIEWER(code-design) | COMMITTED(#58) - template-config.yaml: Declarative single source of truth for all setup-project substitutions —
defaults:block with 6 parameters,substitutions:map with literalold:strings,{variable}new:patterns, and expectedcount:per file (#58) - Post-mortem docs: Two ping-pong-cli post-mortems documenting the systemic failures that drove this release (#58)
- verify/SKILL.md Scope Guard: Reviewer receives completed Design Self-Declaration and independently verifies each claim; responds using structured 11-row comparison table (#58)
- verify/SKILL.md section 4g: New row —
Imports use correct package name(check imports match[tool.setuptools] packages); existing rows made more precise withpyproject.tomlreferences (#58) - reviewer.md per-test Step 4 section: Rewritten to reference
skill implementationverification table; clarifies no commands run during Step 4 reviews (#58) - reviewer.md Zero-Tolerance Rule 1: Scoped to
(Step 5 only — per-test Step 4 checks are code-design only, no commands)(#58) - setup-project.md: Reads
template-config.yaml; each apply step delegates to the config map rather than carrying implicit pattern knowledge (#58) - Template app simplified:
app/version.pydeleted;app/__main__.pyreduced from 41 to 23 lines (#58)
- gen_todo.py path:
parents[5]→parents[4]— was resolving one directory above the project root (#58) - session-workflow Cycle State:
SELF-DECLAREphase added to documented phase list and Rule 6 (#58) - code-quality/SKILL.md: Removed "has been absorbed" migration language (#58)
- Dockerfile stale references:
python_package_template.python_module_template→appin HEALTHCHECK and CMD (#58) - docker-compose.yml stale references:
python_package_template→appin volume mounts and command (#58)
project_defaults.jsondeleted — replaced bytemplate-config.yaml(#58)app/version.pyandtests/version_test.pydeleted — template app simplified to minimal__main__.py+ one Hypothesis unit test (#58)
- Adversarial verification mandate: Reviewer's default hypothesis is now "the code is broken despite green checks" — job is to find the failure mode, not confirm it works (#54)
- Production-grade gate: New step 3 in verification — app must exit cleanly AND output must change when input changes; static output regardless of input = REJECTED (#54)
- UUID Drift bash check: One-liner detects duplicate UUIDs across test functions; any duplicate = REJECTED with fix instructions (#54)
- docs/academic_research.md: 15 cognitive and social science mechanisms with full citations grounding every workflow design decision (pre-mortem, implementation intentions, adversarial collaboration, elaborative encoding, and 11 more) (#54)
- Design pattern decision table: Added to
developer.mdandimplementation/SKILL.md; any detected anti-pattern = REJECTED (#54) - Architecture contradiction check: Developer must cross-check ADRs against ACs before writing production code (#54)
- PO pre-mortem: Added at scope step and acceptance step (#54)
- Semantic alignment rule: Tests must operate at same abstraction level as AC (#54)
- Integration test requirement: Multi-component features require at least one integration test through the public entry point (#54)
- Verification Philosophy section: Added to AGENTS.md — automated checks verify syntax-level correctness; human review verifies semantic-level correctness; both required (#54)
- Verification order: Code review before automated commands; run app first as production-grade gate (#54)
- All review sections converted to tables: Correctness, KISS, SOLID, ObjCal, Design Patterns, Tests, Versions/Build all have PASS/FAIL/Fix columns (#54)
- UUID Uniqueness rule: If only Given varies it is a property — use Hypothesis
@given+@example, not multiple test functions; if When/Then differs useextend-criteria(#54) - Production-grade self-check in implementation: Developer must verify output changes with input before handoff (#54)
- extend-criteria skill: New skill for any agent to add acceptance criteria discovered mid-flight or post-merge, with decision rule (gap within scope vs. new feature), per-role procedures, and commit protocol
- Source: field on acceptance criteria: Mandatory traceability field on every criterion (
stakeholder | po | developer | reviewer | bug) — records who originated the requirement
- Test function naming:
test_<short_title>replacestest_<condition>_should_<outcome> - Test docstring first line: UUID only (no trailing description) —
"""<uuid>\n\nGiven: ... - development commands: All skill and agent files now use
uv run taskconsistently (not baretask) - tests/ layout: Documented as flat (no unit/ or integration/ subdirectories)
- pytest.skip prohibition: Aligned across files — allowed with written justification in the docstring
- Marker decision table: Moved to tdd/SKILL.md only (developer's decision, not PO's)
- mv to in-progress: Ownership reassigned to developer Step 2 (not PO scope step)
- TODO.md status markers: Added
[~](in progress) and[-](cancelled) to documented legend - --doctest-modules: Documented in implementation/SKILL.md (task test runs doctest modules)
- verify/SKILL.md: Report template uses flat
tests/<file>:<function>path format - exit code wording:
exit non-124(was ambiguousexit 0 or 124) in developer.md - README.md:
uv sync --all-extrasanduv run taskcommands throughout
- Removed stale
docs/features/in-progress/auto-publish-docs.md - Split compound acceptance criterion (two outcomes in one Then) into two single-outcome criteria
- Added
@pytest.mark.slowto Hypothesis tests in reference implementation - Added
# Given / # When / # Thenbody comments to all reference tests - Removed duplicate assertion from
test_version_logs_correct_message - Moved
StringIOimport from test body to module-level imports
- Workflow redesigned: 8-phase/6-role system replaced with 6-step/3-role (Product Owner, Developer, Reviewer)
- Roles removed: architect, manager, repo-manager, requirements-gatherer, overseer agents deleted
- Feature directories restructured:
docs/features/{business,architecture}/replaced with flatdocs/features/{backlog,in-progress,completed}/
- product-owner agent: Defines scope, acceptance criteria, picks features, accepts deliveries (Steps 1 + 6)
- reviewer agent: Read+bash only, runs all commands, produces APPROVED/REJECTED report (Step 5)
- scope skill: PO guide for writing user stories + UUID acceptance criteria
- verify skill: Reviewer guide for running commands and code review checklist
- Unified docs site:
docs/index.htmllanding page linking to API Reference, Coverage, Test Results - ghp-import: One-liner
task doc-publishreplaces complex inline Python
- developer agent: Owns all of Steps 2-4+6 including architecture, tests, code, and release
- 9 skills rewritten: session-workflow, tdd, implementation, code-quality, pr-management, git-release, create-skill (lean, <150 lines each)
- Test markers reduced: from 11 (with duplicate) to 3:
unit,integration,slow - doc-build: Now generates all three outputs (pdoc API + pytest-cov HTML + pytest-html)
- CI workflow: Cleaned up to use
uv run task <name>consistently - setup-project agent: No longer uses setup_project.py; agent applies changes directly
- 11 skills deleted (architectural-analysis, delegation-coordination, epic-workflow, feature-definition, qa-enforcement, requirements-management, signature-design, workflow-coordination, prototype-script, create-agent, reference/)
setup_project.pyscript and.opencode/templates/directory- Wrong
dotenvdependency (replaced nothing — was unused) mutmutdev dependency (YAGNI)
- Architecture-First Feature System - New directory structure separating business and architecture features
- Architectural Analysis Skill - Systematic architecture documentation for each feature
- 8-Phase Development Cycle - Expanded from 7-phase with dedicated Architecture Analysis phase
- BDD → Acceptance Criteria - Renamed gherkin-validation to acceptance-criteria-validation for accurate terminology
- Consistency Updates - Fixed phase numbering, cross-references, and documentation across all agents and skills
- Epic-Workflow Refactor - Converted from epic-based to feature-selection with architecture-first priority
- Manager Agent - Enhanced with test signature creation capabilities
- No breaking changes in this release
- Projects can continue using existing workflow
- Docker simplification and cleanup
- V2 Development Workflow with CI/CD fixes
- Template refactoring for generic app package
- Enhanced QA enforcement skills
- Complexity fixes for CI compliance
- CodeQL config conflict resolved
This represents a fundamental architectural shift from V1 (template validation workflows) to V2 (project development workflows).
- Workflow Architecture: Complete transition from template validation (V1) to project development (V2)
- CI/CD Pipeline: New comprehensive GitHub Actions workflow replacing template-specific workflows
- Branch Structure: V2/init becomes the new development foundation
- Agent Configuration: Updated agent roles and capabilities for project development
- Enhanced GitHub Actions workflow security with proper permissions blocks
- Removed risky PIP_USER environment variable from CI/CD pipeline
- Added secure error handling to shell scripts with 'set -euo pipefail'
- Implemented job-level permissions for all CI workflow operations
- Modernized Docker setup with security-first containerization approach
- Comprehensive CI/CD pipeline with GitHub Actions integration
- Improved workflow security following GitHub Advanced Security recommendations
- Full project development workflow implementation
- Complete project-focused development environment
- Better error handling and security practices in automation
- Enhanced development workflow with secure defaults
- Improved CI/CD reliability and security posture
- BREAKING: This is a major version requiring migration from V1 template workflows
- V1 template validation workflows are replaced by V2 project development workflows
- Projects using V1 should plan migration to V2 architecture
- All security improvements follow GitHub security best practices
- QA-gated Epic Workflow - Complete epic-based development with mandatory quality checkpoints at each phase
- Epic-workflow Skill - Manages epic-based development with automatic feature progression
- EPICS.md Template - Epic tracking and management file for generated projects
- Updated all agent descriptions to use industry-standard roles (Development Lead, Software Architect, QA Specialist, Business Analyst, Release Engineer)
- Removed model specifications from all agents to make template model-agnostic
- Updated AGENTS.md to properly document all 5 generated project agents and all skills
- Updated README.md with new workflow and agent roles
- Documentation now accurately reflects what exists in template
- Overseer Agent - Quality assurance agent that reviews work after each test implementation and requests changes if needed
- Requirements Gatherer Agent - Agent that asks questions to understand project needs, updates documentation, creates detailed analysis for architect
- Updated developer workflow to include
@overseercalls after Phase 3 (TDD tests) and Phase 7 (Quality Assurance) - Updated AGENTS.md with new agents and updated workflow examples
- AI-Enhanced Development Workflow - Complete OpenCode integration for AI-powered development
- 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
- Repository Skills - git-release (hybrid calver versioning with themed releases), pr-management
- Meta Skills - create-skill, create-agent for extending OpenCode
- Template Management - template-manager agent, template-test, template-release skills
- Comprehensive CI Workflow - Template validation, generated project tests, Docker builds
- Validation Scripts - cookiecutter.json, pyproject.toml, YAML frontmatter validation
- Updated README.md with modern AI-focused branding
- Updated generated project README template with AI development workflow
- 7-Phase Development Cycle: Feature Definition → Prototype → TDD → Signature Design → Architecture Review → Implementation → Quality Assurance
- SOLID Principles Enforcement - Single responsibility, dependency inversion, interface segregation
- Object Calisthenics - No primitives, small classes, behavior-rich objects
- Hybrid Calver Versioning: v1.2.20260302 format with themed releases
- Themed Release Names: "Swift Cheetah", "Vigilant Owl", "Creative Fox" based on PR sentiment
- Property-Based Testing: Hypothesis integration for robust test coverage
- This is the first semantic version release
- No breaking changes to cookiecutter.json structure
- Generated projects now include OpenCode agents and skills
- Existing projects can regenerate to get new features