feat(workflow): redesign PO scope process — v4 major (Gherkin-first, folder-per-feature, @id tracing) by nullhack · Pull Request #58 · nullhack/python-project-template

nullhack · 2026-04-16T07:14:30Z

Summary

Replace flat feature markdown docs with a folder-per-feature structure containing Gherkin .feature files and a discovery.md per feature
Introduce 4-phase scope model (project discovery → feature discovery → stories → criteria) with stakeholder interview protocol, INVEST gate, declarative Gherkin enforcement, and MoSCoW triage
Switch acceptance criteria from UUID markdown format to Gherkin @id:<8-char-hex> Examples with a stub-generator script (gen_test_stubs.py) that keeps test files in sync with .feature files

Breaking Changes

Folder structure: docs/features/<name>.md → docs/features/<state>/<name>/ (folder with discovery.md + *.feature files inside)
Test layout: tests/<name>_test.py flat → tests/features/<name>/<story-slug>_test.py + tests/unit/
AC format: UUID markdown criteria → Gherkin @id:<8-char-hex> Example blocks
Skills removed: extend-criteria deleted; gap handling absorbed into PO/reviewer roles inline
Skills merged: code-quality now redirects to verify (all quality checks consolidated)

Changes by File

New files

.opencode/skills/tdd/scripts/gen_test_stubs.py — stub generator that syncs pytest tests from .feature files
.opencode/skills/scope/discovery-template.md — per-feature blank discovery template (Status + Entities + Rules + Constraints + Questions)
docs/features/discovery.md — project-level discovery template (Status + Questions only)

Full rewrites

AGENTS.md — new folder structure, 4-phase scope, Gherkin format, 4 markers, gen-tests commands
.opencode/agents/product-owner.md — PO=AI agent, stakeholder=human, 4-phase workflow, gap handling table
.opencode/agents/developer.md — new paths, escalate gaps to PO, reviewer-checks-each-green-test cycle
.opencode/agents/reviewer.md — gap reporting table, @id format, adversarial verification
.opencode/skills/scope/SKILL.md — 4-phase guide with INVEST gate, declarative Gherkin rule, MoSCoW triage, Rules+Constraints sections
.opencode/skills/verify/SKILL.md — absorbed code-quality content, evidence-required rule, @id format
.opencode/skills/tdd/SKILL.md — gen-tests workflow, new function naming, no UUID in docstrings
.opencode/skills/implementation/SKILL.md — reviewer-per-green-test cycle, spec gap escalation
.opencode/skills/session-workflow/SKILL.md — folder-aware session start, @id:hex in TODO.md

Deleted

.opencode/skills/extend-criteria/SKILL.md

Updated

pyproject.toml — added gen-id and gen-tests taskipy tasks; added deprecated pytest marker
tests/conftest.py — auto-skip hook for @pytest.mark.deprecated
docs/academic_research.md — added entries feat(template): add AI-driven themed naming for releases #16-20 (Boehm Cost of Change, INVEST, Example Mapping, Declarative Gherkin, MoSCoW)
README.md, .opencode/skills/pr-management/SKILL.md, .opencode/skills/create-skill/SKILL.md — format updates

Testing

All 5 tests pass: uv run task test ✓ (100% coverage)
uv run task gen-tests runs cleanly
uv run task gen-id produces valid 8-char hex
uv run task lint — not run (docs-only changes; no source code modified)

Reviewer Notes

Legacy artifacts intentionally preserved in old format:

tests/version_test.py — old UUID docstring format, flat layout (reference implementation)
docs/features/completed/display-version.md — old flat markdown AC format (shipped feature, not migrated)

The setup-project.md agent was updated to reference either layout with a flexible note.

…le substitution coverage

@id

…rkin-first AC, and @id tracing - Replace flat feature .md docs with folder-per-feature structure - Add 4-phase scope model: project discovery, feature discovery, stories, criteria - Switch from UUID acceptance criteria to Gherkin @id:<8-char-hex> Examples - Add gen-tests and gen-id taskipy tasks; add gen_test_stubs.py script - Rewrite scope/SKILL.md with INVEST gate, declarative Gherkin rule, MoSCoW triage - Add Rules + Constraints sections to discovery template (Example Mapping layer) - Delete extend-criteria skill; absorb gap-handling into PO and reviewer roles - Absorb code-quality into verify/SKILL.md; leave code-quality as redirect - Rewrite developer.md, reviewer.md with new paths and escalation model - Add deprecated pytest marker with auto-skip conftest hook - Add 4 new academic research entries (INVEST, Example Mapping, Declarative Gherkin, MoSCoW) - Add Boehm Cost of Change Curve as research entry #16 BREAKING CHANGE: folder structure changed from flat docs/features/<name>.md to docs/features/<state>/<name>/ with .feature files inside; test layout changed from tests/ flat to tests/features/<name>/ + tests/unit/

…stitution checks - Replace root main.py with app/__main__.py as the single entry point - Update tests/version_test.py to import from app.__main__ and patch app.__main__ - Fix setup-project.md Step 3d: create __main__.py and delete main.py - Fix setup-project.md Step 3f: add grep verification after substitutions - Fix setup-project.md Step 4: replace smoke test with uv run task test-fast

@id

…lder structure Convert single prose file to the standard folder layout: - discovery.md with status, entities, rules, and constraints - version-retrieval.feature with @id:3f2a1b4c and @id:7a8b9c0d - verbosity-control.feature with @id:a1b2c3d4, @id:b2c3d4e5, @id:e5f6a7b8

- Phase 2: make entity-derivation + interview cycle explicit (pre-mortem before first round, iterate until stakeholder says baseline) - Feature Decomposition Threshold: >2 concerns OR >8 candidate Examples triggers mandatory split - Phase 4: replace soft 3-10 limit with concern-based split rule; note multiple .feature files per folder - Implementation cycle: add hard STOP/WAIT gates, one test at a time before any reviewer interaction - Reviewer per-test scope: code-design only (YAGNI/KISS/DRY/SOLID/ObjCal/patterns + semantic alignment); no lint/pyright/coverage - Quality tooling (lint, static-check, coverage) deferred to developer handoff only - Developer Quality Gate Priority Order added to AGENTS.md and implementation/SKILL.md - TODO.md: add Step 4 cycle-aware format with Cycle State + reviewer scope legend

…indentation - Replace 6 regexes + 3 brittle parsing functions with gherkin-official canonical parser (Cucumber project, actively maintained, single dep) - Fix textwrap.dedent bug causing Given/When/Then docstring lines to land at column 0 instead of 4-space indented in generated test stubs - Add gherkin-official>=39.0.0 to dev dependency group

@id

…kflow hardening - Fix YAGNI > KISS > DRY > SOLID > ObjCal > patterns order across all 8 files (developer.md, reviewer.md, implementation/SKILL.md, session-workflow/SKILL.md, verify/SKILL.md, AGENTS.md) - Add gen_todo.py merge-write script for TODO.md structural enforcement - Rewrite session-workflow, implementation, tdd, verify skills v2.1 with mandatory Cycle State, WIP check, prereq check, STOP/WAIT language, gen-tests --check - Add D6 global @id duplicate detection (WARNING + continue) to gen_test_stubs.py - Add gen-todo task to pyproject.toml

…fication - Add mandatory package verification step at architecture start (Step 2) to prevent code being created under wrong package name - Add Design Self-Declaration checklist to REFACTOR phase (per-test), covering YAGNI > KISS > DRY > SOLID > OC rules 1-9 with file:line evidence - Add SELF-DECLARE as explicit cycle phase between REFACTOR and REVIEWER - Replace compact 3-line reviewer template with structured claims-vs-verdict table so reviewer independently audits each declared rule - Strip Self-Verification Before Handoff to quality tooling only — declaration already done per-test; no duplication at handoff - Add imports-use-correct-package-name check to verify/SKILL.md section 4g - Update Scope Guard in verify/SKILL.md to reference self-declaration flow - Bump both skills to v2.2

… gen_todo path

…table

… fix lint errors in scripts

…test-fast

…r setup substitutions - Replace project_defaults.json with template-config.yaml (YAML, declarative substitution map) - Fix stale Dockerfile references: python_package_template.python_module_template → app - Fix stale docker-compose.yml references: python_package_template → app - Update setup-project.md to read template-config.yaml instead of project_defaults.json - Agent now follows the substitution map directly, no implicit knowledge of patterns needed

nullhack added 15 commits April 15, 2026 10:16

chore(setup-agent): enforce defaults-driven prompting and complete fi…

ecc92e1

…le substitution coverage

feat(gen-id): generate 20 IDs at once instead of one

a818f0b

fix(workflow): sync SELF-DECLARE phase, reviewer Step 4 protocol, and…

941d865

… gen_todo path

fix(workflow): remove migration language from code-quality skill and …

f635e75

…table

docs(post-mortem): add two ping-pong-cli post-mortem reports

c658419

refactor(template): simplify app code, add unit test with Hypothesis,…

1f9dded

… fix lint errors in scripts

fix(template): remove @slow marker from template test — collected by …

3963f33

…test-fast

nullhack merged commit 36c7820 into main Apr 16, 2026
9 checks passed

nullhack deleted the feat/po-workflow-redesign-v4 branch April 16, 2026 15:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(workflow): redesign PO scope process — v4 major (Gherkin-first, folder-per-feature, @id tracing)#58

feat(workflow): redesign PO scope process — v4 major (Gherkin-first, folder-per-feature, @id tracing)#58
nullhack merged 15 commits intomainfrom
feat/po-workflow-redesign-v4

nullhack commented Apr 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

nullhack commented Apr 16, 2026

Summary

Breaking Changes

Changes by File

New files

Full rewrites

Deleted

Updated

Testing

Reviewer Notes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant