From 45e67e8ba62af74e2c6f540563cc06218300ea1b Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:07:55 +0200 Subject: [PATCH 01/11] Add SDD upgrade ticket set --- docs/sdd_article_integration_evaluation.md | 60 +++++ tickets/sdd-upgrade/README.md | 22 ++ .../TKT-2026-06-09-conditional-steering.yaml | 143 +++++++++++ ...26-06-09-decision-lock-context-budget.yaml | 142 +++++++++++ .../TKT-2026-06-09-delta-spec-lifecycle.yaml | 140 +++++++++++ ...KT-2026-06-09-expert-routing-profiles.yaml | 149 ++++++++++++ .../TKT-2026-06-09-quick-flow-escalation.yaml | 143 +++++++++++ ...6-09-readme-terminology-version-0-4-0.yaml | 147 ++++++++++++ ...T-2026-06-09-sdd-upgrade-orchestrator.yaml | 227 ++++++++++++++++++ .../TKT-2026-06-09-spec-artifact-package.yaml | 147 ++++++++++++ .../TKT-2026-06-09-spec-drift-verifier.yaml | 139 +++++++++++ 11 files changed, 1459 insertions(+) create mode 100644 docs/sdd_article_integration_evaluation.md create mode 100644 tickets/sdd-upgrade/README.md create mode 100644 tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml create mode 100644 tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml create mode 100644 tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml create mode 100644 tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml create mode 100644 tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml create mode 100644 tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml create mode 100644 tickets/sdd-upgrade/TKT-2026-06-09-sdd-upgrade-orchestrator.yaml create mode 100644 tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml create mode 100644 tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml diff --git a/docs/sdd_article_integration_evaluation.md b/docs/sdd_article_integration_evaluation.md new file mode 100644 index 0000000..d50d529 --- /dev/null +++ b/docs/sdd_article_integration_evaluation.md @@ -0,0 +1,60 @@ +# SDD Article Integration Evaluation + +Date: 2026-06-09 +Current template version inspected: 0.3.0 +Proposed target version for the SDD upgrade: 0.4.0 + +## Verdict + +The existing workflow is already a strong guarded agentic-engineering baseline: it has role separation, scoped tickets, fresh worker contexts, explicit proof gates, no-bulk-staging, stop conditions, and closeout memory. The most useful additions from the article are not another large agent framework, but a thin SDD layer that turns ticket context into explicit, traceable specs. + +## Already covered well + +- Existing expert-team pattern: `manager-orchestrator`, `scoped worker`, `read-only reviewer`, and `final verifier`, plus `expert_supported` and `bounded_expert_rounds` execution modes. +- Fresh-context execution for bounded tickets. +- Explicit allowed_files / forbidden_files. +- Proof gates, regression gates, visual gate, and closeout. +- Agent memory under `agent/*.md`. +- Approval boundaries for dependencies, secrets, destructive commands, remotes, releases, and deployments. + +## High-value additions to automate + +1. **Expert routing profiles**: keep the existing expert-team model, but let the manager select specific read-only reviewer profiles by ticket type, file patterns, risk, and proof needs. +2. **Spec artifact package**: add requirements/design/tasks templates so tickets do not carry all requirements alone. +3. **Delta-spec lifecycle**: keep durable specs current through ADDED/MODIFIED/REMOVED changes and archive/merge closeout. +4. **Spec drift verifier**: make final verification compare spec, code, tests, docs, and ticket result. +5. **Conditional steering**: load specialized guidance only when matching files/tasks require it, while keeping core safety rules always loaded. +6. **Quick-flow with escalation**: support tiny safe tasks without turning them into vibe coding. +7. **Decision locks + context budgets**: resolve grey areas before implementation and keep worker context small and intentional. +8. **README/version terminology update**: align public docs and VERSION with the SDD release line. + +## Deliberately not recommended as default + +- A second full BMAD-style simulated agile team with many personas: the workflow already has an expert-team pattern. The useful improvement is routing/specialization of the existing read-only experts, not duplicating them with ceremony. +- Proprietary IDE dependency: Kiro concepts are useful, but this template should stay portable. +- Spec-as-Source as the default maturity level: too strong for a pre-1.0 workflow; Spec-first plus Spec-anchored is the safer next step. +- Unbounded parallel implementation agents: keep the existing serial scoped-worker default unless write scopes are provably disjoint. + +## Ticket set created + +- `tickets/sdd-upgrade/TKT-2026-06-09-sdd-upgrade-orchestrator.yaml` +- `tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml` +- `tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml` +- `tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml` +- `tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml` +- `tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml` +- `tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml` +- `tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml` +- `tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml` + +## Recommended implementation order + +1. Expert routing profiles for the existing expert-team pattern. +2. Spec artifact package. +3. Delta-spec lifecycle. +4. Spec drift verifier. +5. Conditional steering. +6. Quick-flow escalation. +7. Decision locks and context budget. +8. README/version/changelog update to 0.4.0. +9. Final verification through the orchestrator ticket. diff --git a/tickets/sdd-upgrade/README.md b/tickets/sdd-upgrade/README.md new file mode 100644 index 0000000..1537e1e --- /dev/null +++ b/tickets/sdd-upgrade/README.md @@ -0,0 +1,22 @@ +# SDD Upgrade Ticket Index + +Created: 2026-06-09 +Target version: 0.4.0 + +These tickets turn the existing Codex-first workflow template into a Spec-driven Development capable workflow while preserving the current safety model. + +## Tickets + +1. `TKT-2026-06-09-sdd-upgrade-orchestrator.yaml` — parent ticket for the whole SDD upgrade. +2. `TKT-2026-06-09-expert-routing-profiles.yaml` — specialize the existing read-only expert-team workflow with routing profiles. +3. `TKT-2026-06-09-spec-artifact-package.yaml` — add requirements/design/tasks spec artifacts. +4. `TKT-2026-06-09-delta-spec-lifecycle.yaml` — add Spec-anchored delta-spec lifecycle. +5. `TKT-2026-06-09-spec-drift-verifier.yaml` — add cross-artifact spec drift verification. +6. `TKT-2026-06-09-conditional-steering.yaml` — add conditional context/steering files. +7. `TKT-2026-06-09-quick-flow-escalation.yaml` — add small-task quick-flow with escalation rules. +8. `TKT-2026-06-09-decision-lock-context-budget.yaml` — add grey-area decision locks and context-budget controls. +9. `TKT-2026-06-09-readme-terminology-version-0-4-0.yaml` — update README, VERSION, and changelog to 0.4.0 after the SDD changes land. + +## Manager note + +Run the README/version ticket last. Until the implementation tickets are complete, `VERSION` should remain `0.3.0` in the source tree; the ticket defines the intended bump to `0.4.0`. diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml new file mode 100644 index 0000000..47add36 --- /dev/null +++ b/tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml @@ -0,0 +1,143 @@ +schema_version: 2 +ticket: + id: TKT-2026-06-09-conditional-steering + title: Add conditional steering files to reduce context noise + repo: agentic-engineering-workflow-template + branch: main + status: backlog + created_at: '2026-06-09' + owner_agent: manager + ticket_class: implementation + work_kind: feature + phase: sdd-upgrade-v0.4.0 + target_version: 0.4.0 +context: + problem: AGENTS.md and agent/*.md are always loaded. As repos grow, always-on context can become noisy. + The article highlights Kiro-style steering modes; the workflow can adopt the useful idea without depending + on Kiro. + current_behavior: Required read order loads AGENTS.md and all agent memory files before planning/implementation. + There is no first-class way to load specialized rules only for matching files, technologies, security + domains, or manual references. + desired_behavior: 'The template supports optional steering documents with inclusion metadata: always, + fileMatch, manual, and auto-like description matching. The manager builds a bounded context pack from + ticket allowed_files and requested task.' + relevant_prior_work: + - 'User-provided iX article: Fünf Tools für Spec-driven Development im Überblick, 2026-06-08' + - README.md + - docs/workflow.md + - templates/AGENTS.md.template +scope: + goal: Introduce conditional steering templates and update read-order rules so only relevant specialized + context is loaded. + allowed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml + - templates/steering/** + - templates/AGENTS.md.template + - docs/workflow.md + - prompts/initialize-repo.md + - prompts/manager-orchestrator.md + - prompts/scoped-worker.md + - checklists/ticket-readiness.md + forbidden_files: + - .env + - .env.* + - node_modules/** + - dist/** + - build/** + - .next/** + - coverage/** + in_scope: + - Add templates/steering/product.md, tech.md, structure.md, testing.md, security.md examples with YAML + front matter. + - 'Define inclusion modes in template-neutral language: always, fileMatch, manual, auto.' + - 'Update AGENTS read order: always steering first; fileMatch steering based on allowed_files; manual/auto + steering only when referenced or matched by task description.' + - Add ticket field context_pack.required_steering_files and context_pack.excluded_context. + - Update initialization prompt to generate starter steering docs only from repo evidence and mark unknowns. + out_of_scope: + - Do not require Kiro IDE. + - Do not remove AGENTS.md. + - Do not load private/global machine paths or secrets into steering files. +execution: + execution_intensity: expert_supported + manager_role: Main Codex agent owns scope, verifies the work, and records proof in this ticket. Any + Codex subagent inherits AGENTS.md, the active ticket scope, approval boundaries, forbidden actions, + and verification requirements. + worker_sequence: + - role: read_only_reviewer + mode: read_only + task: Review the planned workflow/template changes for SDD usefulness, risk, and minimality before + edits. + - role: scoped_worker + mode: implementation + task: Implement only the scoped workflow/template change described in this ticket. + expert_plan: + required: true + planning_reviewer: read-only Codex reviewer + reviewer: final verifier + record_location: execution_result + debug_logging_plan: + owner: scoped_worker + surfaces: + - YAML parse output + - Markdown link/path inspection + - grep output for version and old terminology + temporary_logging_policy: Do not add temporary logs to template files; record command output only + in ticket execution_result. + test_plan: + - Parse every changed YAML file with python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) + for p in pathlib.Path('.').rglob('*.yaml')]". + - Run markdown/path consistency checks manually or with grep for all newly referenced template paths. + - Check whether README, docs/workflow.md, AGENTS template, prompts, checklists, ticket templates, and + agent memory files need updates and record the result. + proof_gates: + - Changed templates and tickets are internally consistent and parseable where applicable. + - The workflow change is bounded to SDD/context-engineering support and does not alter product runtime + assumptions. + - Agent-memory update check is recorded. + - Ticket result records changed files, commands, proof, skipped checks, blockers, and risks. + - Specialized guidance can be included without bloating every worker context. + - Steering templates contain no product-specific fake values and use unknown placeholders. + - Ticket readiness confirms required steering files are explicit when specialized rules apply. + regression_gates: + - No unrelated files changed. + - No secrets, credentials, or private local paths are introduced. + - No dependency installation, destructive cleanup, remote operation, release, deploy, or external-service + action occurs without explicit approval. + - Existing Codex scoped-worker/orchestrator safety boundaries remain stricter or equivalent after the + change. + visual_gate: + required: false + required_views: [] + pass_rule: Not required; this is a workflow/template change. + checkpoint_policy: Create a scoped checkpoint commit only after proof passes or after explicit user + approval. + rollback_or_accept_policy: If the scoped change makes the workflow ambiguous or less safe, keep the + ticket non-done, record the blocker, and propose a smaller follow-up ticket. + stop_conditions: + - The change would require product-repository assumptions that are not available in the template source. + - The change requires editing forbidden files. + - The design would weaken approval boundaries, proof gates, or scoped file ownership. + - The work requires dependency installation, destructive commands, remote operations, deployment, release, + secrets, migrations with side effects, network-dependent setup, or scope expansion without explicit + approval. + handoff_requirements: + - Record changed files, commands run, proof result, skipped checks, blockers, risks, agent updates, + and next action. + done_definition: Done when the scoped workflow/template improvement is implemented, required proof has + passed or justified skips are recorded, and execution_result is complete. +execution_result: + status: pending + changed_files: [] + commands_run: [] + proof: [] + skipped_checks: [] + agent_memory_updates: + checked: false + updated_files: [] + notes: null + blockers: [] + risks: + - 'Risk: auto-like steering could hide important rules; mitigate by keeping security/core standards + always loaded.' + next_recommended_step: null diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml new file mode 100644 index 0000000..290b7e1 --- /dev/null +++ b/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml @@ -0,0 +1,142 @@ +schema_version: 2 +ticket: + id: TKT-2026-06-09-decision-lock-context-budget + title: Add grey-area decision locks and context-budget controls + repo: agentic-engineering-workflow-template + branch: main + status: backlog + created_at: '2026-06-09' + owner_agent: manager + ticket_class: implementation + work_kind: refactor + phase: sdd-upgrade-v0.4.0 + target_version: 0.4.0 +context: + problem: The workflow already uses fresh worker contexts, but it does not explicitly force unresolved + implementation grey areas to be locked before planning, nor does it track how much context a worker + is allowed to receive. + current_behavior: Tickets can include context and stop conditions. agent/DECISIONS.md records durable + decisions, but there is no required locked_decisions block or context_budget/context_pack contract. + desired_behavior: Before implementation, the manager identifies grey areas, asks for or records decisions, + and gives each worker a bounded context pack. Workers stop if decisions are missing or context requirements + exceed budget. + relevant_prior_work: + - 'User-provided iX article: Fünf Tools für Spec-driven Development im Überblick, 2026-06-08' + - README.md + - docs/workflow.md + - templates/AGENTS.md.template +scope: + goal: Add locked decisions and context-budget fields to ticket/orchestrator templates and prompts. + allowed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - templates/AGENTS.md.template + - prompts/manager-orchestrator.md + - prompts/scoped-worker.md + - checklists/ticket-readiness.md + - agent/DECISIONS.md + - docs/workflow.md + forbidden_files: + - .env + - .env.* + - node_modules/** + - dist/** + - build/** + - .next/** + - coverage/** + in_scope: + - Add context_pack with required_files, required_specs, required_steering_files, excluded_context, and + summary_budget. + - Add locked_decisions with decision, rationale, owner, source, and expiry/change rule. + - Update manager prompt to identify grey areas before planning and either resolve them or create a research_only + decision ticket. + - Update scoped-worker prompt to stop when a required decision or context pack item is missing. + - Update DECISIONS.md template to support durable decision locks without storing one-off noise. + out_of_scope: + - Do not implement parallel wave execution in this ticket. + - Do not require atomic commits for every task; keep commits controlled by existing commit policy. + - Do not store private local paths, credentials, or chat dumps in context packs. +execution: + execution_intensity: expert_supported + manager_role: Main Codex agent owns scope, verifies the work, and records proof in this ticket. Any + Codex subagent inherits AGENTS.md, the active ticket scope, approval boundaries, forbidden actions, + and verification requirements. + worker_sequence: + - role: read_only_reviewer + mode: read_only + task: Review the planned workflow/template changes for SDD usefulness, risk, and minimality before + edits. + - role: scoped_worker + mode: implementation + task: Implement only the scoped workflow/template change described in this ticket. + expert_plan: + required: true + planning_reviewer: read-only Codex reviewer + reviewer: final verifier + record_location: execution_result + debug_logging_plan: + owner: scoped_worker + surfaces: + - YAML parse output + - Markdown link/path inspection + - grep output for version and old terminology + temporary_logging_policy: Do not add temporary logs to template files; record command output only + in ticket execution_result. + test_plan: + - Parse every changed YAML file with python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) + for p in pathlib.Path('.').rglob('*.yaml')]". + - Run markdown/path consistency checks manually or with grep for all newly referenced template paths. + - Check whether README, docs/workflow.md, AGENTS template, prompts, checklists, ticket templates, and + agent memory files need updates and record the result. + proof_gates: + - Changed templates and tickets are internally consistent and parseable where applicable. + - The workflow change is bounded to SDD/context-engineering support and does not alter product runtime + assumptions. + - Agent-memory update check is recorded. + - Ticket result records changed files, commands, proof, skipped checks, blockers, and risks. + - 'Ticket readiness requires grey-area status: none, resolved, or blocked.' + - Worker prompt has a clear stop rule for missing decisions/context. + - Context pack avoids dumping the whole repo into every worker context. + regression_gates: + - No unrelated files changed. + - No secrets, credentials, or private local paths are introduced. + - No dependency installation, destructive cleanup, remote operation, release, deploy, or external-service + action occurs without explicit approval. + - Existing Codex scoped-worker/orchestrator safety boundaries remain stricter or equivalent after the + change. + visual_gate: + required: false + required_views: [] + pass_rule: Not required; this is a workflow/template change. + checkpoint_policy: Create a scoped checkpoint commit only after proof passes or after explicit user + approval. + rollback_or_accept_policy: If the scoped change makes the workflow ambiguous or less safe, keep the + ticket non-done, record the blocker, and propose a smaller follow-up ticket. + stop_conditions: + - The change would require product-repository assumptions that are not available in the template source. + - The change requires editing forbidden files. + - The design would weaken approval boundaries, proof gates, or scoped file ownership. + - The work requires dependency installation, destructive commands, remote operations, deployment, release, + secrets, migrations with side effects, network-dependent setup, or scope expansion without explicit + approval. + handoff_requirements: + - Record changed files, commands run, proof result, skipped checks, blockers, risks, agent updates, + and next action. + done_definition: Done when the scoped workflow/template improvement is implemented, required proof has + passed or justified skips are recorded, and execution_result is complete. +execution_result: + status: pending + changed_files: [] + commands_run: [] + proof: [] + skipped_checks: [] + agent_memory_updates: + checked: false + updated_files: [] + notes: null + blockers: [] + risks: + - 'Risk: too much ceremony for obvious tickets; mitigate by allowing grey_areas: none with proof from + discovery.' + next_recommended_step: null diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml new file mode 100644 index 0000000..e3d1602 --- /dev/null +++ b/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml @@ -0,0 +1,140 @@ +schema_version: 2 +ticket: + id: TKT-2026-06-09-delta-spec-lifecycle + title: Add OpenSpec-style delta-spec lifecycle for ongoing changes + repo: agentic-engineering-workflow-template + branch: main + status: backlog + created_at: '2026-06-09' + owner_agent: manager + ticket_class: implementation + work_kind: feature + phase: sdd-upgrade-v0.4.0 + target_version: 0.4.0 +context: + problem: 'The workflow is currently closer to Spec-first: tickets and docs can be created up front, + but there is no formal mechanism to keep durable specs current after implementation. That invites + Spec Drift on long-lived projects.' + current_behavior: agent/*.md and tickets preserve memory, but no current spec tree, change folder, archive + step, or ADDED/MODIFIED/REMOVED format exists. + desired_behavior: 'The template supports Spec-anchored maintenance: each significant change gets a delta-spec + folder, and closeout either merges/archives that delta into durable specs or records why it is deferred.' + relevant_prior_work: + - 'User-provided iX article: Fünf Tools für Spec-driven Development im Überblick, 2026-06-08' + - README.md + - docs/workflow.md + - templates/AGENTS.md.template +scope: + goal: Introduce a lightweight delta-spec lifecycle with current specs, change specs, and archive rules. + allowed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml + - templates/specs/** + - docs/spec_lifecycle.md + - docs/workflow.md + - templates/AGENTS.md.template + - checklists/closeout.md + - prompts/final-verifier.md + forbidden_files: + - .env + - .env.* + - node_modules/** + - dist/** + - build/** + - .next/** + - coverage/** + in_scope: + - Add templates/specs/TEMPLATE.delta-spec.md or .yaml using ADDED, MODIFIED, REMOVED sections. + - 'Document suggested target layout: specs/current/**, specs/changes//{proposal.md,delta-spec.md,design.md,tasks.md}, + specs/archive/**.' + - Update closeout so significant behavior changes must archive/merge the delta spec or record a deferred + spec update blocker. + - Add conflict rule for parallel changes touching the same current spec. + - Add proof gate that the final verifier checks implementation against the delta-spec intent and current + spec update. + out_of_scope: + - Do not build a CLI. + - Do not require Node/OpenSpec installation. + - Do not turn all work into Spec-as-Source where humans never edit code. +execution: + execution_intensity: expert_supported + manager_role: Main Codex agent owns scope, verifies the work, and records proof in this ticket. Any + Codex subagent inherits AGENTS.md, the active ticket scope, approval boundaries, forbidden actions, + and verification requirements. + worker_sequence: + - role: read_only_reviewer + mode: read_only + task: Review the planned workflow/template changes for SDD usefulness, risk, and minimality before + edits. + - role: scoped_worker + mode: implementation + task: Implement only the scoped workflow/template change described in this ticket. + expert_plan: + required: true + planning_reviewer: read-only Codex reviewer + reviewer: final verifier + record_location: execution_result + debug_logging_plan: + owner: scoped_worker + surfaces: + - YAML parse output + - Markdown link/path inspection + - grep output for version and old terminology + temporary_logging_policy: Do not add temporary logs to template files; record command output only + in ticket execution_result. + test_plan: + - Parse every changed YAML file with python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) + for p in pathlib.Path('.').rglob('*.yaml')]". + - Run markdown/path consistency checks manually or with grep for all newly referenced template paths. + - Check whether README, docs/workflow.md, AGENTS template, prompts, checklists, ticket templates, and + agent memory files need updates and record the result. + proof_gates: + - Changed templates and tickets are internally consistent and parseable where applicable. + - The workflow change is bounded to SDD/context-engineering support and does not alter product runtime + assumptions. + - Agent-memory update check is recorded. + - Ticket result records changed files, commands, proof, skipped checks, blockers, and risks. + - docs/spec_lifecycle.md explains propose/apply/archive in repo-local terms. + - Closeout checklist contains a spec archive/update check. + - Final verifier checks current spec alignment or deferred blocker. + regression_gates: + - No unrelated files changed. + - No secrets, credentials, or private local paths are introduced. + - No dependency installation, destructive cleanup, remote operation, release, deploy, or external-service + action occurs without explicit approval. + - Existing Codex scoped-worker/orchestrator safety boundaries remain stricter or equivalent after the + change. + visual_gate: + required: false + required_views: [] + pass_rule: Not required; this is a workflow/template change. + checkpoint_policy: Create a scoped checkpoint commit only after proof passes or after explicit user + approval. + rollback_or_accept_policy: If the scoped change makes the workflow ambiguous or less safe, keep the + ticket non-done, record the blocker, and propose a smaller follow-up ticket. + stop_conditions: + - The change would require product-repository assumptions that are not available in the template source. + - The change requires editing forbidden files. + - The design would weaken approval boundaries, proof gates, or scoped file ownership. + - The work requires dependency installation, destructive commands, remote operations, deployment, release, + secrets, migrations with side effects, network-dependent setup, or scope expansion without explicit + approval. + handoff_requirements: + - Record changed files, commands run, proof result, skipped checks, blockers, risks, agent updates, + and next action. + done_definition: Done when the scoped workflow/template improvement is implemented, required proof has + passed or justified skips are recorded, and execution_result is complete. +execution_result: + status: pending + changed_files: [] + commands_run: [] + proof: [] + skipped_checks: [] + agent_memory_updates: + checked: false + updated_files: [] + notes: null + blockers: [] + risks: + - 'Risk: maintaining current specs creates overhead; mitigate by requiring it only for significant behavior/API/workflow + changes.' + next_recommended_step: null diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml new file mode 100644 index 0000000..ebf8a6e --- /dev/null +++ b/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml @@ -0,0 +1,149 @@ +schema_version: 2 +ticket: + id: TKT-2026-06-09-expert-routing-profiles + title: Add routing profiles for the existing read-only expert team + repo: agentic-engineering-workflow-template + branch: main + status: backlog + created_at: '2026-06-09' + owner_agent: manager + ticket_class: implementation + work_kind: refactor + phase: sdd-upgrade-v0.4.0 + target_version: 0.4.0 +context: + problem: The workflow already has an expert-team pattern through manager-orchestrator, scoped worker, + read-only reviewer, final verifier, and the expert_supported/bounded_expert_rounds execution modes. + However, the current reviewer role is generic, so the manager must manually decide which expert lens + is needed for architecture, tests, security, UX, performance, data, or release documentation. + current_behavior: Tickets can request a read-only reviewer through expert_plan, but there is no structured + routing contract for reviewer profile, trigger, maximum review rounds, expected output, or escalation. + desired_behavior: The existing read-only expert mechanism gains explicit routing profiles without adding + a second BMAD-style persona team. Tickets can declare required/optional expert profiles, trigger + conditions, and max rounds. Reviewers remain read-only and produce bounded findings, proof requirements, + and the next worker task. + relevant_prior_work: + - 'User-provided iX article: Fünf Tools für Spec-driven Development im Überblick, 2026-06-08' + - README.md + - docs/workflow.md + - prompts/read-only-expert.md + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml +scope: + goal: Specialize the existing expert-team workflow with explicit read-only expert routing metadata and + profile guidance. + allowed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - prompts/read-only-expert.md + - prompts/manager-orchestrator.md + - checklists/ticket-readiness.md + - docs/workflow.md + - README.md + forbidden_files: + - .env + - .env.* + - node_modules/** + - dist/** + - build/** + - .next/** + - coverage/** + in_scope: + - Add an expert_routing block to ticket templates with required_profiles, optional_profiles, triggers, + max_rounds, escalation_rule, and record_location. + - Define small reusable reviewer profiles such as requirements, architecture, test, security/privacy, + UX/visual, performance/reliability, data/migration, and docs/release. + - Update read-only expert prompt so the reviewer declares which profile was used and avoids persona theater. + - Update manager prompt so it chooses the minimum useful expert route from ticket risk and file/context + evidence. + - Update ticket readiness so expert routing is either explicit or intentionally not required. + out_of_scope: + - Do not add a separate agile team or BMAD clone. + - Do not make every ticket require every expert profile. + - Do not permit read-only experts to edit files, run migrations, install dependencies, deploy, release, + push, or widen scope. + - Do not require proprietary IDE features or a specific vendor workflow. +execution: + execution_intensity: expert_supported + manager_role: Main Codex agent owns scope, verifies the work, and records proof in this ticket. Any + Codex subagent inherits AGENTS.md, the active ticket scope, approval boundaries, forbidden actions, + and verification requirements. + worker_sequence: + - role: read_only_reviewer + mode: read_only + task: Review whether the proposed expert routing block improves the existing expert-team workflow without + adding excessive ceremony. + - role: scoped_worker + mode: implementation + task: Implement only the expert-routing template, prompt, checklist, and documentation changes described + in this ticket. + expert_plan: + required: true + planning_reviewer: read-only Codex reviewer using the workflow/architecture profile + reviewer: final verifier + record_location: execution_result + debug_logging_plan: + owner: scoped_worker + surfaces: + - YAML parse output + - Markdown link/path inspection + - grep output for expert_routing and read-only reviewer terminology + temporary_logging_policy: Do not add temporary logs to template files; record command output only + in ticket execution_result. + test_plan: + - Parse every changed YAML file with python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path('.').rglob('*.yaml')]". + - Grep changed docs/prompts/templates for expert_routing and read-only boundaries. + - Check README, docs/workflow.md, ticket templates, prompt files, and readiness checklist for consistent + terminology. + - Check whether agent memory files need updates and record the result. + proof_gates: + - Expert routing extends the existing expert-team pattern instead of duplicating it. + - Every expert profile is read-only by default and has a bounded output contract. + - Ticket templates allow the manager to select zero, one, or multiple expert profiles based on risk. + - Manager prompt has a rule to choose the minimum useful expert route and avoid ceremony for simple tickets. + - Ticket readiness requires expert routing to be explicit or explicitly not required. + - Agent-memory update check is recorded. + - Ticket result records changed files, commands, proof, skipped checks, blockers, and risks. + regression_gates: + - No unrelated files changed. + - No secrets, credentials, or private local paths are introduced. + - No dependency installation, destructive cleanup, remote operation, release, deploy, or external-service + action occurs without explicit approval. + - Existing scoped-worker, orchestrator, and final-verifier safety boundaries remain stricter or equivalent + after the change. + visual_gate: + required: false + required_views: [] + pass_rule: Not required; this is a workflow/template change. + checkpoint_policy: Create a scoped checkpoint commit only after proof passes or after explicit user + approval. + rollback_or_accept_policy: If expert routing makes the workflow more ambiguous or pushes every ticket + toward ceremony, keep this ticket non-done and propose a smaller routing-only follow-up. + stop_conditions: + - The change would require product-repository assumptions that are not available in the template source. + - The change requires editing forbidden files. + - The design would weaken approval boundaries, proof gates, or scoped file ownership. + - The work requires dependency installation, destructive commands, remote operations, deployment, release, + secrets, migrations with side effects, network-dependent setup, or scope expansion without explicit + approval. + handoff_requirements: + - Record changed files, commands run, proof result, skipped checks, blockers, risks, agent updates, + and next action. + done_definition: Done when the existing expert-team workflow supports explicit profile routing, required + proof has passed or justified skips are recorded, and execution_result is complete. +execution_result: + status: pending + changed_files: [] + commands_run: [] + proof: [] + skipped_checks: [] + agent_memory_updates: + checked: false + updated_files: [] + notes: null + blockers: [] + risks: + - 'Risk: too many profiles could become ceremony; mitigate by requiring minimum useful expert route and + max_rounds.' + next_recommended_step: null diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml new file mode 100644 index 0000000..0d6a7c0 --- /dev/null +++ b/tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml @@ -0,0 +1,143 @@ +schema_version: 2 +ticket: + id: TKT-2026-06-09-quick-flow-escalation + title: Add quick-flow path with automatic escalation rules + repo: agentic-engineering-workflow-template + branch: main + status: backlog + created_at: '2026-06-09' + owner_agent: manager + ticket_class: implementation + work_kind: feature + phase: sdd-upgrade-v0.4.0 + target_version: 0.4.0 +context: + problem: The full ticket/orchestrator process is safe but can be too heavy for tiny, clear tasks. The + article points at BMAD Quick-Flow/Kiro Quick Plan style shortcuts that still perform discovery and + self-checks. + current_behavior: Every non-trivial task uses a full ticket. There is no separate minimal path for small, + clear changes and no explicit threshold for escalating to full spec/orchestrator flow. + desired_behavior: A quick-flow ticket/prompt handles small bounded changes with a discovery scan, concrete + file paths, Given-When-Then acceptance, proof commands, self-check, and automatic escalation when + scope/risk grows. + relevant_prior_work: + - 'User-provided iX article: Fünf Tools für Spec-driven Development im Überblick, 2026-06-08' + - README.md + - docs/workflow.md + - templates/AGENTS.md.template +scope: + goal: Create a quick-flow prompt/template and escalation policy for small safe tasks. + allowed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml + - prompts/quick-dev.md + - templates/TEMPLATE.quick-ticket.yaml + - docs/workflow.md + - README.md + - templates/AGENTS.md.template + - checklists/ticket-readiness.md + forbidden_files: + - .env + - .env.* + - node_modules/** + - dist/** + - build/** + - .next/** + - coverage/** + in_scope: + - 'Add TEMPLATE.quick-ticket.yaml with compact fields: objective, discovery_evidence, allowed_files, + forbidden_files, acceptance_given_when_then, proof, escalation_conditions, execution_result.' + - Add prompts/quick-dev.md that scans repo evidence, identifies patterns, creates a compact spec, implements, + then self-checks against acceptance. + - 'Define escalation thresholds: more than N files, architectural decision, dependency change, data + migration, auth/security impact, flaky/unknown proof, unclear requirements, UI flows needing visual + proof, or scope outside allowed_files.' + - Update docs/workflow.md and README to explain when quick-flow is allowed and when full SDD/orchestrator + flow is mandatory. + out_of_scope: + - Do not bypass proof gates. + - Do not permit quick-flow for secrets, auth, migrations, releases, dependency changes, or broad refactors. + - Do not make quick-flow the default for risky work. +execution: + execution_intensity: expert_supported + manager_role: Main Codex agent owns scope, verifies the work, and records proof in this ticket. Any + Codex subagent inherits AGENTS.md, the active ticket scope, approval boundaries, forbidden actions, + and verification requirements. + worker_sequence: + - role: read_only_reviewer + mode: read_only + task: Review the planned workflow/template changes for SDD usefulness, risk, and minimality before + edits. + - role: scoped_worker + mode: implementation + task: Implement only the scoped workflow/template change described in this ticket. + expert_plan: + required: true + planning_reviewer: read-only Codex reviewer + reviewer: final verifier + record_location: execution_result + debug_logging_plan: + owner: scoped_worker + surfaces: + - YAML parse output + - Markdown link/path inspection + - grep output for version and old terminology + temporary_logging_policy: Do not add temporary logs to template files; record command output only + in ticket execution_result. + test_plan: + - Parse every changed YAML file with python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) + for p in pathlib.Path('.').rglob('*.yaml')]". + - Run markdown/path consistency checks manually or with grep for all newly referenced template paths. + - Check whether README, docs/workflow.md, AGENTS template, prompts, checklists, ticket templates, and + agent memory files need updates and record the result. + proof_gates: + - Changed templates and tickets are internally consistent and parseable where applicable. + - The workflow change is bounded to SDD/context-engineering support and does not alter product runtime + assumptions. + - Agent-memory update check is recorded. + - Ticket result records changed files, commands, proof, skipped checks, blockers, and risks. + - Quick-flow still records execution_result, proof, skipped checks, blockers, risks, and agent memory + check. + - Escalation conditions are explicit in prompt, template, and workflow docs. + - Quick-flow cannot modify forbidden files or expand scope without approval. + regression_gates: + - No unrelated files changed. + - No secrets, credentials, or private local paths are introduced. + - No dependency installation, destructive cleanup, remote operation, release, deploy, or external-service + action occurs without explicit approval. + - Existing Codex scoped-worker/orchestrator safety boundaries remain stricter or equivalent after the + change. + visual_gate: + required: false + required_views: [] + pass_rule: Not required; this is a workflow/template change. + checkpoint_policy: Create a scoped checkpoint commit only after proof passes or after explicit user + approval. + rollback_or_accept_policy: If the scoped change makes the workflow ambiguous or less safe, keep the + ticket non-done, record the blocker, and propose a smaller follow-up ticket. + stop_conditions: + - The change would require product-repository assumptions that are not available in the template source. + - The change requires editing forbidden files. + - The design would weaken approval boundaries, proof gates, or scoped file ownership. + - The work requires dependency installation, destructive commands, remote operations, deployment, release, + secrets, migrations with side effects, network-dependent setup, or scope expansion without explicit + approval. + handoff_requirements: + - Record changed files, commands run, proof result, skipped checks, blockers, risks, agent updates, + and next action. + done_definition: Done when the scoped workflow/template improvement is implemented, required proof has + passed or justified skips are recorded, and execution_result is complete. +execution_result: + status: pending + changed_files: [] + commands_run: [] + proof: [] + skipped_checks: [] + agent_memory_updates: + checked: false + updated_files: [] + notes: null + blockers: [] + risks: + - 'Risk: quick-flow becomes vibe coding in disguise; mitigate with explicit discovery evidence, Given-When-Then + acceptance, and hard escalation triggers.' + next_recommended_step: null diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml new file mode 100644 index 0000000..132eab1 --- /dev/null +++ b/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml @@ -0,0 +1,147 @@ +schema_version: 2 +ticket: + id: TKT-2026-06-09-readme-terminology-version-0-4-0 + title: Update README terminology and version metadata for SDD release 0.4.0 + repo: agentic-engineering-workflow-template + branch: main + status: backlog + created_at: '2026-06-09' + owner_agent: manager + ticket_class: implementation + work_kind: documentation + phase: sdd-upgrade-v0.4.0 + target_version: 0.4.0 +context: + problem: The README currently positions the template as an agentic engineering workflow. After SDD integration, + the public docs should explain the new terminology, when to use full SDD vs quick-flow, and how version + 0.4.0 differs from 0.3.0. + current_behavior: 'README.md says Current version: 0.3.0 and describes ticket-driven Codex workflow, + proof gates, calibration loops, roles, and target installation. VERSION contains 0.3.0. CHANGELOG.md + has a 0.3.0 entry.' + desired_behavior: 'README.md, VERSION, CHANGELOG.md, and agent/CHANGELOG.md consistently describe 0.4.0 + as the first SDD/context-engineering workflow upgrade. The README uses current SDD terminology: spec-first, + spec-anchored, context pack, conditional steering, quick-flow, spec drift verification, and delta + specs.' + relevant_prior_work: + - 'User-provided iX article: Fünf Tools für Spec-driven Development im Überblick, 2026-06-08' + - README.md + - docs/workflow.md + - templates/AGENTS.md.template +scope: + goal: Update release metadata and README terminology to match the new SDD workflow naming and target + version 0.4.0. + allowed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml + - README.md + - VERSION + - CHANGELOG.md + - agent/CHANGELOG.md + forbidden_files: + - .env + - .env.* + - node_modules/** + - dist/** + - build/** + - .next/** + - coverage/** + in_scope: + - Change VERSION from 0.3.0 to 0.4.0. + - Change README Current version from 0.3.0 to 0.4.0. + - Add README section explaining SDD mode, Spec-first vs Spec-anchored behavior, and how this template + differs from Vibe Coding. + - Document quick-flow vs full orchestrator criteria. + - Add README reference to spec artifacts, delta specs, conditional steering, spec drift verifier, and + context packs. + - Add CHANGELOG.md entry for 0.4.0 dated 2026-06-09. + - Add agent/CHANGELOG.md local note for the SDD upgrade ticket chain. + out_of_scope: + - Do not update product code. + - Do not publish/release/tag. + - Do not claim Spec-as-Source maturity unless implemented in a later ticket. + - Do not remove 0.3.0 changelog history. +execution: + execution_intensity: expert_supported + manager_role: Main Codex agent owns scope, verifies the work, and records proof in this ticket. Any + Codex subagent inherits AGENTS.md, the active ticket scope, approval boundaries, forbidden actions, + and verification requirements. + worker_sequence: + - role: read_only_reviewer + mode: read_only + task: Review the planned workflow/template changes for SDD usefulness, risk, and minimality before + edits. + - role: scoped_worker + mode: implementation + task: Implement only the scoped workflow/template change described in this ticket. + expert_plan: + required: true + planning_reviewer: read-only Codex reviewer + reviewer: final verifier + record_location: execution_result + debug_logging_plan: + owner: scoped_worker + surfaces: + - YAML parse output + - Markdown link/path inspection + - grep output for version and old terminology + temporary_logging_policy: Do not add temporary logs to template files; record command output only + in ticket execution_result. + test_plan: + - Parse every changed YAML file with python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) + for p in pathlib.Path('.').rglob('*.yaml')]". + - Run markdown/path consistency checks manually or with grep for all newly referenced template paths. + - Check whether README, docs/workflow.md, AGENTS template, prompts, checklists, ticket templates, and + agent memory files need updates and record the result. + - 'grep -R "Current version: 0.3.0" README.md returns no matches.' + - grep -R "0.4.0" README.md VERSION CHANGELOG.md returns expected matches. + proof_gates: + - Changed templates and tickets are internally consistent and parseable where applicable. + - The workflow change is bounded to SDD/context-engineering support and does not alter product runtime + assumptions. + - Agent-memory update check is recorded. + - Ticket result records changed files, commands, proof, skipped checks, blockers, and risks. + - cat VERSION returns 0.4.0. + - 'README.md contains Current version: 0.4.0 and no stale Current version: 0.3.0 text.' + - CHANGELOG.md contains a 0.4.0 section and preserves the 0.3.0 history. + - README has a clear migration/upgrade note for existing target repositories. + regression_gates: + - No unrelated files changed. + - No secrets, credentials, or private local paths are introduced. + - No dependency installation, destructive cleanup, remote operation, release, deploy, or external-service + action occurs without explicit approval. + - Existing Codex scoped-worker/orchestrator safety boundaries remain stricter or equivalent after the + change. + visual_gate: + required: false + required_views: [] + pass_rule: Not required; this is a workflow/template change. + checkpoint_policy: Create a scoped checkpoint commit only after proof passes or after explicit user + approval. + rollback_or_accept_policy: If the scoped change makes the workflow ambiguous or less safe, keep the + ticket non-done, record the blocker, and propose a smaller follow-up ticket. + stop_conditions: + - The change would require product-repository assumptions that are not available in the template source. + - The change requires editing forbidden files. + - The design would weaken approval boundaries, proof gates, or scoped file ownership. + - The work requires dependency installation, destructive commands, remote operations, deployment, release, + secrets, migrations with side effects, network-dependent setup, or scope expansion without explicit + approval. + handoff_requirements: + - Record changed files, commands run, proof result, skipped checks, blockers, risks, agent updates, + and next action. + done_definition: Done when the scoped workflow/template improvement is implemented, required proof has + passed or justified skips are recorded, and execution_result is complete. +execution_result: + status: pending + changed_files: [] + commands_run: [] + proof: [] + skipped_checks: [] + agent_memory_updates: + checked: false + updated_files: [] + notes: null + blockers: [] + risks: + - 'Risk: version bump before all SDD tickets are implemented; mitigate by running this ticket last in + the orchestrator sequence.' + next_recommended_step: null diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-sdd-upgrade-orchestrator.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-sdd-upgrade-orchestrator.yaml new file mode 100644 index 0000000..fb7df04 --- /dev/null +++ b/tickets/sdd-upgrade/TKT-2026-06-09-sdd-upgrade-orchestrator.yaml @@ -0,0 +1,227 @@ +schema_version: 2 +ticket: + id: TKT-2026-06-09-sdd-upgrade-orchestrator + title: Orchestrate SDD/context-engineering upgrade for workflow template + repo: agentic-engineering-workflow-template + branch: main + status: backlog + created_at: '2026-06-09' + owner_agent: manager + ticket_class: orchestrator + work_kind: codex_subagent_execution + phase: sdd-upgrade-v0.4.0 + target_version: 0.4.0 +context: + objective: Upgrade the workflow template from ticket-driven agentic engineering to an explicit Spec-driven + Development capable workflow for release 0.4.0. Keep the template Codex-first, tool-agnostic where + possible, and safer than vibe coding. + constraints: + - Use existing project conventions and file layout unless a child ticket deliberately introduces a new + template folder. + - Do not weaken approval boundaries, allowed_files enforcement, proof gates, no-secrets rules, or no-bulk-staging + rules. + - Keep full BMAD-style agile ceremony out of the default path; extend the existing expert-team pattern with routing profiles only where useful. + - No dependency installation, destructive cleanup, remote operation, release, deploy, or external-service + action without explicit approval. + source_of_truth: + - README.md + - docs/workflow.md + - templates/AGENTS.md.template + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - prompts/*.md + - checklists/*.md + - User-provided iX SDD article from 2026-06-08 + target_version: 0.4.0 +orchestration: + execution_intensity: bounded_expert_rounds + manager_role: The manager keeps full context, decomposes work into scoped child tickets, runs one implementation + worker at a time, reviews proof, and decides whether to advance, retry, checkpoint, or stop. + max_iterations: 10 + parallelism_policy: Read-only reviewers may run in parallel for independent questions. Implementation + workers run serially unless child tickets declare disjoint write scopes. + worker_sequence: + - stage: 0 + id: planning_review + role: read_only_reviewer + mode: read_only + owns_files: [] + task: Review all child tickets for overlap, risk, release coherence, and unnecessary ceremony before + implementation. + exit_gate: Reviewer findings are recorded and manager accepts or revises child tickets. + - stage: 1 + id: expert_routing + role: scoped_worker + mode: implementation + owns_files: + - prompts/read-only-expert.md + - prompts/manager-orchestrator.md + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - checklists/ticket-readiness.md + - docs/workflow.md + task: Add routing profiles for the existing read-only expert-team workflow. + exit_gate: Tickets can declare minimum useful expert profiles without creating a second BMAD-style team. + - stage: 2 + id: spec_artifacts + role: scoped_worker + mode: implementation + owns_files: + - templates/specs/** + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - docs/workflow.md + - templates/AGENTS.md.template + task: Add requirements/design/tasks spec artifacts and wire them into ticket readiness. + exit_gate: Spec templates exist and tickets can reference them. + - stage: 3 + id: delta_specs + role: scoped_worker + mode: implementation + owns_files: + - templates/specs/** + - docs/spec_lifecycle.md + - docs/workflow.md + - templates/AGENTS.md.template + task: Add spec-anchored delta-spec lifecycle. + exit_gate: ADDED/MODIFIED/REMOVED change flow is documented and checkable. + - stage: 4 + id: drift_verification + role: scoped_worker + mode: implementation + owns_files: + - prompts/spec-drift-verifier.md + - checklists/spec-drift.md + - prompts/final-verifier.md + - checklists/closeout.md + - templates/TEMPLATE.execution-result.yaml + task: Add cross-artifact spec drift verification. + exit_gate: Closeout and final verification require spec alignment proof. + - stage: 5 + id: conditional_steering + role: scoped_worker + mode: implementation + owns_files: + - templates/steering/** + - templates/AGENTS.md.template + - docs/workflow.md + - prompts/initialize-repo.md + task: Add conditional steering documents to reduce context noise. + exit_gate: Rules explain always, fileMatch, manual, and auto-like loading without requiring Kiro. + - stage: 6 + id: quick_flow + role: scoped_worker + mode: implementation + owns_files: + - prompts/quick-dev.md + - templates/TEMPLATE.quick-ticket.yaml + - docs/workflow.md + - README.md + task: Add quick-flow path with automatic escalation thresholds. + exit_gate: Small tasks can use quick flow and larger/risky tasks escalate. + - stage: 7 + id: decision_context_budget + role: scoped_worker + mode: implementation + owns_files: + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - agent/DECISIONS.md + - docs/workflow.md + - prompts/manager-orchestrator.md + task: Add locked decisions and context-budget controls. + exit_gate: Grey areas must be resolved before implementation and fresh contexts receive bounded context + packs. + - stage: 8 + id: readme_version + role: scoped_worker + mode: documentation + owns_files: + - README.md + - VERSION + - CHANGELOG.md + - agent/CHANGELOG.md + task: Update README terminology and version metadata to 0.4.0. + exit_gate: README and VERSION agree on 0.4.0 and changelog describes SDD upgrade. + - stage: 9 + id: final_verification + role: final_verifier + mode: read_only + owns_files: [] + task: Verify child tickets, version coherence, spec alignment gates, expert-routing boundaries, and no + safety regressions. + exit_gate: Verifier result is recorded. +child_ticket_policy: + required: true + template: tickets/templates/TEMPLATE.ticket.yaml + naming: TKT-2026-06-09-sdd-.yaml + requirements: + - Each child ticket has one owner, one scope, one done definition, explicit allowed_files/forbidden_files, + proof gates, expert-routing status, and execution_result. +test_plan: +- Parse all YAML tickets/templates. +- Check all referenced new template paths exist after implementation. +- Check expert-routing fields and read-only expert boundaries are internally consistent. +- Check README.md, VERSION, and CHANGELOG.md agree on 0.4.0. +- Run grep for old terminology/version references and justify any remaining historical references. +- Final verifier checks that no SDD addition weakens safety or scope controls. +proof_gates: +- All child tickets done or deferred with explicit blockers. +- Final verifier result is recorded. +- No unresolved blocker remains for v0.4.0 release metadata. +- Agent-memory update check is recorded. +regression_gates: +- No child worker edits outside declared scope. +- No safety boundary is weakened. +- No secrets/local paths/generated caches/dependency folders are introduced. +- No external-service action occurs. +visual_gate: + required: false + required_views: [] + pass_rule: Not required. +checkpoint_policy: Checkpoint only after completed child tickets when user/repo policy allows commits. +rollback_or_accept_policy: If a stage fails, stop and record a blocker; do not merge partial workflow + semantics that conflict with existing ticket rules. +stop_conditions: +- A child ticket needs files outside scope. +- The implementation would require a specific proprietary IDE/runtime as a hard dependency. +- The plan weakens safety boundaries. +- Final proof cannot be collected. +allowed_files: +- tickets/** +- templates/** +- prompts/** +- checklists/** +- docs/** +- agent/** +- README.md +- VERSION +- CHANGELOG.md +forbidden_files: +- .env +- .env.* +- node_modules/** +- dist/** +- build/** +- .next/** +- coverage/** +handoff_requirements: +- List each child ticket status, changed files, commands, proof artifacts, agent updates, blockers, risks, + skipped checks, and exact next action. +done_definition: Done when the SDD upgrade is delivered through completed child tickets, final proof passes, + the agent memory update check is complete, and this orchestrator ticket contains a concise execution_result + manager closeout. +execution_result: + status: pending + child_ticket_status: [] + changed_files: [] + commands_run: [] + proof: [] + skipped_checks: [] + agent_memory_updates: + checked: false + updated_files: [] + notes: null + blockers: [] + risks: [] + next_recommended_step: null diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml new file mode 100644 index 0000000..8cd2d0f --- /dev/null +++ b/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml @@ -0,0 +1,147 @@ +schema_version: 2 +ticket: + id: TKT-2026-06-09-spec-artifact-package + title: Add machine-readable SDD spec artifacts before implementation + repo: agentic-engineering-workflow-template + branch: main + status: backlog + created_at: '2026-06-09' + owner_agent: manager + ticket_class: implementation + work_kind: feature + phase: sdd-upgrade-v0.4.0 + target_version: 0.4.0 +context: + problem: The current workflow has strong tickets and proof gates, but tickets are doing too many jobs + at once. There is no separate requirements/design/tasks artifact set that can act as the machine-readable + Single Source of Truth for a feature. + current_behavior: A worker can receive a scoped ticket with context, test_plan, proof_gates, and done_definition. + The workflow does not require requirements.md, design.md, tasks.md, EARS/Given-When-Then acceptance + criteria, invariants, or a traceable spec-to-test map. + desired_behavior: Non-trivial work must start with a compact spec package. The ticket points to the + spec package, and implementation workers treat it as source of truth together with AGENTS.md and agent + memory. Small quick-flow tickets may explicitly justify why no full spec package is needed. + relevant_prior_work: + - 'User-provided iX article: Fünf Tools für Spec-driven Development im Überblick, 2026-06-08' + - README.md + - docs/workflow.md + - templates/AGENTS.md.template +scope: + goal: 'Create and wire templates for SDD feature/bugfix specs: requirements or bugfix analysis, design, + and tasks with acceptance criteria and proof mapping.' + allowed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml + - templates/specs/** + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - checklists/ticket-readiness.md + - docs/workflow.md + - templates/AGENTS.md.template + - prompts/manager-orchestrator.md + - prompts/scoped-worker.md + forbidden_files: + - .env + - .env.* + - node_modules/** + - dist/** + - build/** + - .next/** + - coverage/** + in_scope: + - Add templates/specs/TEMPLATE.requirements.md with user stories, EARS-style acceptance, Given-When-Then + cases, constraints, preconditions, postconditions, invariants, non-goals, and ambiguity log. + - Add templates/specs/TEMPLATE.design.md with architecture, impacted files, interfaces, data flow, failure + modes, security/privacy notes, and test strategy. + - Add templates/specs/TEMPLATE.tasks.md with discrete, dependency-ordered tasks, owner role, allowed + files, proof, and traceability to requirements. + - Add spec_refs/spec_contract fields to ticket templates so every implementation ticket links to its + spec artifacts or records a quick-flow exemption. + - Update readiness checklist and role prompts so implementation cannot start until spec artifacts are + present or exemption is explicit. + out_of_scope: + - Do not import GitHub Spec Kit or Kiro as a dependency. + - Do not replace the existing ticket model. + - Do not require full specs for tiny typo/docs changes when quick-flow exemption is valid. +execution: + execution_intensity: expert_supported + manager_role: Main Codex agent owns scope, verifies the work, and records proof in this ticket. Any + Codex subagent inherits AGENTS.md, the active ticket scope, approval boundaries, forbidden actions, + and verification requirements. + worker_sequence: + - role: read_only_reviewer + mode: read_only + task: Review the planned workflow/template changes for SDD usefulness, risk, and minimality before + edits. + - role: scoped_worker + mode: implementation + task: Implement only the scoped workflow/template change described in this ticket. + expert_plan: + required: true + planning_reviewer: read-only Codex reviewer + reviewer: final verifier + record_location: execution_result + debug_logging_plan: + owner: scoped_worker + surfaces: + - YAML parse output + - Markdown link/path inspection + - grep output for version and old terminology + temporary_logging_policy: Do not add temporary logs to template files; record command output only + in ticket execution_result. + test_plan: + - Parse every changed YAML file with python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) + for p in pathlib.Path('.').rglob('*.yaml')]". + - Run markdown/path consistency checks manually or with grep for all newly referenced template paths. + - Check whether README, docs/workflow.md, AGENTS template, prompts, checklists, ticket templates, and + agent memory files need updates and record the result. + proof_gates: + - Changed templates and tickets are internally consistent and parseable where applicable. + - The workflow change is bounded to SDD/context-engineering support and does not alter product runtime + assumptions. + - Agent-memory update check is recorded. + - Ticket result records changed files, commands, proof, skipped checks, blockers, and risks. + - A new implementation ticket template exposes spec_refs or spec_contract fields. + - Ticket readiness fails if non-trivial implementation work lacks either spec artifacts or a justified + quick-flow exemption. + - Spec templates remain concise enough to be copied into a target repo without product-specific assumptions. + regression_gates: + - No unrelated files changed. + - No secrets, credentials, or private local paths are introduced. + - No dependency installation, destructive cleanup, remote operation, release, deploy, or external-service + action occurs without explicit approval. + - Existing Codex scoped-worker/orchestrator safety boundaries remain stricter or equivalent after the + change. + visual_gate: + required: false + required_views: [] + pass_rule: Not required; this is a workflow/template change. + checkpoint_policy: Create a scoped checkpoint commit only after proof passes or after explicit user + approval. + rollback_or_accept_policy: If the scoped change makes the workflow ambiguous or less safe, keep the + ticket non-done, record the blocker, and propose a smaller follow-up ticket. + stop_conditions: + - The change would require product-repository assumptions that are not available in the template source. + - The change requires editing forbidden files. + - The design would weaken approval boundaries, proof gates, or scoped file ownership. + - The work requires dependency installation, destructive commands, remote operations, deployment, release, + secrets, migrations with side effects, network-dependent setup, or scope expansion without explicit + approval. + handoff_requirements: + - Record changed files, commands run, proof result, skipped checks, blockers, risks, agent updates, + and next action. + done_definition: Done when the scoped workflow/template improvement is implemented, required proof has + passed or justified skips are recorded, and execution_result is complete. +execution_result: + status: pending + changed_files: [] + commands_run: [] + proof: [] + skipped_checks: [] + agent_memory_updates: + checked: false + updated_files: [] + notes: null + blockers: [] + risks: + - 'Risk: over-specification can slow tiny work; mitigate with quick-flow exemption and escalation ticket.' + next_recommended_step: null diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml new file mode 100644 index 0000000..82f42b3 --- /dev/null +++ b/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml @@ -0,0 +1,139 @@ +schema_version: 2 +ticket: + id: TKT-2026-06-09-spec-drift-verifier + title: Add read-only spec drift verifier and cross-artifact proof gate + repo: agentic-engineering-workflow-template + branch: main + status: backlog + created_at: '2026-06-09' + owner_agent: manager + ticket_class: implementation + work_kind: test + phase: sdd-upgrade-v0.4.0 + target_version: 0.4.0 +context: + problem: SDD only works if spec, code, tests, docs, and ticket results stay aligned. The current final + verifier checks scope and proof, but it does not explicitly compare requirements/design/tasks against + the implemented diff and tests. + current_behavior: final-verifier.md validates ticket scope, changed files, proof gates, skipped checks, + and agent memory. It may catch drift indirectly, but no dedicated spec-alignment verdict exists. + desired_behavior: A read-only spec drift verifier compares spec artifacts, changed files, tests, docs, + and execution_result. It returns pass, pass_with_risk, or fail and blocks closing when drift is material. + relevant_prior_work: + - 'User-provided iX article: Fünf Tools für Spec-driven Development im Überblick, 2026-06-08' + - README.md + - docs/workflow.md + - templates/AGENTS.md.template +scope: + goal: Create a spec drift verification prompt/checklist and wire it into final verification and execution_result. + allowed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml + - prompts/spec-drift-verifier.md + - prompts/final-verifier.md + - checklists/spec-drift.md + - checklists/closeout.md + - templates/TEMPLATE.execution-result.yaml + - templates/TEMPLATE.ticket.yaml + forbidden_files: + - .env + - .env.* + - node_modules/** + - dist/** + - build/** + - .next/** + - coverage/** + in_scope: + - Add prompts/spec-drift-verifier.md for read-only comparison of requirements, design, tasks, code diff, + tests, docs, and ticket result. + - 'Add checklists/spec-drift.md with required questions: implemented-but-unspecified, specified-but-unimplemented, + tests-missing-for-acceptance, docs-outdated, changed behavior not approved.' + - Add execution_result.spec_alignment with verdict, checked_specs, drift_findings, required_followups. + - Update final-verifier.md to require spec_alignment for non-trivial tickets. + - Update closeout checklist to require drift result or quick-flow exemption. + out_of_scope: + - Do not auto-rewrite product code in the verifier. + - Do not treat every docs-only ticket as requiring full drift verification. + - Do not create a remote CI integration in this ticket. +execution: + execution_intensity: expert_supported + manager_role: Main Codex agent owns scope, verifies the work, and records proof in this ticket. Any + Codex subagent inherits AGENTS.md, the active ticket scope, approval boundaries, forbidden actions, + and verification requirements. + worker_sequence: + - role: read_only_reviewer + mode: read_only + task: Review the planned workflow/template changes for SDD usefulness, risk, and minimality before + edits. + - role: scoped_worker + mode: implementation + task: Implement only the scoped workflow/template change described in this ticket. + expert_plan: + required: true + planning_reviewer: read-only Codex reviewer + reviewer: final verifier + record_location: execution_result + debug_logging_plan: + owner: scoped_worker + surfaces: + - YAML parse output + - Markdown link/path inspection + - grep output for version and old terminology + temporary_logging_policy: Do not add temporary logs to template files; record command output only + in ticket execution_result. + test_plan: + - Parse every changed YAML file with python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) + for p in pathlib.Path('.').rglob('*.yaml')]". + - Run markdown/path consistency checks manually or with grep for all newly referenced template paths. + - Check whether README, docs/workflow.md, AGENTS template, prompts, checklists, ticket templates, and + agent memory files need updates and record the result. + proof_gates: + - Changed templates and tickets are internally consistent and parseable where applicable. + - The workflow change is bounded to SDD/context-engineering support and does not alter product runtime + assumptions. + - Agent-memory update check is recorded. + - Ticket result records changed files, commands, proof, skipped checks, blockers, and risks. + - A non-trivial ticket cannot be marked done without spec_alignment or a documented exemption. + - Spec drift verifier is read-only and cannot repair issues without a separate scoped repair ticket. + - Execution result template has a machine-readable spec_alignment block. + regression_gates: + - No unrelated files changed. + - No secrets, credentials, or private local paths are introduced. + - No dependency installation, destructive cleanup, remote operation, release, deploy, or external-service + action occurs without explicit approval. + - Existing Codex scoped-worker/orchestrator safety boundaries remain stricter or equivalent after the + change. + visual_gate: + required: false + required_views: [] + pass_rule: Not required; this is a workflow/template change. + checkpoint_policy: Create a scoped checkpoint commit only after proof passes or after explicit user + approval. + rollback_or_accept_policy: If the scoped change makes the workflow ambiguous or less safe, keep the + ticket non-done, record the blocker, and propose a smaller follow-up ticket. + stop_conditions: + - The change would require product-repository assumptions that are not available in the template source. + - The change requires editing forbidden files. + - The design would weaken approval boundaries, proof gates, or scoped file ownership. + - The work requires dependency installation, destructive commands, remote operations, deployment, release, + secrets, migrations with side effects, network-dependent setup, or scope expansion without explicit + approval. + handoff_requirements: + - Record changed files, commands run, proof result, skipped checks, blockers, risks, agent updates, + and next action. + done_definition: Done when the scoped workflow/template improvement is implemented, required proof has + passed or justified skips are recorded, and execution_result is complete. +execution_result: + status: pending + changed_files: [] + commands_run: [] + proof: [] + skipped_checks: [] + agent_memory_updates: + checked: false + updated_files: [] + notes: null + blockers: [] + risks: + - 'Risk: false positives on intentionally changed scope; mitigate by allowing pass_with_risk plus explicit + decision record.' + next_recommended_step: null From af1104b9f96e603b6c71d98417fa579c0276cc37 Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:10:39 +0200 Subject: [PATCH 02/11] Add expert routing profiles --- README.md | 18 +++++- checklists/ticket-readiness.md | 5 ++ docs/workflow.md | 22 ++++++- prompts/manager-orchestrator.md | 6 ++ prompts/read-only-expert.md | 30 +++++++++- templates/TEMPLATE.orchestrator-ticket.yaml | 35 +++++++++++ templates/TEMPLATE.ticket.yaml | 27 +++++++++ ...KT-2026-06-09-expert-routing-profiles.yaml | 59 ++++++++++++++++--- 8 files changed, 187 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index fef4ee5..34c2d21 100644 --- a/README.md +++ b/README.md @@ -181,7 +181,10 @@ shape around its normal product code, tests, package files, docs, and scripts: explicit `allowed_files`, reports changed files and proof, and stops if scope needs to expand. - `read-only reviewer`: a Codex subagent or role prompt that reviews plans, - risks, code, tests, or architecture without editing files. + risks, code, tests, or architecture without editing files. Reviewer routes can + use the `requirements`, `architecture`, `test`, `security_privacy`, + `ux_visual`, `performance_reliability`, `data_migration`, or `docs_release` + profile as a narrow review lens. - `final verifier`: a Codex reviewer that checks scope, proof gates, regression gates, skipped checks, and agent-memory closeout before a ticket or chain is marked done. @@ -194,6 +197,12 @@ The execution modes are defined in the templates and docs: `standard_worker`, `expert_supported`, `bounded_expert_rounds`, and `research_only`. +Tickets can add `expert_routing` to declare required profiles, optional +profiles, trigger conditions, `max_rounds`, escalation behavior, and where +reviewer output is recorded. The manager chooses the minimum useful read-only +route from ticket risk and repository evidence; simple tickets can explicitly +set no required profiles and `max_rounds: 0`. + ## Safety Model The template is built around narrow scope and explicit proof: @@ -205,7 +214,9 @@ The template is built around narrow scope and explicit proof: out-of-scope work, proof gates, regression gates, stop conditions, and done definitions. - Implementation workers edit only assigned scope and do not use bulk staging. -- Read-only Codex reviewers may analyze but do not edit files. +- Read-only Codex reviewers may analyze but do not edit files, run migrations, + install dependencies, deploy, release, use secrets, push, perform remote + operations, or widen scope. - Closeout records changed files, commands run, proof, skipped checks, blockers, risks, and whether `agent/*.md` needed updates. - If no durable agent-memory update is needed, closeout records: @@ -228,7 +239,8 @@ rules only after reviewing the target repository's real context. [`prompts/scoped-worker.md`](prompts/scoped-worker.md), edits only the ticket scope, and records proof. 5. If the work is risky or blocked, the manager asks a read-only Codex reviewer - using [`prompts/read-only-expert.md`](prompts/read-only-expert.md). + using [`prompts/read-only-expert.md`](prompts/read-only-expert.md) and the + smallest useful `expert_routing` profile. 6. The worker or manager records closeout using [`templates/TEMPLATE.execution-result.yaml`](templates/TEMPLATE.execution-result.yaml). 7. A final verifier uses diff --git a/checklists/ticket-readiness.md b/checklists/ticket-readiness.md index 62bb3f3..61862a1 100644 --- a/checklists/ticket-readiness.md +++ b/checklists/ticket-readiness.md @@ -13,6 +13,11 @@ Use before product-code work starts. - [ ] `manager_role` is explicit. - [ ] `worker_sequence` is ordered and each worker has a bounded task. - [ ] `expert_plan` says whether read-only Codex reviewer input is required. +- [ ] `expert_routing` lists required profiles, optional profiles, triggers, + `max_rounds`, escalation rule, and record location, or explicitly sets no + required profiles and `max_rounds: 0`. +- [ ] Expert routing uses the minimum useful read-only profile route and does + not require every profile by default. - [ ] Any Codex subagent role inherits `AGENTS.md`, ticket scope, approval boundaries, forbidden actions, and verification requirements. - [ ] `debug_logging_plan` names an owner and surfaces. diff --git a/docs/workflow.md b/docs/workflow.md index e57a900..401c694 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -56,6 +56,21 @@ files, commands, proof, skipped checks, blockers, risks, and memory updates. risk, architecture, tests, or review questions without editing files. Reviewer output should become ticket context for the next worker. +Read-only reviewers can be routed through small reusable expert profiles: +`requirements`, `architecture`, `test`, `security_privacy`, `ux_visual`, +`performance_reliability`, `data_migration`, and `docs_release`. These profiles +are review lenses for the existing workflow, not a separate team model. The +manager chooses the minimum useful route from ticket risk, changed files, +unknowns, and proof gaps. Simple tickets can set no required profiles and +`max_rounds: 0`. + +Every profile remains read-only. Expert reviewers may inspect files and report +bounded findings, proof requirements, and the next worker task. They may not edit +files, run migrations, install dependencies, deploy, release, use secrets, push, +perform remote operations, or widen scope. If a finding requires broader files or +unapproved actions, the manager stops, revises the ticket, or creates a new +scoped ticket instead of letting the reviewer act. + `final verifier` checks the result against scope, proof gates, regression gates, skipped checks, and memory closeout. It does not repair issues unless the manager creates or assigns a repair ticket. @@ -72,11 +87,14 @@ active ticket and user approval allow the exact action. direct proof. `expert_supported` means a read-only Codex planning or review subagent runs -before or after one scoped worker. +before or after one scoped worker. Use `expert_routing` to declare required and +optional review profiles, triggers, max rounds, escalation behavior, and where +findings are recorded. `bounded_expert_rounds` means the manager runs a capped loop: collect proof, ask a read-only Codex reviewer, assign one bounded worker task, run proof, then -checkpoint or record a blocker. +checkpoint or record a blocker. The cap comes from `expert_routing.max_rounds` +and should be the smallest number that matches the ticket risk. `research_only` means read-only Codex reviewers analyze and recommend. Product files do not change. diff --git a/prompts/manager-orchestrator.md b/prompts/manager-orchestrator.md index ce6e8b2..fbe32f5 100644 --- a/prompts/manager-orchestrator.md +++ b/prompts/manager-orchestrator.md @@ -24,6 +24,11 @@ Rules: - Create or update child tickets before implementation starts. - Run one implementation worker at a time unless scopes are explicitly disjoint. - Use read-only Codex reviewers for planning/review where required. +- Choose the minimum useful `expert_routing` profile from ticket risk, changed + files, proof gaps, and repository evidence. Do not ask every profile by + default or create persona-team ceremony. +- Keep every expert route read-only and within its `max_rounds`; stop or revise + the ticket if reviewer findings require broader scope or unapproved actions. - Ensure every Codex subagent follows `AGENTS.md`, the active ticket scope, approval boundaries, forbidden actions, and verification requirements. - Reject subagent output that exceeds assigned scope or depends on unapproved @@ -46,6 +51,7 @@ Current task: Output required: - plan status +- expert route selected, or `expert routing not required` - next worker or reviewer task - scope for that task - proof required before advancing diff --git a/prompts/read-only-expert.md b/prompts/read-only-expert.md index 51cfdf0..58a70e7 100644 --- a/prompts/read-only-expert.md +++ b/prompts/read-only-expert.md @@ -6,8 +6,8 @@ You are a read-only Codex reviewer. You inherit `AGENTS.md`, the active ticket scope, approval boundaries, forbidden actions, and verification requirements. Do not edit files. Inspect files and report findings only. Do not install dependencies, run -migrations, modify git state, call deploy or release commands, or perform remote -operations. +migrations, modify git state, call deploy or release commands, use secrets, push, +publish, widen scope, or perform remote operations. Read: @@ -21,6 +21,31 @@ Question: ``` +Routing profile: + +Use the profile assigned by `expert_routing`. If none is assigned, declare +`profile_used: general_read_only_review` and keep the review narrow. Do not +invent a persona or create team ceremony; the profile is only a review lens. + +Available profiles: + +- `requirements`: acceptance criteria, user-visible behavior, scope, unknowns, + and done definition. +- `architecture`: module boundaries, interfaces, dependency direction, and + fit with existing patterns. +- `test`: test strategy, fixtures, proof commands, regression coverage, and + skipped-check justification. +- `security_privacy`: auth, permissions, secrets, privacy boundaries, data + exposure, and abuse risk. +- `ux_visual`: user-facing flows, copy, layout, accessibility, visual proof, + and interaction regressions. +- `performance_reliability`: latency, concurrency, resource use, retries, + failure modes, and operational robustness. +- `data_migration`: schema, persistence, migrations, compatibility, backfills, + and rollback risk. +- `docs_release`: setup docs, operator notes, release notes, rollout, + compatibility, and support handoff. + Focus on: - correctness risks @@ -32,6 +57,7 @@ Focus on: Output required: +- profile_used - recommendation: `proceed`, `revise_plan`, or `stop` - key findings ordered by severity - exact files/functions/routes involved diff --git a/templates/TEMPLATE.orchestrator-ticket.yaml b/templates/TEMPLATE.orchestrator-ticket.yaml index 6cc7377..4f07abf 100644 --- a/templates/TEMPLATE.orchestrator-ticket.yaml +++ b/templates/TEMPLATE.orchestrator-ticket.yaml @@ -44,6 +44,41 @@ orchestration: Read-only Codex reviewers may run in parallel only for independent questions. Implementation workers run serially unless child tickets declare disjoint write scopes. + expert_routing: + required_profiles: + - requirements + optional_profiles: + - architecture + - test + - security_privacy + - ux_visual + - performance_reliability + - data_migration + - docs_release + triggers: + - profile: requirements + when: "Acceptance criteria, child-ticket boundaries, or done behavior is ambiguous." + - profile: architecture + when: "The plan crosses module boundaries or changes shared contracts." + - profile: test + when: "The proof strategy, fixtures, or regression surface is unclear." + - profile: security_privacy + when: "Auth, secrets, permissions, user data, or privacy boundaries may change." + - profile: ux_visual + when: "User-facing UI, copy, layout, accessibility, or visual behavior changes." + - profile: performance_reliability + when: "Latency, concurrency, resource use, retries, or failure modes may change." + - profile: data_migration + when: "Schema, persistence, migrations, backfills, or data compatibility may change." + - profile: docs_release + when: "Operational docs, release notes, setup, or rollout behavior may change." + max_rounds: 2 + escalation_rule: > + Use the minimum useful read-only expert route for the chain. Do not ask + every profile by default. Stop instead of widening scope if expert findings + require files, commands, or approvals outside the orchestrator or child + tickets. + record_location: "execution_result" worker_sequence: - stage: 0 id: planning_review diff --git a/templates/TEMPLATE.ticket.yaml b/templates/TEMPLATE.ticket.yaml index a77cb80..9da7e2a 100644 --- a/templates/TEMPLATE.ticket.yaml +++ b/templates/TEMPLATE.ticket.yaml @@ -58,6 +58,33 @@ execution: planning_reviewer: null reviewer: null record_location: "execution_result" + expert_routing: + required_profiles: [] + optional_profiles: [] + triggers: + - profile: requirements + when: "Acceptance criteria, scope, or user-visible behavior is ambiguous." + - profile: architecture + when: "The change crosses module boundaries or alters shared contracts." + - profile: test + when: "Coverage, fixtures, or proof strategy is unclear or high risk." + - profile: security_privacy + when: "Auth, secrets, permissions, user data, or privacy boundaries may change." + - profile: ux_visual + when: "User-facing UI, copy, layout, accessibility, or visual behavior changes." + - profile: performance_reliability + when: "Latency, concurrency, resource use, retries, or failure modes may change." + - profile: data_migration + when: "Schema, persistence, migrations, backfills, or data compatibility may change." + - profile: docs_release + when: "Operational docs, release notes, setup, or rollout behavior may change." + max_rounds: 0 + escalation_rule: > + Use the minimum useful read-only expert route. Set max_rounds to 0 when + no expert review is required, 1 for a targeted review, or a small explicit + cap for risky tickets. Stop instead of widening scope if expert findings + require files, commands, or approvals outside this ticket. + record_location: "execution_result" debug_logging_plan: owner: scoped_worker surfaces: diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml index ebf8a6e..15cd122 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml @@ -133,17 +133,60 @@ execution: done_definition: Done when the existing expert-team workflow supports explicit profile routing, required proof has passed or justified skips are recorded, and execution_result is complete. execution_result: - status: pending - changed_files: [] - commands_run: [] - proof: [] - skipped_checks: [] + status: done + changed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - prompts/read-only-expert.md + - prompts/manager-orchestrator.md + - checklists/ticket-readiness.md + - docs/workflow.md + - README.md + commands_run: + - git status --short --branch + - sed -n '1,240p' tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml + - rg -n "expert|routing|read-only|orchestrator|profile|persona|BMAD|execution_result|allowed_files" README.md docs/workflow.md prompts/read-only-expert.md prompts/manager-orchestrator.md checklists/ticket-readiness.md templates/TEMPLATE.ticket.yaml templates/TEMPLATE.orchestrator-ticket.yaml + - sed -n '1,180p' templates/TEMPLATE.ticket.yaml + - sed -n '1,230p' templates/TEMPLATE.orchestrator-ticket.yaml + - sed -n '1,220p' prompts/read-only-expert.md + - sed -n '1,220p' prompts/manager-orchestrator.md + - sed -n '1,220p' checklists/ticket-readiness.md + - sed -n '1,180p' docs/workflow.md + - sed -n '130,280p' README.md + - rg -n "expert_routing|required_profiles|optional_profiles|max_rounds|security_privacy|profile_used|persona|BMAD|read-only|run migrations|install dependencies|deploy|release|use secrets|widen scope" templates/TEMPLATE.ticket.yaml templates/TEMPLATE.orchestrator-ticket.yaml prompts/read-only-expert.md prompts/manager-orchestrator.md checklists/ticket-readiness.md docs/workflow.md README.md + - python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in [pathlib.Path('templates/TEMPLATE.ticket.yaml'), pathlib.Path('templates/TEMPLATE.orchestrator-ticket.yaml'), pathlib.Path('tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml')]]; print('yaml ok')" + - git diff -- README.md docs/workflow.md prompts/read-only-expert.md prompts/manager-orchestrator.md checklists/ticket-readiness.md templates/TEMPLATE.ticket.yaml templates/TEMPLATE.orchestrator-ticket.yaml + - python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path('.').rglob('*.yaml')]; print('all yaml ok')" + - git diff --check + - git status --short + proof: + - Added expert_routing metadata to both ticket templates with required_profiles, optional_profiles, + triggers, max_rounds, escalation_rule, and record_location. + - Defined the reusable reviewer profile set as requirements, architecture, test, security_privacy, + ux_visual, performance_reliability, data_migration, and docs_release. + - Updated read-only expert prompt to require profile_used, keep profiles as review lenses, + reject persona-team ceremony, and preserve read-only safety boundaries. + - Updated manager prompt to choose the minimum useful expert route from risk and evidence, + avoid asking every profile by default, and stay within max_rounds. + - Updated ticket readiness, workflow docs, and README to require explicit expert routing + or an explicit not-required route with max_rounds 0. + - Repository YAML parse passed with output "all yaml ok". + - Markdown/path terminology inspection passed via rg for expert_routing, profile names, + no persona-team ceremony, and read-only safety boundary terms. + - git diff --check passed with no whitespace errors. + skipped_checks: + - Visual checks skipped because visual_gate.required is false and this ticket only changes + workflow templates, prompts, checklist, and documentation. + - Dependency install, deploy, release, migration, remote operation, and secret checks skipped + because this ticket requires none of those actions and safety boundaries forbid them. agent_memory_updates: - checked: false + checked: true updated_files: [] - notes: null + notes: "No agent/*.md files were edited; user and ticket scope exclude agent file updates for this template change." blockers: [] risks: - 'Risk: too many profiles could become ceremony; mitigate by requiring minimum useful expert route and max_rounds.' - next_recommended_step: null + - 'Residual risk: downstream repositories must update existing tickets manually if they want expert_routing metadata.' + next_recommended_step: "Review the diff, then commit the scoped ticket changes if acceptable." From be296f97d46b01c97fedc33b5c9ffd0c4e752f25 Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:14:26 +0200 Subject: [PATCH 03/11] Add SDD spec artifact templates --- checklists/ticket-readiness.md | 5 ++ docs/workflow.md | 41 +++++++++-- prompts/manager-orchestrator.md | 6 +- prompts/scoped-worker.md | 10 ++- templates/AGENTS.md.template | 19 ++++- templates/TEMPLATE.orchestrator-ticket.yaml | 23 ++++++ templates/TEMPLATE.ticket.yaml | 21 ++++++ templates/specs/TEMPLATE.design.md | 58 +++++++++++++++ templates/specs/TEMPLATE.requirements.md | 61 ++++++++++++++++ templates/specs/TEMPLATE.tasks.md | 28 ++++++++ .../TKT-2026-06-09-spec-artifact-package.yaml | 71 ++++++++++++++++--- 11 files changed, 324 insertions(+), 19 deletions(-) create mode 100644 templates/specs/TEMPLATE.design.md create mode 100644 templates/specs/TEMPLATE.requirements.md create mode 100644 templates/specs/TEMPLATE.tasks.md diff --git a/checklists/ticket-readiness.md b/checklists/ticket-readiness.md index 61862a1..8da504e 100644 --- a/checklists/ticket-readiness.md +++ b/checklists/ticket-readiness.md @@ -8,6 +8,11 @@ Use before product-code work starts. - [ ] Ticket has a single concrete `scope.goal`. - [ ] `allowed_files` and `forbidden_files` are explicit. - [ ] `in_scope` and `out_of_scope` are explicit. +- [ ] Non-trivial implementation work has `spec_refs` for requirements, design, + and tasks, or `spec_contract.quick_flow_exemption.used: true` with a concrete + reason. +- [ ] Linked spec artifacts include acceptance criteria, design boundaries, + task/proof traceability, and unresolved ambiguity handling. - [ ] `execution_intensity` is one of `standard_worker`, `expert_supported`, `bounded_expert_rounds`, or `research_only`. - [ ] `manager_role` is explicit. diff --git a/docs/workflow.md b/docs/workflow.md index 401c694..3c7cb2a 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -6,19 +6,46 @@ memory closeout for a target repository. ## Basic Workflow 1. Plan one bounded step from current repository evidence. -2. Create a ticket from the installed target template +2. For non-trivial work, create or update compact spec artifacts for + requirements, design, and tasks. For tiny quick-flow work, record the + exemption reason in the ticket. +3. Create a ticket from the installed target template `tickets/templates/TEMPLATE.ticket.yaml`. -3. Start a fresh context for ticket execution. -4. Execute only the ticket scope. -5. Run the ticket proof gates. -6. Close out with the installed target template +4. Start a fresh context for ticket execution. +5. Execute only the ticket scope. +6. Run the ticket proof gates. +7. Close out with the installed target template `tickets/templates/TEMPLATE.execution-result.yaml`. -7. Update `agent/*.md`, or record `agent memory checked: no update needed`. +8. Update `agent/*.md`, or record `agent memory checked: no update needed`. Fresh-context execution is intentional. The ticket must carry enough context, scope, proof requirements, and stop conditions for a new Codex session to do the work without relying on unstated chat history. +## Spec Artifacts + +Non-trivial implementation work starts from a compact spec package: + +- `requirements.md` captures user stories, EARS-style acceptance criteria, + Given-When-Then cases, constraints, preconditions, postconditions, + invariants, non-goals, ambiguity handling, and proof targets. +- `design.md` captures the chosen approach, impacted files, interfaces, data + flow, failure modes, security/privacy notes, test strategy, and compatibility + concerns. +- `tasks.md` captures dependency-ordered tasks with owner role, allowed files, + proof, and traceability to requirements. + +The source templates live in `templates/specs/` before installation. In a target +repository, copy them to the project-local spec location named by the ticket. +Implementation tickets link to the package with `spec_refs` and declare the +contract with `spec_contract`. + +Tiny typo, formatting, or documentation-only changes may use quick flow instead +of a full spec package. The ticket must set +`spec_contract.quick_flow_exemption.used: true` and provide a concrete reason. +Readiness fails when non-trivial implementation lacks both linked specs and a +justified exemption. + ## Ticket Chains Use a ticket chain for complex work, risky changes, visual work, migrations, or @@ -31,6 +58,8 @@ multi-stage delivery. - Create child tickets from the installed target template `tickets/templates/TEMPLATE.ticket.yaml`. - Ticket comments and execution results pass context into the next child ticket. +- Child implementation tickets link to the parent spec package, a narrowed child + spec, or an explicit quick-flow exemption. - Record worker closeout with the installed target template `tickets/templates/TEMPLATE.execution-result.yaml`. - The manager looks back at recent child ticket results before planning the next diff --git a/prompts/manager-orchestrator.md b/prompts/manager-orchestrator.md index fbe32f5..7c22638 100644 --- a/prompts/manager-orchestrator.md +++ b/prompts/manager-orchestrator.md @@ -15,13 +15,16 @@ Read first: 7. `agent/SERVICES.md` 8. `agent/CHANGELOG.md` 9. the active orchestrator ticket -10. relevant child tickets and docs +10. spec artifacts named by the active ticket +11. relevant child tickets and docs Rules: - Keep full context and own the execution order. - Do not edit product files unless the ticket explicitly assigns you that work. - Create or update child tickets before implementation starts. +- Ensure non-trivial implementation has requirements, design, and tasks specs, + or a justified quick-flow exemption, before assigning product-code work. - Run one implementation worker at a time unless scopes are explicitly disjoint. - Use read-only Codex reviewers for planning/review where required. - Choose the minimum useful `expert_routing` profile from ticket risk, changed @@ -55,5 +58,6 @@ Output required: - next worker or reviewer task - scope for that task - proof required before advancing +- spec package status, or quick-flow exemption reason - blockers or stop condition, if any - `agent` files to update or `agent memory checked: no update needed` diff --git a/prompts/scoped-worker.md b/prompts/scoped-worker.md index 2ae138f..7063bfc 100644 --- a/prompts/scoped-worker.md +++ b/prompts/scoped-worker.md @@ -12,9 +12,11 @@ Read first: 1. `AGENTS.md` 2. the assigned ticket -3. relevant `agent/*` files when durable state, decisions, known issues, +3. linked requirements, design, and tasks specs, unless the ticket records a + justified quick-flow exemption +4. relevant `agent/*` files when durable state, decisions, known issues, follow-up work, important paths, services, or changelog notes are affected -4. files inside your assigned scope +5. files inside your assigned scope Your ownership: @@ -37,6 +39,9 @@ Task: Rules: - Edit only your assigned scope. +- Treat linked spec artifacts as source of truth with `AGENTS.md`, agent memory, + and the active ticket. If they conflict or are missing without exemption, stop + and report the blocker. - Follow existing project patterns. - Add or update focused tests when the ticket requires it. - Run the assigned proof commands when available. @@ -56,6 +61,7 @@ Final response required: - changed files - commands run - proof result +- spec package used, or quick-flow exemption reason - skipped checks and why - `agent` files updated or `agent memory checked: no update needed` - blockers diff --git a/templates/AGENTS.md.template b/templates/AGENTS.md.template index 0c5766b..f87588b 100644 --- a/templates/AGENTS.md.template +++ b/templates/AGENTS.md.template @@ -19,6 +19,8 @@ product-specific assumptions in this file. - `AGENTS.md` - durable Codex agent workflow rules. - `agent/` - repo-local state, decisions, known issues, and handoff notes. - `tickets/` - scoped workflow records for non-trivial work. +- `specs/` - compact requirements, design, and task artifacts for non-trivial + feature or bugfix work. - `docs/` - reusable implementation paths, architecture notes, and proof records. - `src/`, `app/`, `pages/`, `components/`, `lib/`, `server/`, `tests/`, and @@ -37,8 +39,9 @@ Before planning or implementation work, read: 7. `agent/SERVICES.md` 8. `agent/CHANGELOG.md` 9. the newest relevant ticket in `tickets/` -10. docs named by the ticket -11. files in the ticket's allowed scope +10. specs named by the ticket +11. docs named by the ticket +12. files in the ticket's allowed scope If a referenced file is missing, stale, or conflicts with the current user instruction, report that fact instead of silently filling the gap. @@ -62,6 +65,9 @@ files. - Non-trivial planning and implementation work must be ticketed. - Planning work must create or update a scoped ticket before implementation starts. +- Non-trivial implementation work must link requirements, design, and tasks + specs, or record a justified quick-flow exemption in the ticket before + product-code work starts. - Codex implementation workers must work from the active ticket scope and keep changes inside the ticket's declared files unless the user widens scope. - After each meaningful step, record the result as a ticket comment or result @@ -117,6 +123,8 @@ ticket already grants that permission. Every implementation ticket must include these fields before product-code work: +- `spec_refs`, or a justified `spec_contract.quick_flow_exemption` +- `spec_contract` - `execution_intensity` - `manager_role` - `worker_sequence` @@ -138,6 +146,13 @@ The `test_plan` or closeout proof must include an agent-memory update check for `agent/` files whenever the ticket changes durable project state, decisions, known issues, setup paths, service assumptions, or follow-up work. +For non-trivial work, the ticket's `spec_refs` point to the requirements, +design, and tasks artifacts that act as source of truth with `AGENTS.md` and +agent memory. The specs must keep acceptance criteria, design boundaries, +allowed-file tasks, proof, and requirement traceability aligned. Tiny quick-flow +changes may skip full specs only when the ticket records a concrete exemption +reason. + The `test_plan` must list concrete checks that decide whether the ticket may be marked done. For web applications, use relevant repo-local checks such as: diff --git a/templates/TEMPLATE.orchestrator-ticket.yaml b/templates/TEMPLATE.orchestrator-ticket.yaml index 4f07abf..649dcd0 100644 --- a/templates/TEMPLATE.orchestrator-ticket.yaml +++ b/templates/TEMPLATE.orchestrator-ticket.yaml @@ -31,6 +31,26 @@ context: - "agent/SERVICES.md" - "agent/CHANGELOG.md" +spec_refs: + requirements: "specs//requirements.md" + design: "specs//design.md" + tasks: "specs//tasks.md" + source_of_truth: + - "AGENTS.md" + - "agent/*.md" + - "this orchestrator ticket" + +spec_contract: + required: true + quick_flow_exemption: + used: false + reason: null + requirements_format: "EARS/Given-When-Then acceptance criteria with non-goals and ambiguity log." + design_format: "Architecture, impacted files, interfaces, data flow, failure modes, security/privacy notes, and test strategy." + tasks_format: "Dependency-ordered tasks with owner role, allowed files, proof, and requirement traceability." + child_ticket_rule: "Child implementation tickets link to these specs, a narrowed derived spec, or record a justified quick-flow exemption." + traceability_required: true + orchestration: execution_intensity: bounded_expert_rounds manager_role: > @@ -118,6 +138,7 @@ child_ticket_policy: requirements: - "Each child ticket has one owner, one scope, and one done definition." - "Each child ticket declares allowed_files and forbidden_files." + - "Each non-trivial child ticket links to spec artifacts or records a justified quick-flow exemption." - "Each child ticket records execution_result before it can close." - "The manager reconciles child results into this orchestrator ticket." @@ -131,6 +152,7 @@ debug_logging_plan: correlation_policy: "Use ticket id, route, test name, or request id in proof notes." test_plan: + - "Read linked spec artifacts, or verify a justified quick-flow exemption." - "Parse this ticket and all child tickets as YAML." - "Run repo-local lint/typecheck/build checks before final closeout." - "Run targeted tests for each child ticket." @@ -138,6 +160,7 @@ test_plan: - "Check whether agent memory files need updates and record updated files or `agent memory checked: no update needed`." proof_gates: + - "Non-trivial implementation work has linked requirements/design/tasks specs, or this orchestrator records a justified quick-flow exemption." - "All required child tickets are done or explicitly deferred with blockers." - "Final verifier result is recorded." - "No unresolved blocker remains for the requested outcome." diff --git a/templates/TEMPLATE.ticket.yaml b/templates/TEMPLATE.ticket.yaml index 9da7e2a..6021212 100644 --- a/templates/TEMPLATE.ticket.yaml +++ b/templates/TEMPLATE.ticket.yaml @@ -22,6 +22,25 @@ context: relevant_prior_work: - "Link or path to prior ticket/doc, or 'none'." +spec_refs: + requirements: "specs//requirements.md" + design: "specs//design.md" + tasks: "specs//tasks.md" + source_of_truth: + - "AGENTS.md" + - "agent/*.md" + - "this ticket" + +spec_contract: + required: true + quick_flow_exemption: + used: false + reason: null + requirements_format: "EARS/Given-When-Then acceptance criteria with non-goals and ambiguity log." + design_format: "Architecture, impacted files, interfaces, data flow, failure modes, security/privacy notes, and test strategy." + tasks_format: "Dependency-ordered tasks with owner role, allowed files, proof, and requirement traceability." + traceability_required: true + scope: goal: > One concrete outcome for this ticket. @@ -93,6 +112,7 @@ execution: - "Test output for failing checks." temporary_logging_policy: "Remove or gate temporary logs before done." test_plan: + - "Read linked spec artifacts, or verify a justified quick-flow exemption." - "Parse this ticket as YAML." - "Run formatter/lint command if present." - "Run typecheck command if present." @@ -100,6 +120,7 @@ execution: - "Run build command if present." - "Check whether agent files need updates and record the result." proof_gates: + - "Non-trivial implementation work has linked requirements/design/tasks specs, or this ticket records a justified quick-flow exemption." - "Implementation matches desired behavior." - "Relevant automated checks pass or skipped checks are justified." - "Agent-memory update check is recorded." diff --git a/templates/specs/TEMPLATE.design.md b/templates/specs/TEMPLATE.design.md new file mode 100644 index 0000000..640860c --- /dev/null +++ b/templates/specs/TEMPLATE.design.md @@ -0,0 +1,58 @@ +# Design + +Feature or fix: `` + +## Overview + +Describe the chosen approach and why it satisfies the requirements without +widening the ticket scope. + +## Architecture + +- Entry points: `` +- Components changed: `` +- Components reused: `` +- Components intentionally untouched: `` + +## Impacted Files + +| Path | Change | Requirement IDs | +| --- | --- | --- | +| `` | `` | `` | + +## Interfaces + +- Inputs: `` +- Outputs: `` +- Contracts: `` + +## Data Flow + +```text + -> -> +``` + +## Failure Modes + +| Failure | Expected handling | Proof | +| --- | --- | --- | +| `` | `` | `` | + +## Security And Privacy + +- Secrets: `` +- Permissions: `` +- User data: `` +- Local/private paths: `` + +## Test Strategy + +| Requirement ID | Test or proof | Notes | +| --- | --- | --- | +| REQ-001 | `` | `` | + +## Rollout And Compatibility + +- Compatibility: `` +- Rollback: `` +- Documentation: `` diff --git a/templates/specs/TEMPLATE.requirements.md b/templates/specs/TEMPLATE.requirements.md new file mode 100644 index 0000000..be7ca50 --- /dev/null +++ b/templates/specs/TEMPLATE.requirements.md @@ -0,0 +1,61 @@ +# Requirements + +Feature or fix: `` + +## Summary + +State the user-visible outcome in one or two paragraphs. Use verified facts only; +mark unknowns explicitly. + +## User Stories + +- As a ``, I want `` so that ``. + +## Acceptance Criteria + +Use EARS-style statements where possible: + +- When ``, the system shall ``. +- If ``, the system shall ``. +- While ``, the system shall ``. + +## Given-When-Then Cases + +```text +Given +When +Then +And +``` + +## Constraints + +- `` + +## Preconditions + +- `` + +## Postconditions + +- `` + +## Invariants + +- `` + +## Non-Goals + +- `` + +## Ambiguity Log + +| Question | Current handling | Owner | +| --- | --- | --- | +| `` | `` | `` | + +## Traceability + +| Requirement ID | Acceptance criteria | Proof target | +| --- | --- | --- | +| REQ-001 | `` | `` | diff --git a/templates/specs/TEMPLATE.tasks.md b/templates/specs/TEMPLATE.tasks.md new file mode 100644 index 0000000..93c0116 --- /dev/null +++ b/templates/specs/TEMPLATE.tasks.md @@ -0,0 +1,28 @@ +# Tasks + +Feature or fix: `` + +## Task List + +Order tasks by dependency. Keep each task small enough for one scoped worker. + +| Task ID | Depends on | Owner role | Allowed files | Requirement IDs | Proof | +| --- | --- | --- | --- | --- | --- | +| TASK-001 | none | `` | `` | `` | `` | + +## Implementation Notes + +- `` +- `` + +## Proof Map + +| Proof item | Covers | Command or inspection | +| --- | --- | --- | +| `` | `` | `` | + +## Handoff Notes + +- Changed files must remain within task `allowed_files`. +- Record skipped checks with reasons. +- Record agent memory update check before closing the ticket. diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml index 8cd2d0f..5aa0a8f 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml @@ -132,16 +132,71 @@ execution: done_definition: Done when the scoped workflow/template improvement is implemented, required proof has passed or justified skips are recorded, and execution_result is complete. execution_result: - status: pending - changed_files: [] - commands_run: [] - proof: [] - skipped_checks: [] + status: done + changed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml + - templates/specs/TEMPLATE.requirements.md + - templates/specs/TEMPLATE.design.md + - templates/specs/TEMPLATE.tasks.md + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - checklists/ticket-readiness.md + - docs/workflow.md + - templates/AGENTS.md.template + - prompts/manager-orchestrator.md + - prompts/scoped-worker.md + commands_run: + - 'git status --short --branch' + - 'sed -n ''1,240p'' tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml' + - 'rg --files templates checklists docs prompts | sort' + - 'sed -n ''1,260p'' templates/TEMPLATE.ticket.yaml' + - 'sed -n ''1,260p'' templates/TEMPLATE.orchestrator-ticket.yaml' + - 'sed -n ''1,260p'' checklists/ticket-readiness.md' + - 'sed -n ''1,280p'' docs/workflow.md' + - 'sed -n ''1,320p'' templates/AGENTS.md.template' + - 'sed -n ''1,320p'' prompts/manager-orchestrator.md' + - 'sed -n ''1,320p'' prompts/scoped-worker.md' + - 'find templates/specs -maxdepth 2 -type f -print 2>/dev/null | sort' + - 'git diff -- templates/TEMPLATE.ticket.yaml templates/TEMPLATE.orchestrator-ticket.yaml checklists/ticket-readiness.md docs/workflow.md templates/AGENTS.md.template prompts/manager-orchestrator.md prompts/scoped-worker.md templates/specs/TEMPLATE.requirements.md templates/specs/TEMPLATE.design.md templates/specs/TEMPLATE.tasks.md' + - 'rg -n "spec_refs|spec_contract|requirements\.md|design\.md|tasks\.md|quick-flow|quick flow|templates/specs" templates checklists docs prompts tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml' + - 'find templates/specs -maxdepth 1 -type f -print | sort' + - 'python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path(''.'').rglob(''*.yaml'')]; print(''parsed yaml files'')"' + - 'git diff --check' + - 'rg -n "templates/specs/TEMPLATE\.(requirements|design|tasks)\.md|spec_refs|spec_contract|quick-flow exemption|requirements/design/tasks" templates checklists docs prompts tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml' + - 'rg -n "ticket|workflow|template|spec|requirements|design|tasks|AGENTS|agent memory" README.md agent 2>/dev/null' + - 'git status --short' + - 'git diff --name-only' + - 'git diff -- tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml | sed -n ''1,260p''' + - 'python -c "import yaml; p=''tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml''; data=yaml.safe_load(open(p)); print(data[''execution_result''][''status'']); print(len(data[''execution_result''][''changed_files''])); print(data[''execution_result''][''agent_memory_updates''][''checked'']))"' + proof: + - Added concise generic requirements, design, and tasks templates under templates/specs with acceptance + criteria, Given-When-Then cases, constraints, invariants, ambiguity log, architecture, impacted files, + interfaces, data flow, failure modes, security/privacy notes, task ownership, allowed files, proof, + and requirement traceability. + - Added spec_refs and spec_contract fields to implementation and orchestrator ticket templates, including + quick-flow exemption support and traceability requirements. + - Updated readiness checklist so non-trivial implementation fails readiness without linked specs or a + justified quick-flow exemption. + - Updated workflow docs, AGENTS template, manager prompt, and scoped-worker prompt to treat linked specs + as source of truth while preserving existing scoped-worker and read-only expert routing boundaries. + - 'YAML validation passed: python parsed every *.yaml file in the repository.' + - 'Whitespace validation passed: git diff --check returned no output.' + - 'Reference check passed: rg found the new spec contract and quick-flow references in the scoped templates, + checklist, docs, prompts, and ticket.' + skipped_checks: + - README.md likely needs a follow-up installation-map mention for templates/specs, but README.md is outside + this ticket allowed_files and was not edited. + - No dependency, build, lint, or test command was run because this workflow/template change has no package + install or runtime code path in scope; YAML parse, reference inspection, and git diff --check were the + applicable proof gates. agent_memory_updates: - checked: false + checked: true updated_files: [] - notes: null + notes: 'agent memory checked: no update needed; user explicitly forbade agent/*.md edits for this ticket, + and this template-scope change is recorded in the ticket result instead.' blockers: [] risks: - 'Risk: over-specification can slow tiny work; mitigate with quick-flow exemption and escalation ticket.' - next_recommended_step: null + - 'README.md install-path documentation may lag the new spec templates until a separate docs-scoped ticket + allows README edits.' + next_recommended_step: 'Open a separate docs ticket for README.md if the install mapping should list templates/specs.' From fd8856cd5aed321b34d114e61a5b23f8080401cf Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:18:29 +0200 Subject: [PATCH 04/11] Add delta spec lifecycle --- checklists/closeout.md | 4 ++ docs/spec_lifecycle.md | 65 +++++++++++++++++++ docs/workflow.md | 33 +++++++++- prompts/final-verifier.md | 11 ++++ templates/AGENTS.md.template | 23 ++++++- templates/specs/TEMPLATE.delta-spec.md | 59 +++++++++++++++++ .../TKT-2026-06-09-delta-spec-lifecycle.yaml | 53 ++++++++++++--- 7 files changed, 236 insertions(+), 12 deletions(-) create mode 100644 docs/spec_lifecycle.md create mode 100644 templates/specs/TEMPLATE.delta-spec.md diff --git a/checklists/closeout.md b/checklists/closeout.md index abcc66c..9e4b744 100644 --- a/checklists/closeout.md +++ b/checklists/closeout.md @@ -16,6 +16,10 @@ Use before marking a ticket `done`. - [ ] Browser/UI proof was collected when user-facing UI changed. - [ ] Screenshots/recordings were captured when visual gate required them. - [ ] Temporary logs, debug UI, fixtures, and probes were removed or gated. +- [ ] Significant behavior/API/data/workflow changes checked the delta-spec lifecycle. +- [ ] Accepted delta-spec `ADDED`, `MODIFIED`, and `REMOVED` items were merged into `specs/current/**`, or a deferred spec update blocker is recorded. +- [ ] Closed delta-spec change package was archived under `specs/archive/-/`, or the archive deferral is recorded. +- [ ] Parallel spec conflicts for the same `specs/current/**` path or requirement ID were checked and reconciled or recorded as blockers. - [ ] `agent/STATE.md` was checked and updated if current state changed. - [ ] `agent/DECISIONS.md` was checked and updated if a durable decision was made. - [ ] `agent/KNOWN_ISSUES.md` was checked and updated if a repeatable hazard remains. diff --git a/docs/spec_lifecycle.md b/docs/spec_lifecycle.md new file mode 100644 index 0000000..4d2ddbb --- /dev/null +++ b/docs/spec_lifecycle.md @@ -0,0 +1,65 @@ +# Spec Lifecycle + +Use this lifecycle for significant behavior, API, data, workflow, or durable +documentation changes. It keeps implemented behavior anchored to current specs +without adding a CLI or external tool dependency. + +## Repository Layout + +Target repositories should use this local layout: + +- `specs/current/**` contains the durable current specs for implemented + behavior, contracts, workflows, and important constraints. +- `specs/changes//proposal.md` explains why the change exists, the + intended user or maintainer outcome, and the boundaries. +- `specs/changes//delta-spec.md` records spec changes in `ADDED`, + `MODIFIED`, and `REMOVED` sections. +- `specs/changes//design.md` records the chosen implementation + approach when the change is non-trivial. +- `specs/changes//tasks.md` records dependency-ordered scoped work + and proof. +- `specs/archive/-/**` stores accepted, superseded, or closed + change packages. + +## Propose + +Create `specs/changes//` before implementation for significant +changes. Copy `templates/specs/TEMPLATE.delta-spec.md` to +`specs/changes//delta-spec.md` and fill: + +- `ADDED` for new capabilities, guarantees, constraints, proof gates, or + workflow rules. +- `MODIFIED` for existing current-spec behavior or contracts that will change. +- `REMOVED` for capabilities, requirements, constraints, or proof rules that + will no longer apply. + +The ticket should link the delta spec through `spec_refs`, keep +`spec_contract` aligned with the requirements/design/tasks package, and name the +`specs/current/**` files expected to change. Tiny quick-flow work may skip this +only when the ticket records a concrete exemption. + +## Apply + +During implementation, treat the delta spec as the intended contract for the +change. Keep edits inside the ticket `allowed_files`. If the implementation +needs to change a current spec or delta package outside scope, stop and revise +the ticket or create a follow-up ticket. + +Parallel work must stop for reconciliation when two active tickets touch the +same `specs/current/**` file or the same requirement ID. Reconcile by merging +the intended current-spec wording, splitting ownership, or recording a blocker. + +## Archive + +Before a significant ticket is marked done: + +1. Check implementation against each `ADDED`, `MODIFIED`, and `REMOVED` item. +2. Merge accepted changes into `specs/current/**`. +3. Move or copy the closed change package to + `specs/archive/-/**`. +4. Record proof, changed files, skipped checks, blockers, and risks in the + ticket `execution_result`. + +If the current-spec update or archive step cannot be completed inside scope, +leave the ticket non-done or record a concrete deferred spec update blocker, +depending on the ticket stop conditions and manager decision. diff --git a/docs/workflow.md b/docs/workflow.md index 3c7cb2a..9a56165 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -7,8 +7,10 @@ memory closeout for a target repository. 1. Plan one bounded step from current repository evidence. 2. For non-trivial work, create or update compact spec artifacts for - requirements, design, and tasks. For tiny quick-flow work, record the - exemption reason in the ticket. + requirements, design, and tasks. For significant behavior, API, data, or + workflow changes, also create a delta spec under `specs/changes//` + or record why the lifecycle does not apply. For tiny quick-flow work, record + the exemption reason in the ticket. 3. Create a ticket from the installed target template `tickets/templates/TEMPLATE.ticket.yaml`. 4. Start a fresh context for ticket execution. @@ -34,12 +36,36 @@ Non-trivial implementation work starts from a compact spec package: concerns. - `tasks.md` captures dependency-ordered tasks with owner role, allowed files, proof, and traceability to requirements. +- `delta-spec.md` captures durable spec changes in `ADDED`, `MODIFIED`, and + `REMOVED` sections so implementation can be checked against the intended + lifecycle update. The source templates live in `templates/specs/` before installation. In a target repository, copy them to the project-local spec location named by the ticket. Implementation tickets link to the package with `spec_refs` and declare the contract with `spec_contract`. +For ongoing maintenance, use this target repository layout: + +- `specs/current/**` contains the durable current specs for implemented + behavior, contracts, workflows, and important constraints. +- `specs/changes//proposal.md` explains the change intent and + scope. +- `specs/changes//delta-spec.md` records `ADDED`, `MODIFIED`, and + `REMOVED` updates against `specs/current/**`. +- `specs/changes//design.md` and `tasks.md` hold the implementation + plan when the change is non-trivial. +- `specs/archive/-/**` stores accepted or closed delta-spec + packages after closeout. + +At closeout, significant changes must either merge the delta into +`specs/current/**` and archive the change package, or record a deferred spec +update blocker in the ticket result. Parallel tickets that touch the same +current spec path or requirement ID must stop and reconcile before either ticket +archives its delta. + +See `docs/spec_lifecycle.md` for the propose/apply/archive lifecycle. + Tiny typo, formatting, or documentation-only changes may use quick flow instead of a full spec package. The ticket must set `spec_contract.quick_flow_exemption.used: true` and provide a concrete reason. @@ -60,6 +86,9 @@ multi-stage delivery. - Ticket comments and execution results pass context into the next child ticket. - Child implementation tickets link to the parent spec package, a narrowed child spec, or an explicit quick-flow exemption. +- Child tickets that materially change durable behavior should link to the + relevant `specs/changes//delta-spec.md` and identify any + `specs/current/**` files they intend to update. - Record worker closeout with the installed target template `tickets/templates/TEMPLATE.execution-result.yaml`. - The manager looks back at recent child ticket results before planning the next diff --git a/prompts/final-verifier.md b/prompts/final-verifier.md index b325a6b..8260b94 100644 --- a/prompts/final-verifier.md +++ b/prompts/final-verifier.md @@ -15,6 +15,9 @@ Read: 4. changed files 5. test output or proof artifacts 6. relevant `agent/*` files when validating memory updates or deferrals +7. relevant `specs/current/**`, `specs/changes/**/delta-spec.md`, and + `specs/archive/**` files when the ticket changes durable behavior, + contracts, workflows, data, APIs, or documentation Verify: @@ -25,6 +28,13 @@ Verify: - skipped checks have concrete reasons - `agent` memory update check is recorded and any needed `agent` updates were made or explicitly deferred +- implementation matches the delta-spec `ADDED`, `MODIFIED`, and `REMOVED` + intent when a delta spec is in scope +- accepted delta-spec updates were merged into `specs/current/**` and archived + under `specs/archive/**`, or a concrete deferred spec update blocker is + recorded +- parallel changes touching the same current spec path or requirement ID were + reconciled or left as blockers - user-visible behavior was inspected when relevant - execution_result is complete and honest @@ -34,5 +44,6 @@ Output required: - blocking issues with file references - missing proof - missing `agent` memory updates +- missing or deferred current spec/archive updates - residual risks - whether the ticket may be marked done diff --git a/templates/AGENTS.md.template b/templates/AGENTS.md.template index f87588b..177e5bb 100644 --- a/templates/AGENTS.md.template +++ b/templates/AGENTS.md.template @@ -19,8 +19,11 @@ product-specific assumptions in this file. - `AGENTS.md` - durable Codex agent workflow rules. - `agent/` - repo-local state, decisions, known issues, and handoff notes. - `tickets/` - scoped workflow records for non-trivial work. -- `specs/` - compact requirements, design, and task artifacts for non-trivial - feature or bugfix work. +- `specs/current/` - durable current specs for implemented behavior, contracts, + workflows, and important constraints. +- `specs/changes//` - proposed change specs, typically + `proposal.md`, `delta-spec.md`, `design.md`, and `tasks.md`. +- `specs/archive/` - accepted or closed change specs kept for history. - `docs/` - reusable implementation paths, architecture notes, and proof records. - `src/`, `app/`, `pages/`, `components/`, `lib/`, `server/`, `tests/`, and @@ -68,6 +71,9 @@ files. - Non-trivial implementation work must link requirements, design, and tasks specs, or record a justified quick-flow exemption in the ticket before product-code work starts. +- Significant behavior, API, data, workflow, or durable documentation changes + must link a delta spec under `specs/changes//delta-spec.md` or + record why the delta-spec lifecycle does not apply. - Codex implementation workers must work from the active ticket scope and keep changes inside the ticket's declared files unless the user widens scope. - After each meaningful step, record the result as a ticket comment or result @@ -82,6 +88,13 @@ files. update. If they do, update them inside the ticket scope or record why the update is deferred. If they do not, record `agent memory checked: no update needed` in the ticket result. +- Before closing significant changes, merge accepted `ADDED`, `MODIFIED`, and + `REMOVED` delta-spec items into `specs/current/**` and archive the change + package under `specs/archive/-/`, or record a deferred spec + update blocker in the ticket result. +- If parallel tickets touch the same `specs/current/**` file or requirement ID, + stop and reconcile the conflict before implementation continues or either + ticket archives its delta. - Stage only files in the ticket scope plus the ticket record. Do not use bulk staging such as `git add -A`. - Do not revert changes you did not make unless explicitly requested. @@ -153,6 +166,12 @@ allowed-file tasks, proof, and requirement traceability aligned. Tiny quick-flow changes may skip full specs only when the ticket records a concrete exemption reason. +For significant changes, `spec_refs` should also include the delta spec. The +delta spec uses `ADDED`, `MODIFIED`, and `REMOVED` sections to describe how +`specs/current/**` must change. Final verification checks that implementation +matches the delta intent and that the current spec update was merged, archived, +or explicitly deferred with a blocker. + The `test_plan` must list concrete checks that decide whether the ticket may be marked done. For web applications, use relevant repo-local checks such as: diff --git a/templates/specs/TEMPLATE.delta-spec.md b/templates/specs/TEMPLATE.delta-spec.md new file mode 100644 index 0000000..becc455 --- /dev/null +++ b/templates/specs/TEMPLATE.delta-spec.md @@ -0,0 +1,59 @@ +# Delta Spec + +Change ID: `` + +## Purpose + +Describe the significant behavior, API, workflow, data, or documentation change +this delta proposes. Keep it bounded to the active ticket or ticket chain. + +## Current Spec References + +| Current spec | Capability or contract | Expected update | +| --- | --- | --- | +| `specs/current/.md` | `` | `` | + +## ADDED + +List new capabilities, guarantees, constraints, proof gates, or workflow rules. +Use stable requirement IDs when this delta supports implementation work. + +- `REQ-001`: `` + +## MODIFIED + +List current spec statements that change. Reference the current spec path and +the intended new wording or behavior. + +| Current spec | Existing statement or section | New behavior | +| --- | --- | --- | +| `specs/current/.md` | `
` | `` | + +## REMOVED + +List current spec statements, capabilities, tasks, or proof rules that are being +retired. Include the compatibility or migration note when removal affects users +or dependent work. + +| Current spec | Removed item | Reason and compatibility note | +| --- | --- | --- | +| `specs/current/.md` | `` | `` | + +## Conflicts And Dependencies + +- Parallel changes touching the same `specs/current/**` file or same + requirement ID must stop and reconcile before implementation or archive. +- Depends on: `` +- Blocks: `` + +## Proof And Archive Plan + +| Proof target | Covers | Command or inspection | +| --- | --- | --- | +| `` | `` | `` | + +Closeout result: + +- [ ] Delta was merged into `specs/current/**`. +- [ ] Delta was moved or copied to `specs/archive/-/`. +- [ ] Spec update was deferred with a blocker recorded in the ticket. diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml index e3d1602..99e5fa0 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml @@ -124,17 +124,54 @@ execution: done_definition: Done when the scoped workflow/template improvement is implemented, required proof has passed or justified skips are recorded, and execution_result is complete. execution_result: - status: pending - changed_files: [] - commands_run: [] - proof: [] - skipped_checks: [] + status: done + changed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml + - templates/specs/TEMPLATE.delta-spec.md + - docs/spec_lifecycle.md + - docs/workflow.md + - templates/AGENTS.md.template + - checklists/closeout.md + - prompts/final-verifier.md + commands_run: + - "pwd && git status --short --branch" + - "rg --files -g 'AGENTS.md' -g 'tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml' -g 'docs/spec_lifecycle.md' -g 'docs/workflow.md' -g 'templates/AGENTS.md.template' -g 'checklists/closeout.md' -g 'prompts/final-verifier.md' -g 'templates/specs/**'" + - "sed -n '1,260p' tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml" + - "sed -n '1,260p' docs/workflow.md" + - "sed -n '1,260p' docs/spec_lifecycle.md" + - "sed -n '1,260p' templates/AGENTS.md.template" + - "sed -n '1,260p' checklists/closeout.md" + - "sed -n '1,260p' prompts/final-verifier.md" + - "sed -n '1,260p' templates/specs/TEMPLATE.requirements.md" + - "sed -n '1,260p' templates/specs/TEMPLATE.design.md" + - "sed -n '1,260p' templates/specs/TEMPLATE.tasks.md" + - "git diff -- docs/workflow.md templates/AGENTS.md.template checklists/closeout.md prompts/final-verifier.md docs/spec_lifecycle.md templates/specs/TEMPLATE.delta-spec.md" + - "rg -n \"delta-spec|specs/current|specs/changes|specs/archive|ADDED|MODIFIED|REMOVED|spec_contract|spec_refs|expert_routing|read-only|approval\" docs templates checklists prompts tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml" + - "python -c \"import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path('.').rglob('*.yaml')]\"" + - "python -c \"import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path('.').rglob('*.yaml')]\"" + - "git diff --check" + - "if rg -n \"[ \\t]+$\" docs/spec_lifecycle.md templates/specs/TEMPLATE.delta-spec.md; then exit 1; else echo \"no trailing whitespace\"; fi" + proof: + - "Added `templates/specs/TEMPLATE.delta-spec.md` with `ADDED`, `MODIFIED`, and `REMOVED` sections, current-spec references, conflict handling, proof mapping, and archive closeout." + - "Added `docs/spec_lifecycle.md` documenting propose, apply, and archive in repo-local terms without any CLI or dependency requirement." + - "Updated `docs/workflow.md` with the target `specs/current/**`, `specs/changes//{proposal.md,delta-spec.md,design.md,tasks.md}`, and `specs/archive/**` layout plus closeout and conflict rules." + - "Updated `templates/AGENTS.md.template` to preserve scoped-worker safety, `spec_refs`/`spec_contract`, and expert routing while adding delta-spec obligations for significant changes." + - "Updated `checklists/closeout.md` with lifecycle, merge/archive, and parallel-spec-conflict checks." + - "Updated `prompts/final-verifier.md` so verification checks implementation against delta-spec intent and current spec/archive handling or a deferred blocker." + - "Initial YAML parse failed on unquoted ticket proof entries containing backticks; the ticket formatting was corrected and the same YAML parse command passed on rerun." + - "YAML parse check passed for repository `*.yaml` files." + - "`git diff --check` passed." + - "Focused trailing-whitespace check for new untracked Markdown files passed with no matches." + skipped_checks: + - No formatter, lint, typecheck, unit test, build, or browser check was run because this ticket only changes Markdown/YAML workflow templates and no repo-local command for those checks is required by the ticket. + - No README or ticket-template edits were made because they are outside this ticket's allowed_files. agent_memory_updates: - checked: false + checked: true updated_files: [] - notes: null + notes: "agent memory checked: no update needed; this template ticket explicitly forbids editing agent/*.md, and no target-repo runtime state was changed." blockers: [] risks: - 'Risk: maintaining current specs creates overhead; mitigate by requiring it only for significant behavior/API/workflow changes.' - next_recommended_step: null + - 'Risk: target repositories must adopt the specs/current, specs/changes, and specs/archive layout consistently; mitigate through the updated workflow, AGENTS template, closeout checklist, and final verifier prompt.' + next_recommended_step: "Use the updated lifecycle on the next significant target-repository change and archive/merge the delta spec during closeout." From 667d6f0a503ece104591ab39dbefaafba4692190 Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:21:39 +0200 Subject: [PATCH 05/11] Add spec drift verifier --- checklists/closeout.md | 4 + checklists/spec-drift.md | 30 +++++++ prompts/final-verifier.md | 15 ++++ prompts/spec-drift-verifier.md | 72 +++++++++++++++ templates/TEMPLATE.execution-result.yaml | 9 ++ templates/TEMPLATE.ticket.yaml | 6 ++ .../TKT-2026-06-09-spec-drift-verifier.yaml | 89 +++++++++++++++++-- 7 files changed, 216 insertions(+), 9 deletions(-) create mode 100644 checklists/spec-drift.md create mode 100644 prompts/spec-drift-verifier.md diff --git a/checklists/closeout.md b/checklists/closeout.md index 9e4b744..66a05ee 100644 --- a/checklists/closeout.md +++ b/checklists/closeout.md @@ -20,6 +20,10 @@ Use before marking a ticket `done`. - [ ] Accepted delta-spec `ADDED`, `MODIFIED`, and `REMOVED` items were merged into `specs/current/**`, or a deferred spec update blocker is recorded. - [ ] Closed delta-spec change package was archived under `specs/archive/-/`, or the archive deferral is recorded. - [ ] Parallel spec conflicts for the same `specs/current/**` path or requirement ID were checked and reconciled or recorded as blockers. +- [ ] Spec drift verification ran for non-trivial tickets, or a justified `spec_contract.quick_flow_exemption` is recorded. +- [ ] Spec drift verifier stayed read-only and any material findings were left for separate scoped repair/spec/test/doc tickets. +- [ ] `execution_result.spec_alignment` records `verdict`, `checked_specs`, `drift_findings`, and `required_followups`, or the quick-flow exemption reason. +- [ ] Implemented-but-unspecified, specified-but-unimplemented, tests-missing-for-acceptance, docs-outdated, and changed-behavior-not-approved questions were checked. - [ ] `agent/STATE.md` was checked and updated if current state changed. - [ ] `agent/DECISIONS.md` was checked and updated if a durable decision was made. - [ ] `agent/KNOWN_ISSUES.md` was checked and updated if a repeatable hazard remains. diff --git a/checklists/spec-drift.md b/checklists/spec-drift.md new file mode 100644 index 0000000..7f15b17 --- /dev/null +++ b/checklists/spec-drift.md @@ -0,0 +1,30 @@ +# Spec Drift Checklist + +Use before final verification for non-trivial tickets unless +`spec_contract.quick_flow_exemption.used: true` is justified in the ticket. + +- [ ] The verifier stayed read-only and did not repair code, rewrite specs, + update docs, or change ticket fields. +- [ ] Requirements acceptance criteria were compared with the implemented diff + and proof. +- [ ] Design constraints were compared with changed files, interfaces, data + flow, failure modes, and security/privacy notes. +- [ ] Tasks were compared with completed work, skipped work, and + `execution_result`. +- [ ] Delta-spec `ADDED`, `MODIFIED`, and `REMOVED` items were checked when a + delta spec was in scope. +- [ ] Current spec updates, archives, or explicit deferrals were checked when + durable behavior changed. +- [ ] Implemented-but-unspecified behavior was checked. +- [ ] Specified-but-unimplemented behavior was checked. +- [ ] Tests-missing-for-acceptance criteria were checked. +- [ ] Docs-outdated risk was checked. +- [ ] Changed behavior not approved by ticket/specs/decisions was checked. +- [ ] Drift findings list concrete file references and mark blocking versus + non-blocking impact. +- [ ] Required follow-ups are separate scoped repair/spec/test/doc tickets, not + auto-repairs by the verifier. +- [ ] `execution_result.spec_alignment.verdict` is `pass`, `pass_with_risk`, + or `fail`. +- [ ] `execution_result.spec_alignment.checked_specs`, + `drift_findings`, and `required_followups` are complete. diff --git a/prompts/final-verifier.md b/prompts/final-verifier.md index 8260b94..3491064 100644 --- a/prompts/final-verifier.md +++ b/prompts/final-verifier.md @@ -18,6 +18,9 @@ Read: 7. relevant `specs/current/**`, `specs/changes/**/delta-spec.md`, and `specs/archive/**` files when the ticket changes durable behavior, contracts, workflows, data, APIs, or documentation +8. `execution_result.spec_alignment` and the spec drift verifier output for + non-trivial tickets, unless the ticket records a justified + `spec_contract.quick_flow_exemption` Verify: @@ -35,6 +38,16 @@ Verify: recorded - parallel changes touching the same current spec path or requirement ID were reconciled or left as blockers +- non-trivial tickets include a machine-readable + `execution_result.spec_alignment` block with `verdict`, `checked_specs`, + `drift_findings`, and `required_followups`, or a documented quick-flow + exemption +- spec drift verifier remained read-only and did not auto-repair code, rewrite + specs, or close findings without a separate scoped repair ticket +- implementation, tests, docs, ticket result, and linked specs are aligned, with + implemented-but-unspecified, specified-but-unimplemented, + tests-missing-for-acceptance, docs-outdated, and unapproved behavior findings + recorded as blockers or risks - user-visible behavior was inspected when relevant - execution_result is complete and honest @@ -43,7 +56,9 @@ Output required: - verdict: `pass`, `pass_with_risk`, or `fail` - blocking issues with file references - missing proof +- missing or failing spec_alignment - missing `agent` memory updates - missing or deferred current spec/archive updates +- required follow-up tickets for material spec drift - residual risks - whether the ticket may be marked done diff --git a/prompts/spec-drift-verifier.md b/prompts/spec-drift-verifier.md new file mode 100644 index 0000000..6d82ac6 --- /dev/null +++ b/prompts/spec-drift-verifier.md @@ -0,0 +1,72 @@ +# Spec Drift Verifier Prompt + +Use after implementation proof is available and before final closeout for +non-trivial tickets. This verifier is read-only. It must not edit product code, +rewrite specs, update tickets, repair tests, or change documentation. Material +findings require a separate scoped repair ticket with its own allowed files and +approval boundaries. + +You inherit `AGENTS.md`, the active ticket scope, approval boundaries, +forbidden actions, `spec_refs`, `spec_contract`, delta-spec lifecycle rules, and +expert routing constraints. + +Read: + +1. `AGENTS.md` +2. active ticket and `execution_result` +3. linked requirements, design, and tasks specs unless the ticket records a + justified `spec_contract.quick_flow_exemption` +4. relevant `specs/changes/**/delta-spec.md`, `specs/current/**`, and + `specs/archive/**` artifacts when the ticket changes durable behavior, + contracts, workflows, data, APIs, or documentation +5. changed files and diff +6. tests, logs, screenshots, or other proof artifacts named by the ticket +7. documentation changed by the ticket or documentation that should have changed + +Compare: + +- requirements acceptance criteria against implemented behavior and proof +- design constraints against changed files, interfaces, data flow, and failure + handling +- tasks against completed work and skipped work +- delta-spec `ADDED`, `MODIFIED`, and `REMOVED` items against implementation, + current-spec updates, archives, and recorded deferrals +- changed code and tests against approved scope +- changed or affected docs against changed behavior +- `execution_result` claims against the actual diff and proof + +Required questions: + +- Was anything implemented that is not specified or approved by the ticket, + linked specs, delta spec, or recorded decision? +- Was anything specified but not implemented, tested, documented, or explicitly + deferred? +- Are tests or proof missing for any acceptance criteria, changed behavior, + failure mode, or regression gate? +- Are docs, templates, prompts, checklists, or agent memory now outdated because + behavior changed? +- Did changed behavior lack approval through ticket scope, `spec_refs`, + `spec_contract`, delta lifecycle, or expert routing? + +Verdict rules: + +- `pass`: no material drift found, and all relevant specs, implementation, + tests, docs, and `execution_result` are aligned. +- `pass_with_risk`: only non-blocking drift or uncertainty remains, with clear + risk notes and required follow-up recorded. +- `fail`: material drift exists, required proof is missing, behavior changed + without approval, or `execution_result.spec_alignment` is absent for a + non-trivial ticket without a documented quick-flow exemption. + +Output required: + +- verdict: `pass`, `pass_with_risk`, or `fail` +- checked_specs: list of requirements, design, tasks, delta specs, current + specs, docs, and ticket/result artifacts checked, or the exemption reason +- drift_findings: list of concrete findings with file references and whether + each is blocking +- required_followups: list of separate repair/spec/test/doc tickets required, + or `none` +- missing proof +- residual risks +- whether the ticket may proceed to final verification diff --git a/templates/TEMPLATE.execution-result.yaml b/templates/TEMPLATE.execution-result.yaml index f4bcb98..7d255ef 100644 --- a/templates/TEMPLATE.execution-result.yaml +++ b/templates/TEMPLATE.execution-result.yaml @@ -12,6 +12,15 @@ execution_result: - "command exactly as run" proof: - "Observed passing result or artifact path." + spec_alignment: + verdict: pass + checked_specs: + - "specs//requirements.md" + - "specs//design.md" + - "specs//tasks.md" + - "specs/changes//delta-spec.md, or quick-flow exemption reason" + drift_findings: [] + required_followups: [] skipped_checks: - check: "command or proof not run" reason: "Concrete reason." diff --git a/templates/TEMPLATE.ticket.yaml b/templates/TEMPLATE.ticket.yaml index 6021212..c40f3e0 100644 --- a/templates/TEMPLATE.ticket.yaml +++ b/templates/TEMPLATE.ticket.yaml @@ -125,6 +125,7 @@ execution: - "Relevant automated checks pass or skipped checks are justified." - "Agent-memory update check is recorded." - "Ticket result records changed files, commands, proof, and blockers." + - "Non-trivial tickets record execution_result.spec_alignment with verdict, checked_specs, drift_findings, and required_followups, or a justified quick-flow exemption." regression_gates: - "No unrelated files changed." - "No secrets or local machine paths are committed." @@ -156,6 +157,11 @@ execution_result: changed_files: [] commands_run: [] proof: [] + spec_alignment: + verdict: null + checked_specs: [] + drift_findings: [] + required_followups: [] skipped_checks: [] agent_memory_updates: checked: false diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml index 82f42b3..b8e2ef5 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml @@ -123,17 +123,88 @@ execution: done_definition: Done when the scoped workflow/template improvement is implemented, required proof has passed or justified skips are recorded, and execution_result is complete. execution_result: - status: pending - changed_files: [] - commands_run: [] - proof: [] - skipped_checks: [] + status: done + changed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml + - prompts/spec-drift-verifier.md + - prompts/final-verifier.md + - checklists/spec-drift.md + - checklists/closeout.md + - templates/TEMPLATE.execution-result.yaml + - templates/TEMPLATE.ticket.yaml + commands_run: + - pwd && git status --short --branch + - rg --files + - sed -n '1,240p' tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml + - find .. -name AGENTS.md -print + - sed -n '1,260p' prompts/final-verifier.md + - test -f prompts/spec-drift-verifier.md && sed -n '1,260p' prompts/spec-drift-verifier.md + || true + - test -f checklists/spec-drift.md && sed -n '1,240p' checklists/spec-drift.md + || true + - sed -n '1,260p' checklists/closeout.md + - sed -n '1,260p' templates/TEMPLATE.execution-result.yaml + - sed -n '1,320p' templates/TEMPLATE.ticket.yaml + - rg -n "spec_alignment|quick_flow|delta-spec|expert_routing|execution_result:" + tickets/sdd-upgrade templates prompts checklists + - sed -n '1,260p' tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml + - sed -n '1,260p' prompts/scoped-worker.md + - sed -n '1,260p' prompts/manager-orchestrator.md + - git diff -- prompts/spec-drift-verifier.md prompts/final-verifier.md checklists/spec-drift.md + checklists/closeout.md templates/TEMPLATE.execution-result.yaml templates/TEMPLATE.ticket.yaml + - rg -n "spec-drift|spec_alignment|implemented-but-unspecified|specified-but-unimplemented|tests-missing-for-acceptance|docs-outdated|changed-behavior-not-approved|read-only|quick_flow_exemption|delta-spec|expert_routing|spec_contract|spec_refs" + prompts checklists templates tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml + - python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path('.').rglob('*.yaml')]" + - git diff --name-only + - git diff --check + - git status --short + - if rg -n "[ \t]+$" prompts/spec-drift-verifier.md checklists/spec-drift.md; then exit 1; else + echo "no trailing whitespace in new markdown files"; fi + proof: + - Added prompts/spec-drift-verifier.md with a read-only verifier prompt that compares requirements, + design, tasks, delta specs, current/archive specs, changed files, tests, docs, and execution_result. + - Added checklists/spec-drift.md with required implemented-but-unspecified, specified-but-unimplemented, + tests-missing-for-acceptance, docs-outdated, and changed-behavior-not-approved checks. + - Updated prompts/final-verifier.md to require execution_result.spec_alignment for non-trivial tickets + unless a justified quick-flow exemption is recorded. + - Updated checklists/closeout.md to require a drift result or quick-flow exemption and to preserve the + read-only/no-auto-repair boundary. + - Updated templates/TEMPLATE.execution-result.yaml and templates/TEMPLATE.ticket.yaml with a + machine-readable spec_alignment block containing verdict, checked_specs, drift_findings, and + required_followups. + - Verified the scoped change preserves spec_refs/spec_contract, delta lifecycle wording, expert routing, + and separate scoped repair-ticket boundaries. + - YAML parse passed for repository *.yaml files. + - git diff --check passed. + - New untracked Markdown files were checked directly for trailing whitespace and passed. + spec_alignment: + verdict: pass + checked_specs: + - tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml + - prompts/spec-drift-verifier.md + - prompts/final-verifier.md + - checklists/spec-drift.md + - checklists/closeout.md + - templates/TEMPLATE.execution-result.yaml + - templates/TEMPLATE.ticket.yaml + drift_findings: [] + required_followups: [] + skipped_checks: + - check: formatter/lint/typecheck/unit tests/build/browser proof + reason: This ticket only changes Markdown and YAML workflow templates; no repo-local formatter, + typecheck, unit test, build, or browser check is required by the ticket. + - check: README.md, docs/workflow.md, templates/AGENTS.md.template, and agent/*.md edits + reason: Checked for need during scope review; no update was required for this narrow workflow hook, + and these paths are outside this ticket's allowed_files or explicitly forbidden by user instruction. agent_memory_updates: - checked: false + checked: true updated_files: [] - notes: null + notes: "agent memory checked: no update needed; this template ticket does not change target-repo runtime state, and agent/*.md edits are explicitly out of scope." blockers: [] risks: - 'Risk: false positives on intentionally changed scope; mitigate by allowing pass_with_risk plus explicit - decision record.' - next_recommended_step: null + decision record and required follow-up tickets.' + - 'Risk: existing target repositories must add spec_alignment to active tickets manually when adopting this + template update.' + next_recommended_step: Use the spec drift verifier during closeout of the next non-trivial ticket and + record execution_result.spec_alignment before final verification. From 1e1b41f4ca8600a64b3916e73173787004a00dda Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:26:00 +0200 Subject: [PATCH 06/11] Add conditional steering templates --- checklists/ticket-readiness.md | 7 ++ docs/workflow.md | 44 +++++++-- prompts/initialize-repo.md | 20 +++-- prompts/manager-orchestrator.md | 29 +++--- prompts/scoped-worker.md | 17 +++- templates/AGENTS.md.template | 41 ++++++--- templates/steering/product.md | 28 ++++++ templates/steering/security.md | 30 +++++++ templates/steering/structure.md | 29 ++++++ templates/steering/tech.md | 31 +++++++ templates/steering/testing.md | 31 +++++++ .../TKT-2026-06-09-conditional-steering.yaml | 90 ++++++++++++++++--- 12 files changed, 350 insertions(+), 47 deletions(-) create mode 100644 templates/steering/product.md create mode 100644 templates/steering/security.md create mode 100644 templates/steering/structure.md create mode 100644 templates/steering/tech.md create mode 100644 templates/steering/testing.md diff --git a/checklists/ticket-readiness.md b/checklists/ticket-readiness.md index 8da504e..a2f465e 100644 --- a/checklists/ticket-readiness.md +++ b/checklists/ticket-readiness.md @@ -8,6 +8,13 @@ Use before product-code work starts. - [ ] Ticket has a single concrete `scope.goal`. - [ ] `allowed_files` and `forbidden_files` are explicit. - [ ] `in_scope` and `out_of_scope` are explicit. +- [ ] `context_pack.required_steering_files` lists every specialized steering + file required for the ticket, or is explicitly empty. +- [ ] `context_pack.excluded_context` records noisy, stale, unsafe, or + out-of-scope context that looked relevant but should not be loaded, or is + explicitly empty. +- [ ] Required steering files use supported inclusion modes: `always`, + `fileMatch`, `manual`, or `auto`. - [ ] Non-trivial implementation work has `spec_refs` for requirements, design, and tasks, or `spec_contract.quick_flow_exemption.used: true` with a concrete reason. diff --git a/docs/workflow.md b/docs/workflow.md index 9a56165..203f7b1 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -13,12 +13,14 @@ memory closeout for a target repository. the exemption reason in the ticket. 3. Create a ticket from the installed target template `tickets/templates/TEMPLATE.ticket.yaml`. -4. Start a fresh context for ticket execution. -5. Execute only the ticket scope. -6. Run the ticket proof gates. -7. Close out with the installed target template +4. Build the ticket context pack from `AGENTS.md`, selected steering files, + linked specs, linked docs, and allowed files. +5. Start a fresh context for ticket execution. +6. Execute only the ticket scope. +7. Run the ticket proof gates. +8. Close out with the installed target template `tickets/templates/TEMPLATE.execution-result.yaml`. -8. Update `agent/*.md`, or record `agent memory checked: no update needed`. +9. Update `agent/*.md`, or record `agent memory checked: no update needed`. Fresh-context execution is intentional. The ticket must carry enough context, scope, proof requirements, and stop conditions for a new Codex session to do the @@ -72,6 +74,38 @@ of a full spec package. The ticket must set Readiness fails when non-trivial implementation lacks both linked specs and a justified exemption. +## Conditional Steering + +Steering files are optional Markdown files with YAML front matter under +`steering/` in an installed target repository. The workflow package provides +starter templates under `templates/steering/`. Steering keeps specialized rules +available without loading every domain note into every worker context. + +Supported inclusion modes are: + +- `always`: load for every ticket. Use this sparingly for core safety, + security, privacy, or repository-wide rules. +- `fileMatch`: load when the ticket's `allowed_files` match the steering + `inclusion.fileMatch` patterns. +- `manual`: load only when the user, manager, ticket, spec, or prompt names the + steering file. +- `auto`: load when the steering `inclusion.description` clearly matches the + requested task, changed-file domain, or proof risk. + +Tickets can make selection explicit with: + +- `context_pack.required_steering_files`: steering files that must be read for + the ticket. +- `context_pack.excluded_context`: relevant-looking context intentionally left + out because it is noisy, stale, unsafe, or outside scope. + +Always-loaded steering is read before specialized steering. `fileMatch` steering +is selected from the ticket's `allowed_files`. `manual` and `auto` steering must +stay bounded to explicit references or clear task-description matches. Do not +put secrets, private local paths, machine-specific notes, or invented product +facts into steering files. Unknowns should remain marked as unknown until +confirmed by repository evidence or user input. + ## Ticket Chains Use a ticket chain for complex work, risky changes, visual work, migrations, or diff --git a/prompts/initialize-repo.md b/prompts/initialize-repo.md index 01ecb34..7ee797a 100644 --- a/prompts/initialize-repo.md +++ b/prompts/initialize-repo.md @@ -24,6 +24,9 @@ Rules: - Use manifests, lockfiles, framework config, test config, build config, CI files, Docker files, environment examples, scripts, and existing docs. - Do not invent unknown values. Mark unknowns explicitly. +- Generate starter `steering/*.md` files only from repository evidence and + template-neutral placeholders. Do not use product-specific fake values, + private paths, secret names with values, or machine-local notes. - Do not install dependencies automatically. Propose the commands first, explain why they are needed, and ask for approval. - Use Codex-only planning, execution, review, verification, and closeout. @@ -47,16 +50,19 @@ Initialization work: repository before proposing writes. 4. Check whether `templates/AGENTS.md.template` has been installed as `AGENTS.md`. -5. Check whether `agent/*.md` exists and contains repo-specific evidence rather +5. Check whether starter steering templates are installed under `steering/` and + whether their YAML front matter uses only supported inclusion modes: + `always`, `fileMatch`, `manual`, and `auto`. +6. Check whether `agent/*.md` exists and contains repo-specific evidence rather than placeholders. -6. Check whether ticket templates are available under `tickets/templates/*`. -7. Check whether reusable workflow docs exist under `docs/`. -8. If files are missing, propose the minimal package-to-target copy plan before +7. Check whether ticket templates are available under `tickets/templates/*`. +8. Check whether reusable workflow docs exist under `docs/`. +9. If files are missing, propose the minimal package-to-target copy plan before writing anything. -9. Propose the minimal files to create or update. -10. Propose dependency, lint, test, build, and dev-server commands from repo +10. Propose the minimal files to create or update. +11. Propose dependency, lint, test, build, and dev-server commands from repo evidence. -11. Ask for approval before writing files or running dependency installation. +12. Ask for approval before writing files or running dependency installation. Closeout: diff --git a/prompts/manager-orchestrator.md b/prompts/manager-orchestrator.md index 7c22638..79e5eab 100644 --- a/prompts/manager-orchestrator.md +++ b/prompts/manager-orchestrator.md @@ -7,22 +7,30 @@ You are the Codex manager/observer for this ticket chain. Read first: 1. `AGENTS.md` -2. `agent/STATE.md` -3. `agent/DECISIONS.md` -4. `agent/KNOWN_ISSUES.md` -5. `agent/TODO.md` -6. `agent/PATHS.md` -7. `agent/SERVICES.md` -8. `agent/CHANGELOG.md` -9. the active orchestrator ticket -10. spec artifacts named by the active ticket -11. relevant child tickets and docs +2. steering files whose front matter uses `inclusion.mode: always` +3. the active orchestrator ticket +4. steering files named by `context_pack.required_steering_files` +5. steering files whose `fileMatch`, `manual`, or `auto` inclusion metadata + applies to the ticket scope and task description +6. `agent/STATE.md` +7. `agent/DECISIONS.md` +8. `agent/KNOWN_ISSUES.md` +9. `agent/TODO.md` +10. `agent/PATHS.md` +11. `agent/SERVICES.md` +12. `agent/CHANGELOG.md` +13. spec artifacts named by the active ticket +14. relevant child tickets and docs Rules: - Keep full context and own the execution order. - Do not edit product files unless the ticket explicitly assigns you that work. - Create or update child tickets before implementation starts. +- Build a bounded context pack. Include required steering, matching + `fileMatch` steering, explicitly referenced `manual` steering, and clear + task-matched `auto` steering. Record noisy or irrelevant exclusions in + `context_pack.excluded_context` when that decision matters. - Ensure non-trivial implementation has requirements, design, and tasks specs, or a justified quick-flow exemption, before assigning product-code work. - Run one implementation worker at a time unless scopes are explicitly disjoint. @@ -58,6 +66,7 @@ Output required: - next worker or reviewer task - scope for that task - proof required before advancing +- required steering files and excluded context - spec package status, or quick-flow exemption reason - blockers or stop condition, if any - `agent` files to update or `agent memory checked: no update needed` diff --git a/prompts/scoped-worker.md b/prompts/scoped-worker.md index 7063bfc..fd72f28 100644 --- a/prompts/scoped-worker.md +++ b/prompts/scoped-worker.md @@ -11,12 +11,16 @@ changed files. Do not revert unrelated changes. Read first: 1. `AGENTS.md` -2. the assigned ticket -3. linked requirements, design, and tasks specs, unless the ticket records a +2. steering files whose front matter uses `inclusion.mode: always` +3. the assigned ticket +4. steering files listed in `context_pack.required_steering_files` +5. steering files selected by `fileMatch`, `manual`, or `auto` inclusion + metadata for this ticket +6. linked requirements, design, and tasks specs, unless the ticket records a justified quick-flow exemption -4. relevant `agent/*` files when durable state, decisions, known issues, +7. relevant `agent/*` files when durable state, decisions, known issues, follow-up work, important paths, services, or changelog notes are affected -5. files inside your assigned scope +8. files inside your assigned scope Your ownership: @@ -42,6 +46,10 @@ Rules: - Treat linked spec artifacts as source of truth with `AGENTS.md`, agent memory, and the active ticket. If they conflict or are missing without exemption, stop and report the blocker. +- Treat selected steering files as specialized guidance. If steering conflicts + with `AGENTS.md`, the active ticket, approval boundaries, spec contracts, + delta lifecycle rules, or expert routing constraints, keep the stricter rule + and report the conflict. - Follow existing project patterns. - Add or update focused tests when the ticket requires it. - Run the assigned proof commands when available. @@ -62,6 +70,7 @@ Final response required: - commands run - proof result - spec package used, or quick-flow exemption reason +- steering files used and context intentionally excluded - skipped checks and why - `agent` files updated or `agent memory checked: no update needed` - blockers diff --git a/templates/AGENTS.md.template b/templates/AGENTS.md.template index 177e5bb..b0c399c 100644 --- a/templates/AGENTS.md.template +++ b/templates/AGENTS.md.template @@ -17,6 +17,8 @@ product-specific assumptions in this file. ## Target Repository Map - `AGENTS.md` - durable Codex agent workflow rules. +- `steering/` - optional conditional guidance with YAML front matter that + declares when specialized context should be loaded. - `agent/` - repo-local state, decisions, known issues, and handoff notes. - `tickets/` - scoped workflow records for non-trivial work. - `specs/current/` - durable current specs for implemented behavior, contracts, @@ -34,17 +36,32 @@ product-specific assumptions in this file. Before planning or implementation work, read: 1. `AGENTS.md` -2. `agent/STATE.md` -3. `agent/DECISIONS.md` -4. `agent/KNOWN_ISSUES.md` -5. `agent/TODO.md` -6. `agent/PATHS.md` -7. `agent/SERVICES.md` -8. `agent/CHANGELOG.md` -9. the newest relevant ticket in `tickets/` -10. specs named by the ticket -11. docs named by the ticket -12. files in the ticket's allowed scope +2. `steering/*.md` files whose front matter uses `inclusion.mode: always` +3. the newest relevant ticket in `tickets/` +4. steering files listed by + `context_pack.required_steering_files` +5. steering files whose `inclusion.mode: fileMatch` patterns match the + ticket's `allowed_files` +6. steering files whose `inclusion.mode: manual` files are explicitly named by + the user, ticket, specs, or manager prompt +7. steering files whose `inclusion.mode: auto` description clearly matches the + requested task, changed-file domain, or proof risk +8. `agent/STATE.md` +9. `agent/DECISIONS.md` +10. `agent/KNOWN_ISSUES.md` +11. `agent/TODO.md` +12. `agent/PATHS.md` +13. `agent/SERVICES.md` +14. `agent/CHANGELOG.md` +15. specs named by the ticket +16. docs named by the ticket +17. files in the ticket's allowed scope + +Build a bounded context pack before implementation. Include only the steering +files selected by the rules above, and record intentionally excluded noisy or +irrelevant context in `context_pack.excluded_context` when the ticket needs that +decision preserved. Do not load private/global machine paths, secrets, or +product-specific assumptions into steering files. If a referenced file is missing, stale, or conflicts with the current user instruction, report that fact instead of silently filling the gap. @@ -136,6 +153,8 @@ ticket already grants that permission. Every implementation ticket must include these fields before product-code work: +- `context_pack.required_steering_files` +- `context_pack.excluded_context` - `spec_refs`, or a justified `spec_contract.quick_flow_exemption` - `spec_contract` - `execution_intensity` diff --git a/templates/steering/product.md b/templates/steering/product.md new file mode 100644 index 0000000..149fea2 --- /dev/null +++ b/templates/steering/product.md @@ -0,0 +1,28 @@ +--- +id: product +title: Product Steering +inclusion: + mode: manual + fileMatch: [] + description: "Load when product goals, user outcomes, or domain behavior are explicitly in scope." +context_pack: + required_when: + - "" + excluded_when: + - "" +--- + +# Product Steering + +## Source Of Truth + +- Product goal: `` +- Primary users: `` +- Non-goals: `` + +## Guidance + +- Use repository evidence and ticket specs before making product assumptions. +- Mark unknown product facts as unknown instead of inventing placeholder values. +- If implementation would change user-visible behavior not covered by the + ticket, stop and request a scope update or follow-up ticket. diff --git a/templates/steering/security.md b/templates/steering/security.md new file mode 100644 index 0000000..f426dc1 --- /dev/null +++ b/templates/steering/security.md @@ -0,0 +1,30 @@ +--- +id: security +title: Security And Privacy Steering +inclusion: + mode: always + fileMatch: [] + description: "Load for all tasks because security, secrets, and approval boundaries are core workflow constraints." +context_pack: + required_when: + - "" + excluded_when: [] +--- + +# Security And Privacy Steering + +## Source Of Truth + +- Secret locations: `` +- Sensitive data classes: `` +- External services: `` + +## Guidance + +- Do not read, print, copy, create, or modify secret values or private + environment files. +- Do not push, deploy, release, publish, run migrations with side effects, or + contact external services unless the ticket and user approval allow the exact + action. +- Keep security and privacy rules at least as strict as `AGENTS.md`; specialized + steering may narrow behavior but must not weaken safety boundaries. diff --git a/templates/steering/structure.md b/templates/steering/structure.md new file mode 100644 index 0000000..88ba0cd --- /dev/null +++ b/templates/steering/structure.md @@ -0,0 +1,29 @@ +--- +id: structure +title: Repository Structure Steering +inclusion: + mode: auto + fileMatch: + - "" + description: "Load when the task creates, moves, renames, or reorganizes files or directories." +context_pack: + required_when: + - "" + excluded_when: + - "" +--- + +# Repository Structure Steering + +## Source Of Truth + +- Important directories: `` +- Generated or ignored paths: `` +- Ownership boundaries: `` + +## Guidance + +- Preserve existing layout and naming unless the ticket explicitly changes it. +- Avoid moving files as part of unrelated cleanup. +- If a new directory is required, document why it belongs in the selected + location and how future agents should discover it. diff --git a/templates/steering/tech.md b/templates/steering/tech.md new file mode 100644 index 0000000..663d696 --- /dev/null +++ b/templates/steering/tech.md @@ -0,0 +1,31 @@ +--- +id: tech +title: Technical Steering +inclusion: + mode: fileMatch + fileMatch: + - "" + - "" + description: "Load when allowed files touch implementation, build, dependency, runtime, or test tooling." +context_pack: + required_when: + - "" + excluded_when: + - "" +--- + +# Technical Steering + +## Source Of Truth + +- Language and runtime: `` +- Package manager: `` +- Frameworks and services: `` +- Test commands: `` + +## Guidance + +- Prefer existing repository patterns, scripts, and local helper APIs. +- Do not install, upgrade, or remove dependencies without explicit approval. +- Keep technical changes within the ticket's `allowed_files`; stop if required + work belongs in a different package or scope. diff --git a/templates/steering/testing.md b/templates/steering/testing.md new file mode 100644 index 0000000..a621bd5 --- /dev/null +++ b/templates/steering/testing.md @@ -0,0 +1,31 @@ +--- +id: testing +title: Testing Steering +inclusion: + mode: fileMatch + fileMatch: + - "" + - "" + - "" + description: "Load when changes require automated tests, manual proof, coverage decisions, or verification strategy." +context_pack: + required_when: + - "" + excluded_when: + - "" +--- + +# Testing Steering + +## Source Of Truth + +- Unit test command: `` +- Integration test command: `` +- Build or typecheck command: `` + +## Guidance + +- Let proof scale with risk and blast radius. +- Record skipped checks with a concrete reason. +- If the test surface is missing or ambiguous, use the smallest reliable proof + available and record the residual risk. diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml index 47add36..e76152a 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml @@ -3,8 +3,8 @@ ticket: id: TKT-2026-06-09-conditional-steering title: Add conditional steering files to reduce context noise repo: agentic-engineering-workflow-template - branch: main - status: backlog + branch: feature/sdd-workflow-v0.4.0 + status: done created_at: '2026-06-09' owner_agent: manager ticket_class: implementation @@ -26,6 +26,13 @@ context: - README.md - docs/workflow.md - templates/AGENTS.md.template +context_pack: + required_steering_files: + - templates/steering/security.md + excluded_context: + - agent/*.md not edited or loaded into this template ticket because user instructions forbid agent file + edits and the ticket scope is limited to reusable template files. + - Private/global machine paths and secrets are excluded from steering examples by design. scope: goal: Introduce conditional steering templates and update read-order rules so only relevant specialized context is loaded. @@ -127,17 +134,80 @@ execution: done_definition: Done when the scoped workflow/template improvement is implemented, required proof has passed or justified skips are recorded, and execution_result is complete. execution_result: - status: pending - changed_files: [] - commands_run: [] - proof: [] - skipped_checks: [] + status: done + changed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml + - templates/steering/product.md + - templates/steering/tech.md + - templates/steering/structure.md + - templates/steering/testing.md + - templates/steering/security.md + - templates/AGENTS.md.template + - docs/workflow.md + - prompts/initialize-repo.md + - prompts/manager-orchestrator.md + - prompts/scoped-worker.md + - checklists/ticket-readiness.md + commands_run: + - git status --short --branch + - sed -n '1,240p' tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml + - rg -n "steering|context_pack|conditional|always|fileMatch|manual|auto|excluded_context|spec drift|expert routing|delta" templates docs prompts checklists tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml + - sed -n '1,260p' templates/AGENTS.md.template + - sed -n '1,180p' docs/workflow.md + - sed -n '1,220p' prompts/initialize-repo.md + - sed -n '1,220p' prompts/manager-orchestrator.md + - sed -n '1,220p' prompts/scoped-worker.md + - sed -n '1,180p' checklists/ticket-readiness.md + - find templates/steering -maxdepth 2 -type f -print | sort + - find templates -maxdepth 2 -type f | sort + - git diff -- templates/AGENTS.md.template docs/workflow.md prompts/initialize-repo.md prompts/manager-orchestrator.md prompts/scoped-worker.md checklists/ticket-readiness.md templates/steering/product.md templates/steering/tech.md templates/steering/structure.md templates/steering/testing.md templates/steering/security.md + - rg -n "context_pack|required_steering_files|excluded_context|inclusion.mode|fileMatch|manual|auto|always|steering" templates/AGENTS.md.template docs/workflow.md prompts/initialize-repo.md prompts/manager-orchestrator.md prompts/scoped-worker.md checklists/ticket-readiness.md templates/steering tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml + - python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path('.').rglob('*.yaml')]" + - | + python - <<'PY' + from pathlib import Path + import yaml + for path in sorted(Path('templates/steering').glob('*.md')): + text = path.read_text() + if not text.startswith('---\n'): + raise SystemExit(f'{path}: missing YAML front matter') + _, front, _ = text.split('---\n', 2) + data = yaml.safe_load(front) + mode = data.get('inclusion', {}).get('mode') + if mode not in {'always', 'fileMatch', 'manual', 'auto'}: + raise SystemExit(f'{path}: unsupported inclusion mode {mode!r}') + print('validated steering front matter') + PY + - rg -n "templates/steering/(product|tech|structure|testing|security).md|steering/" templates/AGENTS.md.template docs/workflow.md prompts/initialize-repo.md prompts/manager-orchestrator.md prompts/scoped-worker.md checklists/ticket-readiness.md tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml templates/steering + - git diff --check + proof: + - Read-only review completed in-session before edits; the scoped change was useful, minimal, and did not + require product assumptions. + - Added five generic steering templates with YAML front matter and supported inclusion modes only. + - AGENTS read order now loads always steering first, then required, fileMatch, manual, and auto steering + before specialized work. + - Manager and scoped-worker prompts now carry required steering files, excluded context, and conflict + handling while preserving approval boundaries, spec contracts, delta lifecycle, spec drift, and expert + routing constraints. + - Initialization prompt now requires starter steering docs to come from repository evidence or unknown + placeholders. + - Ticket readiness now requires explicit steering context pack fields when specialized rules apply. + - Initial YAML validation caught a ticket execution_result heredoc command that needed YAML-safe block + scalar formatting; fixed before final validation. + - YAML files and steering YAML front matter validated successfully. + - Markdown/path consistency checked with rg for new steering references. + - git diff --check passed. + skipped_checks: + - Visual checks not run; visual_gate.required is false and this is a workflow/template documentation change. + - Dependency, lint, build, and test commands not run; the ticket requested YAML validation, path inspection, + and diff whitespace proof only, and no runtime code changed. agent_memory_updates: - checked: false + checked: true updated_files: [] - notes: null + notes: 'agent memory checked: no update needed; user explicitly forbade editing agent/*.md for this template ticket.' blockers: [] risks: - 'Risk: auto-like steering could hide important rules; mitigate by keeping security/core standards always loaded.' - next_recommended_step: null + - 'Residual risk: target repositories must tune fileMatch globs from repository evidence during initialization.' + next_recommended_step: Commit the scoped ticket changes after review if desired. From 4d4010054ce33fcd1e44cb9c26b14d638a351f07 Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:32:58 +0200 Subject: [PATCH 07/11] Add quick-flow escalation path --- README.md | 22 ++ checklists/ticket-readiness.md | 15 ++ docs/workflow.md | 63 +++++- prompts/quick-dev.md | 102 +++++++++ templates/AGENTS.md.template | 47 ++++ templates/TEMPLATE.quick-ticket.yaml | 208 ++++++++++++++++++ .../TKT-2026-06-09-quick-flow-escalation.yaml | 57 ++++- 7 files changed, 498 insertions(+), 16 deletions(-) create mode 100644 prompts/quick-dev.md create mode 100644 templates/TEMPLATE.quick-ticket.yaml diff --git a/README.md b/README.md index 34c2d21..cb53ce5 100644 --- a/README.md +++ b/README.md @@ -139,6 +139,7 @@ target. Source files in this template install into different paths in the target | [`templates/AGENTS.md.template`](templates/AGENTS.md.template) | `AGENTS.md` | | [`agent/*.md`](agent/) | `agent/*.md` | | [`templates/TEMPLATE.ticket.yaml`](templates/TEMPLATE.ticket.yaml) | `tickets/templates/TEMPLATE.ticket.yaml` | +| [`templates/TEMPLATE.quick-ticket.yaml`](templates/TEMPLATE.quick-ticket.yaml) | `tickets/templates/TEMPLATE.quick-ticket.yaml` | | [`templates/TEMPLATE.orchestrator-ticket.yaml`](templates/TEMPLATE.orchestrator-ticket.yaml) | `tickets/templates/TEMPLATE.orchestrator-ticket.yaml` | | [`templates/TEMPLATE.execution-result.yaml`](templates/TEMPLATE.execution-result.yaml) | `tickets/templates/TEMPLATE.execution-result.yaml` | | [`templates/TEMPLATE.reusable-feature-path.md`](templates/TEMPLATE.reusable-feature-path.md) | `docs/reusable_feature_implementation_paths.md` | @@ -165,6 +166,7 @@ shape around its normal product code, tests, package files, docs, and scripts: ├── tickets/ │ ├── templates/ │ │ ├── TEMPLATE.ticket.yaml +│ │ ├── TEMPLATE.quick-ticket.yaml │ │ ├── TEMPLATE.orchestrator-ticket.yaml │ │ └── TEMPLATE.execution-result.yaml │ └── TKT-YYYY-MM-DD-example.yaml @@ -203,6 +205,18 @@ reviewer output is recorded. The manager chooses the minimum useful read-only route from ticket risk and repository evidence; simple tickets can explicitly set no required profiles and `max_rounds: 0`. +Quick-flow is available for tiny, clear, low-risk work through +[`templates/TEMPLATE.quick-ticket.yaml`](templates/TEMPLATE.quick-ticket.yaml) +and [`prompts/quick-dev.md`](prompts/quick-dev.md). It still requires repository +discovery evidence, exact `allowed_files`, `forbidden_files`, Given-When-Then +acceptance, proof, closeout, no-secrets handling, approval boundaries, and no +bulk staging. It must escalate to the full ticket or orchestrator flow if the +change needs more than 3 non-ticket files, more than 1 behavior module, an +architecture decision, dependency changes, data migration, auth/security/privacy +work, unclear acceptance, failing or unavailable proof, ambiguous visual/product +behavior, files outside scope, spec drift, delta lifecycle work, or expert +routing. + ## Safety Model The template is built around narrow scope and explicit proof: @@ -213,6 +227,9 @@ The template is built around narrow scope and explicit proof: - Tickets declare `allowed_files`, `forbidden_files`, in-scope work, out-of-scope work, proof gates, regression gates, stop conditions, and done definitions. +- Quick-flow tickets are allowed only for tiny bounded work and must escalate + when scope or risk grows; they cannot bypass proof gates, forbidden files, + no-secrets rules, approval boundaries, closeout, or no bulk staging. - Implementation workers edit only assigned scope and do not use bulk staging. - Read-only Codex reviewers may analyze but do not edit files, run migrations, install dependencies, deploy, release, use secrets, push, perform remote @@ -254,6 +271,11 @@ For larger delivery, start from [`templates/TEMPLATE.orchestrator-ticket.yaml`](templates/TEMPLATE.orchestrator-ticket.yaml) and let the manager split the outcome into child tickets. +For tiny bounded work, start from +[`templates/TEMPLATE.quick-ticket.yaml`](templates/TEMPLATE.quick-ticket.yaml) +and use [`prompts/quick-dev.md`](prompts/quick-dev.md). Convert to a full ticket +as soon as any escalation condition is true. + ## Reference - [`docs/workflow.md`](docs/workflow.md) explains the workflow, roles, execution diff --git a/checklists/ticket-readiness.md b/checklists/ticket-readiness.md index a2f465e..bd8f507 100644 --- a/checklists/ticket-readiness.md +++ b/checklists/ticket-readiness.md @@ -18,6 +18,21 @@ Use before product-code work starts. - [ ] Non-trivial implementation work has `spec_refs` for requirements, design, and tasks, or `spec_contract.quick_flow_exemption.used: true` with a concrete reason. +- [ ] Quick-flow tickets use `templates/TEMPLATE.quick-ticket.yaml` shape: + `objective`, `discovery_evidence`, `allowed_files`, `forbidden_files`, + `acceptance_given_when_then`, `proof`, `escalation_conditions`, and + `execution_result`. +- [ ] Quick-flow discovery names current repository evidence and confirms no + escalation trigger is active before implementation. +- [ ] Quick-flow escalation thresholds are explicit: more than 3 non-ticket + files, more than 1 behavior module, architecture decision, dependency change, + data migration, auth/security/privacy impact, unclear acceptance, failing or + unavailable proof, visual/product ambiguity, scope outside `allowed_files`, + forbidden files, spec drift, conditional steering conflict, delta lifecycle + work, or expert routing. +- [ ] Quick-flow does not bypass proof gates, forbidden files, no-secrets rules, + approval boundaries, no bulk staging, conditional steering, delta lifecycle, + spec drift checks, expert routing, or closeout. - [ ] Linked spec artifacts include acceptance criteria, design boundaries, task/proof traceability, and unresolved ambiguity handling. - [ ] `execution_intensity` is one of `standard_worker`, `expert_supported`, diff --git a/docs/workflow.md b/docs/workflow.md index 203f7b1..764dcd8 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -12,7 +12,8 @@ memory closeout for a target repository. or record why the lifecycle does not apply. For tiny quick-flow work, record the exemption reason in the ticket. 3. Create a ticket from the installed target template - `tickets/templates/TEMPLATE.ticket.yaml`. + `tickets/templates/TEMPLATE.ticket.yaml`, or for tiny bounded work from + `tickets/templates/TEMPLATE.quick-ticket.yaml`. 4. Build the ticket context pack from `AGENTS.md`, selected steering files, linked specs, linked docs, and allowed files. 5. Start a fresh context for ticket execution. @@ -68,11 +69,60 @@ archives its delta. See `docs/spec_lifecycle.md` for the propose/apply/archive lifecycle. -Tiny typo, formatting, or documentation-only changes may use quick flow instead -of a full spec package. The ticket must set +Tiny typo, formatting, narrow tests, or documentation-only changes may use +quick-flow instead of a full spec package. The quick ticket must set `spec_contract.quick_flow_exemption.used: true` and provide a concrete reason. -Readiness fails when non-trivial implementation lacks both linked specs and a -justified exemption. +It must still include discovery evidence, concrete file paths, forbidden files, +Given-When-Then acceptance, proof commands or manual proof, escalation +conditions, and a complete `execution_result`. Readiness fails when non-trivial +implementation lacks both linked specs and a justified exemption. + +## Quick-Flow + +Quick-flow is a ticketed path for tiny, clear, low-risk work. It exists to avoid +full requirements/design/tasks ceremony when current repository evidence already +shows the change is small and directly verifiable. + +Use quick-flow only when all of these are true: + +- The objective is one bounded outcome. +- Discovery can name the exact current files and patterns involved. +- The change stays within explicit `allowed_files` and avoids all + `forbidden_files`. +- Acceptance can be written as concrete Given-When-Then cases. +- Proof is available, local, and meaningful. +- No durable spec, API, data, workflow, release, security, or architecture + decision is required. + +Quick-flow must not bypass proof gates, forbidden files, no-secrets rules, +approval boundaries, no bulk staging, conditional steering, delta lifecycle +rules, spec drift checks, expert routing, or ticket closeout. It still records +changed files, commands run, proof, skipped checks, blockers, risks, and the +agent-memory update check. + +Escalate from quick-flow to a full ticket or parent orchestrator flow before +implementation continues when any threshold is met: + +- More than 3 non-ticket files need edits. +- More than 1 package, service, app, or bounded module needs behavior changes. +- The change requires an architecture decision or alters a shared contract. +- Dependencies must be added, removed, upgraded, or reconfigured. +- Schema, storage, data migration, backfill, or destructive cleanup is needed. +- Auth, security, permissions, secrets, privacy, payments, deployment, release, + remotes, or external-service behavior may change. +- Acceptance is unclear, contradictory, or lacks observable outcomes. +- Proof is unavailable, flaky, network-dependent without approval, or fails for + unclear reasons. +- User-facing UI, product copy, layout, accessibility, or visual behavior is + ambiguous or needs visual proof that is not already specified. +- Required files are outside `allowed_files` or match `forbidden_files`. +- Spec drift, conditional steering conflicts, delta lifecycle work, or expert + routing is discovered. + +When escalation triggers, stop implementation, record the trigger in +`execution_result.blockers`, and convert to the full SDD ticket or orchestrator +flow. The discovery evidence collected by quick-flow should become context for +the new ticket. ## Conditional Steering @@ -123,6 +173,9 @@ multi-stage delivery. - Child tickets that materially change durable behavior should link to the relevant `specs/changes//delta-spec.md` and identify any `specs/current/**` files they intend to update. +- Child quick-flow tickets may use + `tickets/templates/TEMPLATE.quick-ticket.yaml` only when they satisfy the + quick-flow rules and escalation thresholds above. - Record worker closeout with the installed target template `tickets/templates/TEMPLATE.execution-result.yaml`. - The manager looks back at recent child ticket results before planning the next diff --git a/prompts/quick-dev.md b/prompts/quick-dev.md new file mode 100644 index 0000000..1b25feb --- /dev/null +++ b/prompts/quick-dev.md @@ -0,0 +1,102 @@ +# Quick Dev Prompt + +Use after installing this package in a target repository for a tiny, clear, +bounded task that already has a quick ticket. + +You are a scoped Codex quick-flow worker. You inherit `AGENTS.md`, selected +steering, the quick ticket, approval boundaries, forbidden actions, proof gates, +and verification requirements. + +Quick-flow is still ticketed work. It is not permission to skip discovery, +acceptance criteria, proof, closeout, no-secrets rules, approval boundaries, or +scope control. + +Read first: + +1. `AGENTS.md` +2. steering files whose front matter uses `inclusion.mode: always` +3. the assigned quick ticket +4. steering files selected by the quick ticket or by `fileMatch`, `manual`, or + clear `auto` applicability +5. relevant files inside `allowed_files` +6. relevant docs or tests named by the ticket + +Before editing: + +- Run a small discovery scan of current repository evidence. +- Identify the exact files that appear necessary. +- Record discovery evidence in the quick ticket before or alongside the change. +- Confirm the task can stay inside `allowed_files`. +- Confirm `forbidden_files` are not needed. +- Confirm acceptance is concrete as Given-When-Then statements. +- Confirm proof commands or manual proof steps are available and meaningful. +- Confirm the quick ticket includes + `spec_contract.quick_flow_exemption.used: true` with a concrete reason, or + stop and ask the manager to convert the task to a full ticket. + +Escalate before implementation if any condition is true: + +- More than 3 non-ticket files need edits. +- More than 1 package, service, app, or bounded module needs behavior changes. +- The change needs an architecture decision or changes a shared contract. +- The change adds, removes, upgrades, or reconfigures dependencies. +- The change touches auth, security, permissions, secrets, privacy, payments, + deployment, release, remotes, or external-service behavior. +- The change requires schema, storage, data migration, backfill, or destructive + cleanup. +- Acceptance is unclear, contradictory, or missing observable outcomes. +- Proof is unavailable, flaky, network-dependent without approval, or fails for + reasons that are not clearly inside the quick ticket. +- User-facing UI, product copy, layout, accessibility, or visual behavior is + ambiguous or needs visual proof not already specified. +- Required files are outside `allowed_files`, or any needed path matches + `forbidden_files`. +- The task reveals spec drift, conditional steering conflicts, unresolved delta + lifecycle work, or expert routing that requires read-only review. +- The implementation would bypass no-secrets rules, proof gates, approval + boundaries, no bulk staging, or closeout requirements. + +If escalation is triggered: + +- Stop implementation. +- Record the trigger in `execution_result.blockers`. +- Recommend conversion to a full ticket or parent orchestrator flow. +- Preserve current evidence and any safe read-only findings in the quick ticket. + +Implementation rules: + +- Edit only `allowed_files`. +- Do not edit secrets, credentials, private local configuration, generated + output, dependency folders, or build artifacts. +- Do not install dependencies, run migrations with side effects, run destructive + commands, push, deploy, release, publish, alter remotes, or contact external + services unless the quick ticket and user approval allow that exact action. +- Do not use bulk staging such as `git add -A`. +- Follow existing project patterns. +- Keep changes small enough that the discovery evidence and acceptance criteria + still describe the whole change. +- If risk grows, stop and escalate instead of widening scope. + +Closeout: + +- Run the listed proof when available. +- Run a YAML parse check for changed YAML files when YAML changed. +- Run `git diff --check`. +- Check whether `agent/*.md` needs updates. For quick-flow, most changes should + record `agent memory checked: no update needed`; update agent files only when + they are inside scope and durable repository knowledge changed. +- Fill `execution_result` with changed files, commands run, proof, skipped + checks, blockers, risks, agent memory update check, and next recommended step. + +Final response required: + +- changed files +- commands run +- proof result +- quick-flow exemption reason +- steering files used and context intentionally excluded +- skipped checks and why +- `agent` files updated or `agent memory checked: no update needed` +- blockers +- risks +- whether the ticket can be marked done or must escalate diff --git a/templates/AGENTS.md.template b/templates/AGENTS.md.template index b0c399c..5cfd498 100644 --- a/templates/AGENTS.md.template +++ b/templates/AGENTS.md.template @@ -21,6 +21,8 @@ product-specific assumptions in this file. declares when specialized context should be loaded. - `agent/` - repo-local state, decisions, known issues, and handoff notes. - `tickets/` - scoped workflow records for non-trivial work. +- `tickets/templates/TEMPLATE.quick-ticket.yaml` - compact quick-flow ticket + template for tiny bounded work. - `specs/current/` - durable current specs for implemented behavior, contracts, workflows, and important constraints. - `specs/changes//` - proposed change specs, typically @@ -91,6 +93,11 @@ files. - Significant behavior, API, data, workflow, or durable documentation changes must link a delta spec under `specs/changes//delta-spec.md` or record why the delta-spec lifecycle does not apply. +- Tiny quick-flow work may use `tickets/templates/TEMPLATE.quick-ticket.yaml` + and `prompts/quick-dev.md` only when it has discovery evidence, exact + `allowed_files`, `forbidden_files`, Given-When-Then acceptance, proof, hard + escalation conditions, and a justified + `spec_contract.quick_flow_exemption`. - Codex implementation workers must work from the active ticket scope and keep changes inside the ticket's declared files unless the user widens scope. - After each meaningful step, record the result as a ticket comment or result @@ -116,6 +123,41 @@ files. staging such as `git add -A`. - Do not revert changes you did not make unless explicitly requested. +## Quick-Flow Rules + +Quick-flow is for tiny, clear, low-risk work. It is still ticketed work and +must not bypass proof gates, forbidden files, no-secrets rules, approval +boundaries, conditional steering, delta lifecycle rules, spec drift checks, +expert routing, no bulk staging, or closeout. + +Before editing in quick-flow, Codex must scan current repository evidence, +record the discovered files and patterns, confirm concrete Given-When-Then +acceptance, confirm proof, and verify that no escalation condition applies. + +Escalate to a full ticket or parent orchestrator flow when any condition is +true: + +- More than 3 non-ticket files need edits. +- More than 1 package, service, app, or bounded module needs behavior changes. +- An architecture decision or shared contract change is required. +- A dependency add, remove, upgrade, or configuration change is required. +- A schema, storage, data migration, backfill, or destructive cleanup is + required. +- Auth, security, permissions, secrets, privacy, payments, deployment, release, + remotes, or external-service behavior may change. +- Acceptance is unclear, contradictory, or missing observable outcomes. +- Proof is unavailable, flaky, network-dependent without approval, or failing + for unclear reasons. +- UI, product copy, layout, accessibility, or visual behavior is ambiguous or + needs unspecified visual proof. +- Needed files are outside `allowed_files` or match `forbidden_files`. +- Spec drift, conditional steering conflicts, delta lifecycle work, or expert + routing is discovered. + +When escalation triggers, stop implementation, record the trigger in +`execution_result.blockers`, and convert to the full SDD ticket or orchestrator +flow before continuing. + ## Safety And Approval Boundaries Forbidden unless the user explicitly requests or approves the exact action: @@ -185,6 +227,11 @@ allowed-file tasks, proof, and requirement traceability aligned. Tiny quick-flow changes may skip full specs only when the ticket records a concrete exemption reason. +Quick-flow tickets must also include `objective`, `discovery_evidence`, +`acceptance_given_when_then`, `proof`, `escalation_conditions`, and +`execution_result`. If those fields cannot be completed honestly before +implementation, create a full ticket instead. + For significant changes, `spec_refs` should also include the delta spec. The delta spec uses `ADDED`, `MODIFIED`, and `REMOVED` sections to describe how `specs/current/**` must change. Final verification checks that implementation diff --git a/templates/TEMPLATE.quick-ticket.yaml b/templates/TEMPLATE.quick-ticket.yaml new file mode 100644 index 0000000..0debc8b --- /dev/null +++ b/templates/TEMPLATE.quick-ticket.yaml @@ -0,0 +1,208 @@ +schema_version: 2 + +ticket: + id: TKT-YYYY-MM-DD-short-name + title: "Short human-readable quick-flow title" + repo: "" + branch: "" + status: backlog + created_at: "YYYY-MM-DD" + owner_agent: "" + ticket_class: quick_flow + work_kind: "" + phase: "" + +objective: > + One tiny, clear, bounded outcome. Quick-flow is allowed only when the task + can be understood from repository evidence, implemented in a few known files, + and verified with concrete proof. + +context: + problem: > + Describe the small problem. Mark unknowns explicitly. + current_behavior: > + Describe current evidence. Do not guess. + desired_behavior: > + Describe the target observable behavior. + quick_flow_reason: > + Explain why full requirements/design/tasks specs are not needed. + +context_pack: + required_steering_files: [] + excluded_context: [] + +spec_refs: null + +spec_contract: + required: true + quick_flow_exemption: + used: true + reason: "Tiny bounded change with concrete files, acceptance, and proof." + preserves_spec_contracts: true + delta_lifecycle: "Not required for tiny quick-flow; escalate if durable behavior, API, data, or workflow specs must change." + traceability_required: true + +discovery_evidence: + repo_scan: + - "Command or file inspected, with concise finding." + patterns_found: + - "Existing pattern this change follows." + unknowns: + - "Unknowns that do not block quick-flow, or 'none'." + escalation_check: "No escalation trigger found before implementation." + +scope: + allowed_files: + - "tickets/TKT-YYYY-MM-DD-short-name.yaml" + - "" + forbidden_files: + - ".env" + - ".env.*" + - "node_modules/**" + - "dist/**" + - "build/**" + - ".next/**" + - "coverage/**" + in_scope: + - "Specific small change allowed by this ticket." + out_of_scope: + - "Any adjacent work that requires full ticket or orchestrator flow." + +acceptance_given_when_then: + - id: AC-001 + given: "A concrete precondition from repo evidence." + when: "The changed behavior or document is used." + then: "The observable result that proves the objective." + +proof: + commands: + - "Parse changed YAML files if any YAML changed." + - "Run targeted test, lint, docs check, or manual inspection relevant to this change." + - "git diff --check" + manual_checks: + - "Manual inspection needed, or 'none'." + required_before_done: + - "Acceptance criteria are satisfied." + - "Proof passed or skipped checks are justified." + - "execution_result is complete." + +escalation_conditions: + max_non_ticket_files: 3 + max_behavior_modules: 1 + triggers: + - "More than 3 non-ticket files need edits." + - "More than 1 package, service, app, or bounded module needs behavior changes." + - "Architecture decision or shared contract change is required." + - "Dependency add, remove, upgrade, or configuration change is required." + - "Schema, storage, data migration, backfill, or destructive cleanup is required." + - "Auth, security, permissions, secrets, privacy, payments, deployment, release, remotes, or external-service behavior may change." + - "Acceptance is unclear, contradictory, or missing observable outcomes." + - "Proof is unavailable, flaky, network-dependent without approval, or failing for unclear reasons." + - "User-facing UI, product copy, layout, accessibility, or visual behavior is ambiguous or needs unspecified visual proof." + - "Needed files are outside allowed_files or match forbidden_files." + - "Spec drift, conditional steering conflict, delta lifecycle work, or expert routing is discovered." + - "The change would bypass proof gates, no-secrets rules, approval boundaries, closeout, or no bulk staging." + escalation_action: > + Stop quick-flow implementation, record the trigger in execution_result, and + convert to a full ticket or parent orchestrator flow before continuing. + +execution: + execution_intensity: standard_worker + manager_role: > + Main Codex agent owns scope, verifies the work, and records proof in this + ticket. Any Codex subagent inherits AGENTS.md, the active ticket scope, + approval boundaries, forbidden actions, and verification requirements. + worker_sequence: + - role: scoped_worker + mode: quick_flow_implementation + task: "Implement only the quick-flow change described in this ticket." + expert_plan: + required: false + planning_reviewer: null + reviewer: null + record_location: "execution_result" + expert_routing: + required_profiles: [] + optional_profiles: [] + triggers: + - profile: requirements + when: "Acceptance, scope, or observable behavior is unclear." + - profile: architecture + when: "The change crosses module boundaries or alters shared contracts." + - profile: test + when: "Proof strategy is missing, flaky, or too broad." + - profile: security_privacy + when: "Auth, secrets, permissions, user data, or privacy boundaries may change." + - profile: ux_visual + when: "UI, copy, layout, accessibility, or visual behavior is ambiguous." + - profile: performance_reliability + when: "Latency, concurrency, resource use, retries, or failure modes may change." + - profile: data_migration + when: "Schema, persistence, migrations, backfills, or compatibility may change." + - profile: docs_release + when: "Operational docs, release, setup, or rollout behavior may change." + max_rounds: 0 + escalation_rule: "Any expert routing trigger escalates quick-flow to full ticket or orchestrator review before implementation continues." + record_location: "execution_result" + debug_logging_plan: + owner: scoped_worker + surfaces: + - "Discovery commands and proof output." + temporary_logging_policy: "Do not add temporary logs; record command output only in execution_result." + test_plan: + - "Verify quick_flow_exemption is justified." + - "Review discovery evidence and escalation conditions before editing." + - "Run proof.commands that are available and relevant." + - "Run git diff --check." + - "Check whether agent files need updates and record the result." + proof_gates: + - "Quick-flow exemption is justified and recorded." + - "Discovery evidence names current files or commands inspected." + - "Acceptance criteria are concrete Given-When-Then cases." + - "No escalation condition is active." + - "No forbidden files changed." + - "No secrets or private local paths are introduced." + - "Relevant proof passes or skipped checks are justified." + - "execution_result records changed files, commands, proof, skipped checks, blockers, risks, and agent memory check." + regression_gates: + - "No unrelated files changed." + - "No dependency installation, destructive cleanup, remote operation, release, deploy, or external-service action occurs without explicit approval." + - "No bulk staging is used." + - "Existing spec contracts, conditional steering, delta lifecycle, spec drift checks, and expert routing remain stricter or equivalent." + visual_gate: + required: false + required_views: [] + pass_rule: "Escalate if user-facing visual proof is needed and not already specified." + checkpoint_policy: "Create a scoped checkpoint commit only after proof passes or after explicit user approval." + rollback_or_accept_policy: > + If the quick change fails proof and the fix is not obvious inside + allowed_files, keep the ticket non-done, record the blocker, and escalate. + stop_conditions: + - "Any escalation condition becomes true." + - "Required files or commands are missing and cannot be inferred safely." + - "The change requires editing forbidden files." + - "The work requires dependency installation, destructive commands, remote operations, deployment, release, secrets, migrations with side effects, network-dependent setup, or scope expansion without explicit approval." + handoff_requirements: + - "Record changed files, commands run, proof result, skipped checks, blockers, risks, agent updates, and next action." + done_definition: > + Done when the quick-flow change is implemented within allowed_files, + acceptance and proof are satisfied, no escalation trigger remains active, + and execution_result is complete. + +execution_result: + status: pending + changed_files: [] + commands_run: [] + proof: [] + skipped_checks: [] + agent_memory_updates: + checked: false + updated_files: [] + notes: null + blockers: [] + risks: [] + escalation: + triggered: false + conditions: [] + converted_to_full_ticket: false + next_recommended_step: null diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml index 0d6a7c0..ada70cc 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml @@ -4,7 +4,7 @@ ticket: title: Add quick-flow path with automatic escalation rules repo: agentic-engineering-workflow-template branch: main - status: backlog + status: done created_at: '2026-06-09' owner_agent: manager ticket_class: implementation @@ -127,17 +127,52 @@ execution: done_definition: Done when the scoped workflow/template improvement is implemented, required proof has passed or justified skips are recorded, and execution_result is complete. execution_result: - status: pending - changed_files: [] - commands_run: [] - proof: [] - skipped_checks: [] + status: done + changed_files: + - prompts/quick-dev.md + - templates/TEMPLATE.quick-ticket.yaml + - docs/workflow.md + - README.md + - templates/AGENTS.md.template + - checklists/ticket-readiness.md + - tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml + commands_run: + - "sed -n '1,240p' tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml" + - "sed -n '1,240p' AGENTS.md" + - "sed -n '1,260p' README.md" + - "sed -n '1,320p' docs/workflow.md" + - "sed -n '1,260p' templates/AGENTS.md.template" + - "sed -n '1,260p' checklists/ticket-readiness.md" + - "sed -n '261,620p' templates/AGENTS.md.template" + - "rg -n \"quick|Quick|TEMPLATE\\.ticket|execution_result|spec_contract|expert_routing|allowed_files|forbidden_files|proof\" README.md docs/workflow.md templates/AGENTS.md.template checklists/ticket-readiness.md templates prompts tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml" + - "rg --files prompts templates docs checklists tickets/sdd-upgrade | sort" + - "sed -n '1,220p' prompts/scoped-worker.md" + - "sed -n '1,180p' prompts/manager-orchestrator.md" + - "sed -n '1,230p' templates/TEMPLATE.ticket.yaml" + - "git diff -- README.md docs/workflow.md templates/AGENTS.md.template checklists/ticket-readiness.md prompts/quick-dev.md templates/TEMPLATE.quick-ticket.yaml" + - "rg -n \"quick-flow|Quick-flow|quick_flow|TEMPLATE.quick-ticket|quick-dev|More than 3|more than 3|no bulk staging|forbidden files|proof gates|spec drift|delta lifecycle|expert routing\" README.md docs/workflow.md templates/AGENTS.md.template checklists/ticket-readiness.md prompts/quick-dev.md templates/TEMPLATE.quick-ticket.yaml" + - "git status --short" + - "python -c \"import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path('.').rglob('*.yaml')]; print('parsed yaml files:', len(list(pathlib.Path('.').rglob('*.yaml'))))\"" + - "git diff --check" + - "for path in prompts/quick-dev.md templates/TEMPLATE.quick-ticket.yaml docs/workflow.md README.md templates/AGENTS.md.template checklists/ticket-readiness.md; do test -f \"$path\" || exit 1; done; rg -n \"TEMPLATE.quick-ticket.yaml|prompts/quick-dev.md|tickets/templates/TEMPLATE.quick-ticket.yaml|quick_flow_exemption|execution_result\" README.md docs/workflow.md templates/AGENTS.md.template checklists/ticket-readiness.md prompts/quick-dev.md templates/TEMPLATE.quick-ticket.yaml" + proof: + - "Read-only review completed before edits: quick-flow should remain ticketed, proof-bound, and subordinate to full SDD/orchestrator escalation when risk grows." + - "Created prompts/quick-dev.md with discovery, compact spec, implementation, proof, closeout, and escalation instructions." + - "Created templates/TEMPLATE.quick-ticket.yaml with objective, discovery_evidence, scoped allowed/forbidden files, Given-When-Then acceptance, proof, escalation_conditions, execution_result, spec exemption, and expert routing escalation." + - "Updated docs/workflow.md and README.md to describe when quick-flow is allowed and when full SDD/orchestrator flow is mandatory." + - "Updated templates/AGENTS.md.template and checklists/ticket-readiness.md so installed target repos inherit quick-flow safety and readiness checks." + - "Path/reference inspection found quick-flow template and prompt references across README, docs/workflow.md, AGENTS template, checklist, prompt, and template." + - "YAML parse passed for all 13 YAML files." + - "git diff --check passed." + skipped_checks: + - "Visual proof skipped: ticket visual_gate.required is false and this is a workflow/template documentation change." + - "Runtime tests skipped: repository has no product runtime surface for this workflow/template-only change." agent_memory_updates: - checked: false + checked: true updated_files: [] - notes: null + notes: "agent memory checked: no update needed; ticket scope forbids editing agent/*.md and this template-source change is fully recorded in the ticket." blockers: [] risks: - - 'Risk: quick-flow becomes vibe coding in disguise; mitigate with explicit discovery evidence, Given-When-Then - acceptance, and hard escalation triggers.' - next_recommended_step: null + - "Risk: quick-flow becomes vibe coding in disguise; mitigated with explicit discovery evidence, Given-When-Then acceptance, proof, closeout, and hard escalation triggers in the prompt, template, workflow docs, AGENTS template, and checklist." + - "Risk: future users may overuse quick-flow for risky work; mitigated by mandatory escalation for architecture, dependencies, data migration, auth/security/privacy, unclear acceptance, failing proof, visual/product ambiguity, scope expansion, spec drift, delta lifecycle work, and expert routing." + next_recommended_step: "Final verifier can review the diff and proof, then accept this ticket." From df74f1b37cbd32eaa8e3fb6abd79c28d580c78dc Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:36:44 +0200 Subject: [PATCH 08/11] Add decision locks and context budgets --- agent/DECISIONS.md | 3 + checklists/ticket-readiness.md | 12 +++ docs/workflow.md | 36 +++++++- prompts/manager-orchestrator.md | 15 ++- prompts/scoped-worker.md | 22 +++-- templates/AGENTS.md.template | 31 ++++++- templates/TEMPLATE.orchestrator-ticket.yaml | 27 ++++++ templates/TEMPLATE.ticket.yaml | 26 ++++++ ...26-06-09-decision-lock-context-budget.yaml | 92 +++++++++++++++++-- 9 files changed, 236 insertions(+), 28 deletions(-) diff --git a/agent/DECISIONS.md b/agent/DECISIONS.md index 2be66c3..55d7895 100644 --- a/agent/DECISIONS.md +++ b/agent/DECISIONS.md @@ -7,5 +7,8 @@ Newest entries go at the bottom. - Context: `` - Decision: `` +- Rationale: `` +- Owner: `` - Consequence: `` - Source: `` +- Expiry/change rule: `` diff --git a/checklists/ticket-readiness.md b/checklists/ticket-readiness.md index bd8f507..3c228c5 100644 --- a/checklists/ticket-readiness.md +++ b/checklists/ticket-readiness.md @@ -8,11 +8,23 @@ Use before product-code work starts. - [ ] Ticket has a single concrete `scope.goal`. - [ ] `allowed_files` and `forbidden_files` are explicit. - [ ] `in_scope` and `out_of_scope` are explicit. +- [ ] Grey-area status is explicit as `none`, `resolved`, or `blocked`. +- [ ] Any grey-area items are resolved before implementation planning, or the + ticket is blocked and points to a `research_only` blocker ticket. +- [ ] `locked_decisions` is present, either as an explicitly empty list or with + entries that include `decision`, `rationale`, `owner`, `source`, and + `expiry/change rule`. +- [ ] `context_pack.required_files` lists files the worker must read before + editing, or is explicitly empty. +- [ ] `context_pack.required_specs` lists specs the worker must read before + editing, or is explicitly empty because a quick-flow exemption applies. - [ ] `context_pack.required_steering_files` lists every specialized steering file required for the ticket, or is explicitly empty. - [ ] `context_pack.excluded_context` records noisy, stale, unsafe, or out-of-scope context that looked relevant but should not be loaded, or is explicitly empty. +- [ ] `context_pack.budget_notes` states the intended context budget and when a + worker must stop instead of loading more context. - [ ] Required steering files use supported inclusion modes: `always`, `fileMatch`, `manual`, or `auto`. - [ ] Non-trivial implementation work has `spec_refs` for requirements, design, diff --git a/docs/workflow.md b/docs/workflow.md index 764dcd8..3af419d 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -16,12 +16,15 @@ memory closeout for a target repository. `tickets/templates/TEMPLATE.quick-ticket.yaml`. 4. Build the ticket context pack from `AGENTS.md`, selected steering files, linked specs, linked docs, and allowed files. -5. Start a fresh context for ticket execution. -6. Execute only the ticket scope. -7. Run the ticket proof gates. -8. Close out with the installed target template +5. Identify implementation grey areas and resolve them through user input, + specs, or locked decisions before planning implementation. If they cannot be + resolved inside scope, create a `research_only` blocker ticket. +6. Start a fresh context for ticket execution. +7. Execute only the ticket scope. +8. Run the ticket proof gates. +9. Close out with the installed target template `tickets/templates/TEMPLATE.execution-result.yaml`. -9. Update `agent/*.md`, or record `agent memory checked: no update needed`. +10. Update `agent/*.md`, or record `agent memory checked: no update needed`. Fresh-context execution is intentional. The ticket must carry enough context, scope, proof requirements, and stop conditions for a new Codex session to do the @@ -144,10 +147,15 @@ Supported inclusion modes are: Tickets can make selection explicit with: +- `context_pack.required_files`: exact repository files the worker must read. +- `context_pack.required_specs`: specs the worker must read, or an explicitly + empty list for a justified quick-flow exemption. - `context_pack.required_steering_files`: steering files that must be read for the ticket. - `context_pack.excluded_context`: relevant-looking context intentionally left out because it is noisy, stale, unsafe, or outside scope. +- `context_pack.budget_notes`: the context budget and stop rule for loading + more context. Always-loaded steering is read before specialized steering. `fileMatch` steering is selected from the ticket's `allowed_files`. `manual` and `auto` steering must @@ -156,6 +164,24 @@ put secrets, private local paths, machine-specific notes, or invented product facts into steering files. Unknowns should remain marked as unknown until confirmed by repository evidence or user input. +## Grey Areas And Decision Locks + +Before implementation planning, the manager records `context.grey_areas.status` +as `none`, `resolved`, or `blocked`. Grey areas are decisions that would make a +worker guess about behavior, scope, ownership, safety boundaries, proof, or +which context is authoritative. + +Resolved grey areas are captured in ticket-local `locked_decisions` entries. +Each entry includes `decision`, `rationale`, `owner`, `source`, and +`expiry/change rule`. Use `agent/DECISIONS.md` only for durable decisions that +future tickets must inherit; do not use it for one-off closeout notes. + +If a grey area cannot be resolved from current repository evidence, specs, +existing durable decisions, or user input, stop and create or update a +`research_only` blocker ticket. Implementation workers stop when a required +decision or context-pack item is missing, when `context.grey_areas.status` is +`blocked`, or when the requested context exceeds `context_pack.budget_notes`. + ## Ticket Chains Use a ticket chain for complex work, risky changes, visual work, migrations, or diff --git a/prompts/manager-orchestrator.md b/prompts/manager-orchestrator.md index 79e5eab..2497f9f 100644 --- a/prompts/manager-orchestrator.md +++ b/prompts/manager-orchestrator.md @@ -26,11 +26,21 @@ Rules: - Keep full context and own the execution order. - Do not edit product files unless the ticket explicitly assigns you that work. +- Identify implementation grey areas before planning child work. Record + `context.grey_areas.status` as `none`, `resolved`, or `blocked`. +- Resolve grey areas through user input, linked specs, existing durable + decisions, or new `locked_decisions` entries with `decision`, `rationale`, + `owner`, `source`, and `expiry/change rule`. +- If a grey area cannot be resolved inside scope, create or update a + `research_only` blocker ticket and stop before assigning implementation. - Create or update child tickets before implementation starts. - Build a bounded context pack. Include required steering, matching `fileMatch` steering, explicitly referenced `manual` steering, and clear task-matched `auto` steering. Record noisy or irrelevant exclusions in - `context_pack.excluded_context` when that decision matters. + `context_pack.excluded_context` when that decision matters. Fill + `context_pack.required_files`, `context_pack.required_specs`, + `context_pack.required_steering_files`, and `context_pack.budget_notes` so + workers know what to read and when to stop. - Ensure non-trivial implementation has requirements, design, and tasks specs, or a justified quick-flow exemption, before assigning product-code work. - Run one implementation worker at a time unless scopes are explicitly disjoint. @@ -66,7 +76,8 @@ Output required: - next worker or reviewer task - scope for that task - proof required before advancing -- required steering files and excluded context +- grey-area status and locked decisions +- required files, specs, steering files, excluded context, and budget notes - spec package status, or quick-flow exemption reason - blockers or stop condition, if any - `agent` files to update or `agent memory checked: no update needed` diff --git a/prompts/scoped-worker.md b/prompts/scoped-worker.md index fd72f28..df0e101 100644 --- a/prompts/scoped-worker.md +++ b/prompts/scoped-worker.md @@ -13,14 +13,17 @@ Read first: 1. `AGENTS.md` 2. steering files whose front matter uses `inclusion.mode: always` 3. the assigned ticket -4. steering files listed in `context_pack.required_steering_files` -5. steering files selected by `fileMatch`, `manual`, or `auto` inclusion +4. files listed in `context_pack.required_files` +5. specs listed in `context_pack.required_specs`, unless the ticket records a + justified quick-flow exemption +6. steering files listed in `context_pack.required_steering_files` +7. steering files selected by `fileMatch`, `manual`, or `auto` inclusion metadata for this ticket -6. linked requirements, design, and tasks specs, unless the ticket records a +8. linked requirements, design, and tasks specs, unless the ticket records a justified quick-flow exemption -7. relevant `agent/*` files when durable state, decisions, known issues, +9. relevant `agent/*` files when durable state, decisions, known issues, follow-up work, important paths, services, or changelog notes are affected -8. files inside your assigned scope +10. files inside your assigned scope Your ownership: @@ -43,6 +46,12 @@ Task: Rules: - Edit only your assigned scope. +- Before editing, confirm that `context.grey_areas.status` is `none` or + `resolved`, that required `locked_decisions` are present, and that every + required context-pack item is available within `context_pack.budget_notes`. +- Stop and report a blocker when a required decision, required file, required + spec, required steering file, or context-budget item is missing. Do not fill + the gap by guessing or widening context. - Treat linked spec artifacts as source of truth with `AGENTS.md`, agent memory, and the active ticket. If they conflict or are missing without exemption, stop and report the blocker. @@ -70,7 +79,8 @@ Final response required: - commands run - proof result - spec package used, or quick-flow exemption reason -- steering files used and context intentionally excluded +- grey-area status and locked decisions used +- required files, specs, steering files, excluded context, and budget notes - skipped checks and why - `agent` files updated or `agent memory checked: no update needed` - blockers diff --git a/templates/AGENTS.md.template b/templates/AGENTS.md.template index 5cfd498..5ee70e9 100644 --- a/templates/AGENTS.md.template +++ b/templates/AGENTS.md.template @@ -59,11 +59,13 @@ Before planning or implementation work, read: 16. docs named by the ticket 17. files in the ticket's allowed scope -Build a bounded context pack before implementation. Include only the steering -files selected by the rules above, and record intentionally excluded noisy or -irrelevant context in `context_pack.excluded_context` when the ticket needs that -decision preserved. Do not load private/global machine paths, secrets, or -product-specific assumptions into steering files. +Build a bounded context pack before implementation. Include only the +`context_pack.required_files`, `context_pack.required_specs`, selected steering +files, linked docs, and allowed files needed for the task. Record intentionally +excluded noisy or irrelevant context in `context_pack.excluded_context` when +the ticket needs that decision preserved, and use `context_pack.budget_notes` +to state the context budget and stop rule. Do not load private/global machine +paths, secrets, or product-specific assumptions into steering files. If a referenced file is missing, stale, or conflicts with the current user instruction, report that fact instead of silently filling the gap. @@ -87,6 +89,11 @@ files. - Non-trivial planning and implementation work must be ticketed. - Planning work must create or update a scoped ticket before implementation starts. +- Before implementation planning, identify implementation grey areas. Resolve + them through user input, specs, or durable decision locks, or create a + `research_only` blocker ticket instead of assigning implementation. +- Required durable decision locks live in `locked_decisions` and include + `decision`, `rationale`, `owner`, `source`, and `expiry/change rule`. - Non-trivial implementation work must link requirements, design, and tasks specs, or record a justified quick-flow exemption in the ticket before product-code work starts. @@ -195,8 +202,16 @@ ticket already grants that permission. Every implementation ticket must include these fields before product-code work: +- `context.grey_areas.status` with `none`, `resolved`, or `blocked` +- `context.grey_areas.items` +- `context.grey_areas.resolution` +- `context_pack.required_files` +- `context_pack.required_specs` - `context_pack.required_steering_files` - `context_pack.excluded_context` +- `context_pack.budget_notes` +- `locked_decisions`, or an explicitly empty list when no decision locks are + required - `spec_refs`, or a justified `spec_contract.quick_flow_exemption` - `spec_contract` - `execution_intensity` @@ -216,6 +231,10 @@ Every implementation ticket must include these fields before product-code work: - `handoff_requirements` - `done_definition` +Workers must stop before editing when a required context-pack item is missing, +when a required locked decision is absent, or when the task would require +context beyond `context_pack.budget_notes`. + The `test_plan` or closeout proof must include an agent-memory update check for `agent/` files whenever the ticket changes durable project state, decisions, known issues, setup paths, service assumptions, or follow-up work. @@ -279,6 +298,8 @@ owner. - Independent read-only Codex reviewers may run in parallel only when the ticket allows it and their questions are distinct. - Codex workers receive a narrow file scope and must not edit outside it. +- Codex workers must stop and report a blocker when required files, specs, + steering files, or locked decisions are missing from the assigned context. - Codex workers must report changed files, commands run, proof, blockers, and risks to the manager. - Codex subagents must not write logs, memory files, closeout reports, or review diff --git a/templates/TEMPLATE.orchestrator-ticket.yaml b/templates/TEMPLATE.orchestrator-ticket.yaml index 649dcd0..e41b644 100644 --- a/templates/TEMPLATE.orchestrator-ticket.yaml +++ b/templates/TEMPLATE.orchestrator-ticket.yaml @@ -30,6 +30,30 @@ context: - "agent/PATHS.md" - "agent/SERVICES.md" - "agent/CHANGELOG.md" + grey_areas: + status: none + items: [] + resolution: "No unresolved planning or implementation grey areas before child-ticket creation." + +context_pack: + required_files: + - "Exact repository files the manager or child worker must read before planning or editing." + required_specs: + - "Specs that must be read, or [] when a justified quick-flow exemption applies." + required_steering_files: [] + excluded_context: + - "Relevant-looking context intentionally not loaded because it is noisy, stale, unsafe, or out of scope." + budget_notes: > + State the intended context budget for the manager and child workers, + including what is omitted and when work must stop instead of loading more + context. + +locked_decisions: + - decision: "Concrete decision locked before planning or implementation." + rationale: "Why this decision resolves a planning or implementation grey area." + owner: "user|manager|ticket|spec" + source: "Ticket, spec, user instruction, or agent/DECISIONS.md path." + "expiry/change rule": "When this decision expires or what must happen before it changes." spec_refs: requirements: "specs//requirements.md" @@ -161,6 +185,9 @@ test_plan: proof_gates: - "Non-trivial implementation work has linked requirements/design/tasks specs, or this orchestrator records a justified quick-flow exemption." + - "Grey-area status is `none`, `resolved`, or `blocked`; child implementation starts only when there are no unresolved grey areas." + - "Required context pack items are present and fit each worker budget, or the orchestrator records a blocker." + - "Required locked decisions are present before child implementation, or the orchestrator records a blocker." - "All required child tickets are done or explicitly deferred with blockers." - "Final verifier result is recorded." - "No unresolved blocker remains for the requested outcome." diff --git a/templates/TEMPLATE.ticket.yaml b/templates/TEMPLATE.ticket.yaml index c40f3e0..c4c23a3 100644 --- a/templates/TEMPLATE.ticket.yaml +++ b/templates/TEMPLATE.ticket.yaml @@ -21,6 +21,29 @@ context: Describe the target behavior and acceptance expectations. relevant_prior_work: - "Link or path to prior ticket/doc, or 'none'." + grey_areas: + status: none + items: [] + resolution: "No unresolved implementation grey areas before planning." + +context_pack: + required_files: + - "Exact repository files the worker must read before editing." + required_specs: + - "Specs that must be read, or [] when a justified quick-flow exemption applies." + required_steering_files: [] + excluded_context: + - "Relevant-looking context intentionally not loaded because it is noisy, stale, unsafe, or out of scope." + budget_notes: > + State the intended context budget for the worker, including what is omitted + and when the worker must stop instead of requesting or loading more context. + +locked_decisions: + - decision: "Concrete decision locked before implementation." + rationale: "Why this decision resolves an implementation grey area." + owner: "user|manager|ticket|spec" + source: "Ticket, spec, user instruction, or agent/DECISIONS.md path." + "expiry/change rule": "When this decision expires or what must happen before it changes." spec_refs: requirements: "specs//requirements.md" @@ -121,6 +144,9 @@ execution: - "Check whether agent files need updates and record the result." proof_gates: - "Non-trivial implementation work has linked requirements/design/tasks specs, or this ticket records a justified quick-flow exemption." + - "Grey-area status is `none`, `resolved`, or `blocked`; implementation starts only when there are no unresolved grey areas." + - "Required context pack items are present and fit the ticket budget, or the ticket records a blocker." + - "Required locked decisions are present before implementation, or the ticket records a blocker." - "Implementation matches desired behavior." - "Relevant automated checks pass or skipped checks are justified." - "Agent-memory update check is recorded." diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml index 290b7e1..765e834 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml @@ -25,6 +25,47 @@ context: - README.md - docs/workflow.md - templates/AGENTS.md.template + grey_areas: + status: resolved + items: + - Whether the context budget field should be named summary_budget or budget_notes. + resolution: User instruction for this execution uses budget_notes; update this ticket scope accordingly. +context_pack: + required_files: + - tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - templates/AGENTS.md.template + - prompts/manager-orchestrator.md + - prompts/scoped-worker.md + - checklists/ticket-readiness.md + - agent/DECISIONS.md + - docs/workflow.md + required_specs: [] + required_steering_files: [] + excluded_context: + - README.md version and install docs are relevant to the broader v0.4.0 upgrade but outside this ticket scope. + - templates/TEMPLATE.quick-ticket.yaml has older compact context fields but is outside allowed_files for this ticket. + - Local machine desktop policies are not relevant to this generic template change. + budget_notes: Keep worker context to the active ticket plus scoped workflow/template files. Do not load + private local paths, credentials, chat dumps, broad repo history, or unrelated package docs. Stop and + record a blocker if required files or decisions are missing instead of expanding context outside + allowed_files. +locked_decisions: +- decision: Use budget_notes as the context-pack budget field name for this ticket. + rationale: The latest user instruction explicitly requested budget_notes, superseding the older in-ticket + summary_budget wording. + owner: user + source: Current task instruction for tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml + "expiry/change rule": Change only through a new ticket or explicit user instruction that updates the + context-pack field contract. +- decision: Keep agent/DECISIONS.md generic and do not record this SDD ticket as a durable local closeout. + rationale: This repository is a workflow template, and the user explicitly prohibited local/task-specific + notes in agent files. + owner: user + source: Current task instruction + "expiry/change rule": Change only if a future ticket intentionally changes the template's decision-memory + policy. scope: goal: Add locked decisions and context-budget fields to ticket/orchestrator templates and prompts. allowed_files: @@ -47,7 +88,7 @@ scope: - coverage/** in_scope: - Add context_pack with required_files, required_specs, required_steering_files, excluded_context, and - summary_budget. + budget_notes. - Add locked_decisions with decision, rationale, owner, source, and expiry/change rule. - Update manager prompt to identify grey areas before planning and either resolve them or create a research_only decision ticket. @@ -126,17 +167,48 @@ execution: done_definition: Done when the scoped workflow/template improvement is implemented, required proof has passed or justified skips are recorded, and execution_result is complete. execution_result: - status: pending - changed_files: [] - commands_run: [] - proof: [] - skipped_checks: [] + status: done + changed_files: + - tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml + - templates/TEMPLATE.ticket.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - templates/AGENTS.md.template + - prompts/manager-orchestrator.md + - prompts/scoped-worker.md + - checklists/ticket-readiness.md + - agent/DECISIONS.md + - docs/workflow.md + commands_run: + - git status --short --branch + - rg -n "context_pack|locked_decisions|decision lock|grey|gray|research_only|required_files|required_specs|required_steering_files|excluded_context|budget_notes|expiry|change rule" templates prompts checklists agent docs tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml + - python -c "import yaml, pathlib; files=[pathlib.Path('tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml'), pathlib.Path('templates/TEMPLATE.ticket.yaml'), pathlib.Path('templates/TEMPLATE.orchestrator-ticket.yaml')]; [yaml.safe_load(p.read_text()) for p in files]; print('parsed', len(files), 'scoped yaml files')" + - rg -n "summary_budget|expiry_change_rule|context_pack\\.required_files|context_pack\\.required_specs|context_pack\\.budget_notes|locked_decisions|grey_areas|expiry/change rule|research_only" templates/TEMPLATE.ticket.yaml templates/TEMPLATE.orchestrator-ticket.yaml templates/AGENTS.md.template prompts/manager-orchestrator.md prompts/scoped-worker.md checklists/ticket-readiness.md agent/DECISIONS.md docs/workflow.md tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml + - python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path('.').rglob('*.yaml')]; print('parsed all yaml files')" + - git diff --check + proof: + - All repository YAML files parsed successfully with PyYAML. + - git diff --check passed with no whitespace errors. + - Changed files are limited to the ticket allowed_files list. + - Manager prompt now requires grey-area identification, resolution through decisions, or a research_only + blocker ticket before implementation assignment. + - Worker prompt now stops when required decisions or context-pack items are missing. + - agent/DECISIONS.md remains a reusable durable decision-lock template and does not contain a specific + SDD ticket closeout note. + skipped_checks: + - No dedicated markdown link checker is defined in the repo; path and terminology consistency was checked + with targeted rg output instead. agent_memory_updates: - checked: false - updated_files: [] - notes: null + checked: true + updated_files: + - agent/DECISIONS.md + notes: Updated only the reusable durable-decision template fields; no local, machine-specific, or + one-off task closeout note was added. blockers: [] risks: - 'Risk: too much ceremony for obvious tickets; mitigate by allowing grey_areas: none with proof from discovery.' - next_recommended_step: null + - 'Risk: templates/TEMPLATE.quick-ticket.yaml still has the older compact context_pack shape because it + was outside this ticket allowed_files.' + next_recommended_step: Use the updated ticket readiness checklist for the next non-trivial SDD ticket and + decide in a separate scoped ticket whether the quick-ticket template should gain the same expanded + context_pack fields. From d95d5eba2f70d32c669c00cf132d988ccef35aed Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:40:29 +0200 Subject: [PATCH 09/11] Prepare SDD workflow release 0.4.0 --- CHANGELOG.md | 10 ++ README.md | 101 +++++++++++++++--- VERSION | 2 +- agent/CHANGELOG.md | 5 + ...6-09-readme-terminology-version-0-4-0.yaml | 69 ++++++++++-- 5 files changed, 160 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d9bc655..a484ad3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,15 @@ # Changelog +## 0.4.0 - 2026-06-09 + +- Added the first SDD/context-engineering workflow upgrade for Codex-managed + repositories. +- Documented spec-first and spec-anchored workflow modes, context packs, + conditional steering, decision locks, context budgets, delta specs, expert + routing profiles, and spec drift verification. +- Clarified quick-flow versus full orchestrator criteria and added upgrade + guidance for existing target repositories. + ## 0.3.0 - 2026-05-23 - Added public release metadata for the Codex workflow template. diff --git a/README.md b/README.md index cb53ce5..2b97377 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,22 @@ # Agentic Engineering Workflow Template -Current version: 0.3.0 +Current version: 0.4.0 > **Codex 5.5-led setup:** do not install this workflow by hand first. > Use Codex 5.5 as the setup and orchestration agent, let it inspect the target > repository, and let it implement the workflow layer with a scoped setup plan. `Agentic Engineering Workflow Template` turns an existing or new repository into -a governed agentic engineering workspace. It gives Codex 5.5 an automatic -ticket, documentation, proof, and memory workflow so agent work stays scoped, -traceable, and reviewable. +a governed SDD/context-engineering workspace for Codex 5.5. It gives Codex an +automatic spec, ticket, documentation, proof, and memory workflow so agent work +stays scoped, traceable, and reviewable. The template is designed to reduce drift and hallucinations by forcing clear -ownership, explicit handoffs, maximum available repository context, proof gates, -and documentation checkpoints between every meaningful step. Tickets, notes, and -agent memory files act as the working memory for the agent system, so humans can -focus on engineering decisions instead of manually tracking what each agent did, -why it did it, and what must happen next. +ownership, explicit handoffs, bounded context packs, proof gates, spec drift +checks, and documentation checkpoints between every meaningful step. Specs, +tickets, notes, and agent memory files act as the working memory for the agent +system, so humans can focus on engineering decisions instead of manually +tracking what each agent did, why it did it, and what must happen next. It is not an app, framework, service, or runtime. Use it when work needs more structure than one chat prompt: multi-step delivery, risky refactors, UI changes @@ -26,6 +26,7 @@ implementation, review, and final verification. | Signal | Meaning | | --- | --- | | Codex 5.5 first | Use Codex 5.5 to understand, initialize, calibrate, and orchestrate the workflow. | +| SDD mode | Use specs, tickets, context packs, and proof gates to keep agent work anchored to explicit intent. | | Ticket-driven memory | Tickets, closeouts, and `agent/*.md` files preserve context between agent steps. | | Drift control | Scope, proof gates, role boundaries, and documentation checkpoints keep work reviewable. | | Target-repo installed | This template stays the source; the workflow files are installed into another repo. | @@ -57,15 +58,85 @@ the setup. ## Public Release Status -Version 0.3.0 is an early public template release for Codex-managed repository -workflows. It is meant to be copied, reviewed, and adapted inside a target -repository before relying on it for day-to-day work. +Version 0.4.0 is the first SDD/context-engineering upgrade for Codex-managed +repository workflows. It is meant to be copied, reviewed, and adapted inside a +target repository before relying on it for day-to-day work. Maturity: early practical template / pre-1.0. -The template is mature enough to describe repeatable Codex roles, scoped tickets, -proof expectations, and closeout records. It is not a guarantee that a target -repository is ready to ship. +The template is mature enough to describe repeatable Codex roles, scoped +tickets, spec artifacts, context packs, proof expectations, and closeout records. +It is not a guarantee that a target repository is ready to ship, and it does not +claim Spec-as-Source maturity. + +## SDD Mode + +SDD mode means Codex works from explicit intent before implementation. For +non-trivial changes, the manager should establish requirements, design, tasks, +and, when durable behavior changes, a delta spec before assigning scoped work. +The worker then implements against the ticket, linked specs, selected steering, +locked decisions, and bounded context pack instead of improvising from a single +chat prompt. + +This template supports two levels of SDD practice: + +| Mode | Use when | Required anchor | +| --- | --- | --- | +| Spec-first | New behavior, API, data, workflow, UI, security, migration, or architecture work needs explicit agreement before implementation. | Requirements, design, tasks, ticket scope, and delta spec when durable specs must change. | +| Spec-anchored | A smaller change can start from an existing ticket or current spec, but implementation still has to stay aligned with the recorded contract. | Existing current specs, ticket acceptance, context pack, locked decisions, and proof gates. | + +This is different from Vibe Coding. Codex can still move quickly, but the work +is not accepted because it "looks right" in a chat. The workflow asks Codex to +name the relevant files and specs, lock grey-area decisions, state what context +is intentionally excluded, prove the result, and record whether any spec drift +or follow-up remains. + +SDD artifacts in this template include: + +- `specs/current/**` for durable current behavior, contracts, workflows, and + important constraints after installation in a target repository. +- `specs/changes//proposal.md`, `delta-spec.md`, `design.md`, and + `tasks.md` for proposed changes. +- `templates/specs/TEMPLATE.*.md` for requirements, design, tasks, and delta + spec structure. +- `context_pack.required_files`, `context_pack.required_specs`, + `context_pack.required_steering_files`, `context_pack.excluded_context`, and + `context_pack.budget_notes` in ticket templates. +- `locked_decisions` for pre-implementation decisions that resolve grey areas. +- `templates/steering/*.md` for conditional steering that loads specialized + guidance only when file patterns, task types, or manual selection require it. +- `expert_routing` profiles for targeted read-only review by lens, such as + requirements, architecture, test, security/privacy, UX/visual, + performance/reliability, data migration, or docs/release. +- `prompts/spec-drift-verifier.md` for read-only comparison of specs, tickets, + implementation, tests, docs, and closeout. + +## Quick-Flow vs Full Orchestrator + +Use quick-flow only for tiny, clear, low-risk work that already has repository +discovery evidence, exact `allowed_files`, exact `forbidden_files`, concrete +Given-When-Then acceptance, proof, closeout, no-secrets handling, approval +boundaries, and a justified `spec_contract.quick_flow_exemption`. + +Use a full ticket or orchestrator when the change needs more than 3 non-ticket +files, more than 1 behavior module, requirements/design/tasks specs, a delta +spec lifecycle, conditional steering conflict resolution, expert routing, +architecture decisions, dependency changes, data migration, auth, security, +privacy, unclear acceptance, unavailable proof, visual/product ambiguity, files +outside scope, or spec drift repair. For larger delivery, the orchestrator owns +the context budget, creates child tickets, routes the minimum useful read-only +experts, and keeps specs, tickets, implementation, and proof aligned. + +## Upgrade Notes For Existing Targets + +Existing repositories initialized from 0.3.0 should update the workflow files +intentionally instead of blindly overwriting local rules. Ask Codex to compare +the target `AGENTS.md`, `agent/*.md`, ticket templates, prompts, checklists, +steering files, and specs against this template, preserve project-specific +rules, and add the 0.4.0 concepts only where they fit the target repository. +After updating, run one small calibration ticket and one quick-flow candidate to +confirm context packs, quick-flow escalation, spec drift verification, and +closeout records are working as expected. ## Codex Quickstart diff --git a/VERSION b/VERSION index 0d91a54..1d0ba9e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.3.0 +0.4.0 diff --git a/agent/CHANGELOG.md b/agent/CHANGELOG.md index a7c2167..45cad0c 100644 --- a/agent/CHANGELOG.md +++ b/agent/CHANGELOG.md @@ -3,6 +3,11 @@ Concise local workflow changelog. This is not a replacement for Git history or release notes. +## 2026-06-09 + +- `TKT-2026-06-09-readme-terminology-version-0-4-0`: recorded the template + 0.4.0 SDD/context-engineering release metadata and README terminology update. + ## YYYY-MM-DD - ``: `` diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml index 132eab1..9bfca00 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml @@ -131,17 +131,64 @@ execution: done_definition: Done when the scoped workflow/template improvement is implemented, required proof has passed or justified skips are recorded, and execution_result is complete. execution_result: - status: pending - changed_files: [] - commands_run: [] - proof: [] - skipped_checks: [] + status: completed + changed_files: + - README.md + - VERSION + - CHANGELOG.md + - agent/CHANGELOG.md + - tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml + commands_run: + - command: git status --short + result: Clean before edits; after docs edits, only allowed files were dirty. + - command: sed -n '1,240p' tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml + result: Read active ticket scope, allowed_files, proof gates, and closeout requirements. + - command: sed -n '1,260p' README.md && sed -n '261,520p' README.md + result: Inspected README terminology, release status, workflow sections, and reference links. + - command: sed -n '1,220p' CHANGELOG.md && sed -n '1,220p' agent/CHANGELOG.md && cat VERSION + result: Inspected current release metadata before editing. + - command: rg -n "workflow|spec|delta|conditional|drift|decision|context|expert|quick" docs templates prompts agent README.md + result: Checked existing SDD terminology and related template artifacts for README consistency. + - command: python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path('.').rglob('*.yaml')]" + result: Passed in the final validation pass after fixing a quoted command string in this ticket closeout. + - command: 'grep -R "Current version: 0.3.0" README.md' + result: No matches. + - command: 'grep -R "0.4.0" README.md VERSION CHANGELOG.md' + result: Found expected 0.4.0 matches in README.md, VERSION, and CHANGELOG.md. + - command: cat VERSION + result: Printed 0.4.0. + - command: git diff --check + result: Passed in the final validation pass. + - command: 'rg -n "Spec-as-Source|spec-first|Spec-first|spec-anchored|Spec-anchored|context pack|conditional steering|quick-flow|spec drift|delta spec|delta-spec|locked decisions|context budget|expert_routing|expert routing|prompts/spec-drift-verifier.md|templates/specs|templates/steering" README.md' + result: Found required README terminology and artifact references; README explicitly says it does not claim Spec-as-Source maturity. + - command: python - <<'PY' ... README markdown path link check ... PY + result: README markdown path links exist. + - command: 'rg -n "private local path|password|secret|token|api[_-]?key" README.md CHANGELOG.md agent/CHANGELOG.md VERSION tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml' + result: No private local paths or credentials were introduced; matches were generic no-secrets/security text and ticket regression-gate wording. + - command: git diff --name-only + result: Only allowed files were changed. + proof: + - VERSION now contains 0.4.0. + - README now says Current version: 0.4.0 and describes 0.4.0 as the first SDD/context-engineering upgrade. + - README explains SDD mode, Spec-first versus Spec-anchored, and how the workflow differs from Vibe Coding. + - README documents quick-flow versus full ticket/orchestrator criteria. + - README references spec artifacts, delta specs, context packs, conditional steering, locked decisions, context budget, expert routing profiles, and the spec drift verifier. + - README includes migration/upgrade notes for existing target repositories. + - CHANGELOG.md has a 0.4.0 section dated 2026-06-09 and preserves the 0.3.0 history. + - agent/CHANGELOG.md has a generic template release-history note for this SDD upgrade ticket. + - No local machine notes, secrets, credentials, private local paths, product runtime assumptions, release, publish, deploy, remote operation, dependency installation, or forbidden-file edits were introduced. + skipped_checks: + - Visual gate not run because this is a documentation/version metadata ticket and visual_gate.required is false. + - Product tests, dependency installation, release, tagging, publishing, and remote checks were not run because they are out of scope for this docs-only template ticket. agent_memory_updates: - checked: false - updated_files: [] - notes: null + checked: true + updated_files: + - agent/CHANGELOG.md + notes: Updated only the allowed generic template workflow changelog; no local machine notes or chat-specific details were added. blockers: [] risks: - - 'Risk: version bump before all SDD tickets are implemented; mitigate by running this ticket last in - the orchestrator sequence.' - next_recommended_step: null + - 'Risk: version bump before all SDD tickets are implemented; mitigated by keeping README language pre-1.0, + explicitly avoiding Spec-as-Source maturity claims, and recording that this is the 0.4.0 SDD/context-engineering + workflow upgrade.' + next_recommended_step: Final verifier should review this ticket result, confirm allowed-file scope, and decide whether + to checkpoint or mark the release-doc ticket done. From 0f8a7f477e7014509267a8556e61fc780db0fddd Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:43:11 +0200 Subject: [PATCH 10/11] Mark SDD upgrade tickets done --- .../TKT-2026-06-09-decision-lock-context-budget.yaml | 2 +- tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml | 2 +- tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml | 2 +- .../TKT-2026-06-09-readme-terminology-version-0-4-0.yaml | 2 +- tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml | 2 +- tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml index 765e834..2fde27b 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml @@ -4,7 +4,7 @@ ticket: title: Add grey-area decision locks and context-budget controls repo: agentic-engineering-workflow-template branch: main - status: backlog + status: done created_at: '2026-06-09' owner_agent: manager ticket_class: implementation diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml index 99e5fa0..a06ca31 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml @@ -4,7 +4,7 @@ ticket: title: Add OpenSpec-style delta-spec lifecycle for ongoing changes repo: agentic-engineering-workflow-template branch: main - status: backlog + status: done created_at: '2026-06-09' owner_agent: manager ticket_class: implementation diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml index 15cd122..2f73e08 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml @@ -4,7 +4,7 @@ ticket: title: Add routing profiles for the existing read-only expert team repo: agentic-engineering-workflow-template branch: main - status: backlog + status: done created_at: '2026-06-09' owner_agent: manager ticket_class: implementation diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml index 9bfca00..97268b0 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml @@ -4,7 +4,7 @@ ticket: title: Update README terminology and version metadata for SDD release 0.4.0 repo: agentic-engineering-workflow-template branch: main - status: backlog + status: done created_at: '2026-06-09' owner_agent: manager ticket_class: implementation diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml index 5aa0a8f..ad02e63 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml @@ -4,7 +4,7 @@ ticket: title: Add machine-readable SDD spec artifacts before implementation repo: agentic-engineering-workflow-template branch: main - status: backlog + status: done created_at: '2026-06-09' owner_agent: manager ticket_class: implementation diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml index b8e2ef5..d5a65cd 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml @@ -4,7 +4,7 @@ ticket: title: Add read-only spec drift verifier and cross-artifact proof gate repo: agentic-engineering-workflow-template branch: main - status: backlog + status: done created_at: '2026-06-09' owner_agent: manager ticket_class: implementation From 9fbab079609f8f4ff634d9b44da0599cffcf7982 Mon Sep 17 00:00:00 2001 From: Sascha Athmer <33932092+J0hnExample@users.noreply.github.com> Date: Thu, 11 Jun 2026 20:45:20 +0200 Subject: [PATCH 11/11] Close SDD upgrade orchestrator --- ...T-2026-06-09-sdd-upgrade-orchestrator.yaml | 129 ++++++++++++++++-- 1 file changed, 116 insertions(+), 13 deletions(-) diff --git a/tickets/sdd-upgrade/TKT-2026-06-09-sdd-upgrade-orchestrator.yaml b/tickets/sdd-upgrade/TKT-2026-06-09-sdd-upgrade-orchestrator.yaml index fb7df04..ded2c5e 100644 --- a/tickets/sdd-upgrade/TKT-2026-06-09-sdd-upgrade-orchestrator.yaml +++ b/tickets/sdd-upgrade/TKT-2026-06-09-sdd-upgrade-orchestrator.yaml @@ -3,8 +3,8 @@ ticket: id: TKT-2026-06-09-sdd-upgrade-orchestrator title: Orchestrate SDD/context-engineering upgrade for workflow template repo: agentic-engineering-workflow-template - branch: main - status: backlog + branch: feature/sdd-workflow-v0.4.0 + status: done created_at: '2026-06-09' owner_agent: manager ticket_class: orchestrator @@ -212,16 +212,119 @@ done_definition: Done when the SDD upgrade is delivered through completed child the agent memory update check is complete, and this orchestrator ticket contains a concise execution_result manager closeout. execution_result: - status: pending - child_ticket_status: [] - changed_files: [] - commands_run: [] - proof: [] - skipped_checks: [] + status: done + child_ticket_status: + - id: TKT-2026-06-09-expert-routing-profiles + status: done + commit: af1104b + - id: TKT-2026-06-09-spec-artifact-package + status: done + commit: be296f9 + - id: TKT-2026-06-09-delta-spec-lifecycle + status: done + commit: fd8856c + - id: TKT-2026-06-09-spec-drift-verifier + status: done + commit: 667d6f0 + - id: TKT-2026-06-09-conditional-steering + status: done + commit: 1e1b41f + - id: TKT-2026-06-09-quick-flow-escalation + status: done + commit: 4d40100 + - id: TKT-2026-06-09-decision-lock-context-budget + status: done + commit: df74f1b + - id: TKT-2026-06-09-readme-terminology-version-0-4-0 + status: done + commit: d95d5eb + changed_files: + - README.md + - VERSION + - CHANGELOG.md + - agent/CHANGELOG.md + - agent/DECISIONS.md + - checklists/closeout.md + - checklists/spec-drift.md + - checklists/ticket-readiness.md + - docs/sdd_article_integration_evaluation.md + - docs/spec_lifecycle.md + - docs/workflow.md + - prompts/final-verifier.md + - prompts/initialize-repo.md + - prompts/manager-orchestrator.md + - prompts/quick-dev.md + - prompts/read-only-expert.md + - prompts/scoped-worker.md + - prompts/spec-drift-verifier.md + - templates/AGENTS.md.template + - templates/TEMPLATE.execution-result.yaml + - templates/TEMPLATE.orchestrator-ticket.yaml + - templates/TEMPLATE.quick-ticket.yaml + - templates/TEMPLATE.ticket.yaml + - templates/specs/TEMPLATE.delta-spec.md + - templates/specs/TEMPLATE.design.md + - templates/specs/TEMPLATE.requirements.md + - templates/specs/TEMPLATE.tasks.md + - templates/steering/product.md + - templates/steering/security.md + - templates/steering/structure.md + - templates/steering/tech.md + - templates/steering/testing.md + - tickets/sdd-upgrade/README.md + - tickets/sdd-upgrade/TKT-2026-06-09-conditional-steering.yaml + - tickets/sdd-upgrade/TKT-2026-06-09-decision-lock-context-budget.yaml + - tickets/sdd-upgrade/TKT-2026-06-09-delta-spec-lifecycle.yaml + - tickets/sdd-upgrade/TKT-2026-06-09-expert-routing-profiles.yaml + - tickets/sdd-upgrade/TKT-2026-06-09-quick-flow-escalation.yaml + - tickets/sdd-upgrade/TKT-2026-06-09-readme-terminology-version-0-4-0.yaml + - tickets/sdd-upgrade/TKT-2026-06-09-sdd-upgrade-orchestrator.yaml + - tickets/sdd-upgrade/TKT-2026-06-09-spec-artifact-package.yaml + - tickets/sdd-upgrade/TKT-2026-06-09-spec-drift-verifier.yaml + commands_run: + - git apply --check sdd_upgrade_tickets_v2.patch + - git apply -p5 sdd_upgrade_tickets_v2.patch + - python -c "import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path('.').rglob('*.yaml')]" + - git diff --check + - python markdown relative path link sanity check for README, docs, prompts, and checklists + - grep -R "Current version: 0.3.0" README.md + - grep -R "0.4.0" README.md VERSION CHANGELOG.md + - cat VERSION + - rg secret/private-local-path pattern scan across README, changelogs, docs, prompts, checklists, templates, + tickets, and agent files + - read-only final verifier subagent pass after ticket status fix + proof: + - Patch/ticket set applied from sdd_upgrade_tickets_v2.patch and committed before implementation. + - Eight child tickets were implemented serially with one subagent per ticket, then reviewed by the manager. + - All child implementation tickets now have ticket.status done and execution_result.status done or completed. + - VERSION is 0.4.0, README has Current version 0.4.0, and CHANGELOG.md preserves the 0.3.0 history. + - README explicitly avoids claiming Spec-as-Source maturity and documents SDD mode, Spec-first, + Spec-anchored, quick-flow versus full orchestrator criteria, and upgrade notes. + - Workflow now includes requirements/design/tasks specs, delta specs with ADDED/MODIFIED/REMOVED, spec + drift verification, conditional steering, quick-flow escalation, decision locks/context budget, and + expert routing profiles. + - YAML parse passed for all repository YAML files. + - git diff --check passed. + - Markdown relative path link sanity check passed; markdownlint was unavailable. + - Secret/private-local-path pattern scan produced no actionable matches after removing a local-path search + pattern from one ticket closeout. + - Read-only final verifier found an initial ticket-status blocker; it was fixed and rechecked with PASS. + skipped_checks: + - markdownlint was not installed in the environment; a repository-local Markdown path-link sanity check was + run instead. + - Product lint, typecheck, build, runtime tests, browser checks, deployment, release, and tagging were not + run because this repository is a workflow/template documentation package and no runtime product code + changed. agent_memory_updates: - checked: false - updated_files: [] - notes: null + checked: true + updated_files: + - agent/CHANGELOG.md + - agent/DECISIONS.md + notes: Updated only generic template files in allowed scope. No local machine notes, private paths, + secrets, or chat-specific closeout notes were added to agent files. blockers: [] - risks: [] - next_recommended_step: null + risks: + - Existing target repositories must adopt the 0.4.0 workflow intentionally and preserve their project-specific + rules instead of blindly overwriting local AGENTS.md or agent memory. + - markdownlint was unavailable, so Markdown style beyond link existence was not automatically checked. + next_recommended_step: Push feature/sdd-workflow-v0.4.0 and open a pull request for review.