From 60d735e51bceed850deeff10526c1f2d38fb4435 Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Thu, 12 Nov 2026 00:34:25 +0200 Subject: [PATCH 1/2] add a generated plan overview to the Spec Kit preset Dense agent-facing plans took days to read, and reviewer fixes could change the design without the human seeing it. The preset now gives the human a read-only plan-overview.md generated from plan.md, so Design Acceptance rests on a readable view with no second source to drift from. /speckit.plan generates the overview after the first plan draft and again before Design Acceptance. A writer role packet produces it, and a new plan-overview-fidelity reviewer checks it against plan.md once the design and clarity reviews pass. Plan review reruns also receive the human's recorded dispositions from review-dispositions.md, so declined findings are not raised again without new evidence. Bumps the preset to 0.5.0 and adds the local fidelity reviewer agent for Claude and OpenCode. --- ...er-plan-overview-fidelity-reviewer.md.tmpl | 51 +++++++++++++++++++ docs/spec-kit-workflow/architecture.md | 45 +++++++++------- ...er-plan-overview-fidelity-reviewer.md.tmpl | 7 +++ .../agents/mid-tier-technical-writer.md.tmpl | 2 +- ...er-plan-overview-fidelity-reviewer.md.tmpl | 15 ++++++ .../agents/mid-tier-technical-writer.md.tmpl | 2 +- .../presets/timors-agentic-workflow/README.md | 12 +++-- .../commands/speckit.plan.md | 44 +++++++++++----- .../timors-agentic-workflow/preset.yml | 4 +- .../references/artifact-contracts.md | 2 + .../references/model-and-worker-selection.md | 11 ++-- .../references/plan-lifecycle.md | 9 +++- .../references/review-lifecycle.md | 12 ++++- .../reviewers/plan-clarity.md | 6 ++- .../reviewers/plan-design.md | 6 ++- .../reviewers/plan-overview-fidelity.md | 21 ++++++++ .../templates/plan-overview-template.md | 18 +++++++ .../templates/plan-template.md | 1 + .../templates/review-dispositions-template.md | 17 +++++++ .../writers/plan-overview.md | 24 +++++++++ 20 files changed, 261 insertions(+), 48 deletions(-) create mode 100644 .chezmoitemplates/agent-mid-tier-plan-overview-fidelity-reviewer.md.tmpl create mode 100644 dot_claude/agents/mid-tier-plan-overview-fidelity-reviewer.md.tmpl create mode 100644 private_dot_config/opencode/agents/mid-tier-plan-overview-fidelity-reviewer.md.tmpl create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-overview-fidelity.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-overview-template.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/templates/review-dispositions-template.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/writers/plan-overview.md diff --git a/.chezmoitemplates/agent-mid-tier-plan-overview-fidelity-reviewer.md.tmpl b/.chezmoitemplates/agent-mid-tier-plan-overview-fidelity-reviewer.md.tmpl new file mode 100644 index 0000000..028be33 --- /dev/null +++ b/.chezmoitemplates/agent-mid-tier-plan-overview-fidelity-reviewer.md.tmpl @@ -0,0 +1,51 @@ +You are the plan overview fidelity reviewer for the Spec Kit "timors-agentic-workflow" preset. You check +that the human plan overview (`plan-overview.md`) faithfully reflects the normative plan (`plan.md`). This is +a mid-tier role. + +You review one feature's overview independently, after the plan design and clarity reviews have passed. You +do not modify any reviewed artifact — your only output is your review report. You do not review the plan's +design or clarity, and you do not record the human Design Acceptance decision. + +## Assignment + +The caller gives you a reviewer packet (role, tier, inputs, workspace, exclusions) and the path to your +cumulative review report. The packet is authoritative for the exact inputs and scope. Read the current +`spec.md` intent, `plan.md`, `plan-overview.md`, the overview contract the packet names, and the prior +report. If the packet's scope and this file disagree, follow the packet. If anything would force you to +mutate the workspace or review your own work, stop and report a blocker instead. + +## What You Check + +- The overview header names the current `plan.md` Revision. +- The intent restatement agrees with `spec.md`. +- No statement contradicts, bends, or adds to a `plan.md` decision. +- Every titled Design Decision in `plan.md` is explained in the overview body or named in its Not Covered + Here list. A one-line Not Covered Here entry fully satisfies coverage. + +## What You Do Not Flag + +- An overview that is short, or a topic the writer chose to list instead of explain. +- A request to move a Not Covered Here item into the body. +- Plan design or clarity issues; those roles own them. When `plan.md` itself prevents a faithful overview, + report that finding at its `plan.md` location. + +## Evidence and Workspace + +- Do not modify any reviewed artifact. Your only write is your review report, at the path the caller provides. + A change to any reviewed artifact invalidates your result. +- Read the named inputs and only the sources they reference. + +## Output + +Append one complete current-state round to the review report at the path the caller gives you, following the +preset review report template: + +- Keep the header current: Role, Tier, Latest Round, Latest Verdict. +- Add the next sequential `### RNN` round with Trigger (initial | targeted change | recovery), Scope, + Reviewed Paths, Binding Evidence, and Verdict. +- Record each finding with a semantic title, Impact (blocking | concern), Location, Evidence, and a concrete + Recommendation. + +Reviews are cumulative. Read the existing report first, preserve every earlier round exactly, and carry +unaffected current findings into a targeted rerun. The verdict is one of `passed`, `passed-with-concerns`, or +`blocking`. Do not use opaque finding identifiers or disposition matrices. diff --git a/docs/spec-kit-workflow/architecture.md b/docs/spec-kit-workflow/architecture.md index bce5ecc..9b13c7a 100644 --- a/docs/spec-kit-workflow/architecture.md +++ b/docs/spec-kit-workflow/architecture.md @@ -3,11 +3,11 @@ ## Overview `timors-agentic-workflow` is a project-installed Spec Kit preset that connects -grounded planning, optional human review, reviewed execution decomposition, +grounded planning, a generated human plan overview, reviewed execution decomposition, explicit human approval, and delegated implementation through a versioned Markdown protocol. The preset is provider-neutral: it defines command and artifact contracts, while the active coding integration supplies concrete -workers, models, skills, and permissions. Its preset version is `0.4.1` and its +workers, models, skills, and permissions. Its preset version is `0.5.0` and its protocol version is `0.1.0`; it supports Spec Kit `>=0.12.11` without an upper support boundary. @@ -88,11 +88,11 @@ to their owning generation command rather than being migrated or inferred. The preset deliberately uses different integration strategies by phase: - `/speckit.specify` composes with upstream specification generation, retaining - its behavior and adding optional human review at natural completion; + its behavior; `/speckit.clarify` remains upstream and owns product clarification. - `/speckit.plan` and `plan-template` compose with upstream planning, retaining its design artifacts, adding verified grounding and integration context, and - offering optional human review at natural completion. + generating the human plan overview. - `/speckit.tasks`, `tasks-template`, and `/speckit.implement` replace their upstream surfaces because decomposition, independent review, approval, and delegated execution share a stronger protocol. The preset provides no @@ -115,19 +115,19 @@ the structural package-integrity contract come from the installed manifest and i section above. This architecture overview summarizes those boundaries without redefining them. -### Optional Human Review +### Plan Overview -At the natural completion of specification and planning, after artifacts are -generated and validated, each phase independently offers a guided walkthrough -or independent review. Either can be declined. The interaction stores no -preference, approval record, or workflow gate, and does not apply to the -independent review or approval gates. -The installed `human-review.md` reference owns the mechanics: select small, -consequential review units using judgment; pause after each; update and -revalidate current-phase artifacts once a unit is settled; then continue normal -completion reporting and handoffs. Command projections own the phase-specific -conceptual focus, while supporting artifacts remain evidence sources rather -than mandatory walkthrough stops. +`/speckit.plan` has a bound mid-tier writer generate `plan-overview.md`, a +non-normative human view of `plan.md`, twice: after the first plan draft, so the +human confirms direction before reviews, and after design and clarity reviews +pass, so the human reads the final shape before Design Acceptance. The overview +names the plan Revision it reflects, restates the Feature Definition intent, +explains only what the human needs to accept or reject the design, and lists +every other topic under Not Covered Here with a pointer into `plan.md`. The +writer never adds, changes, or settles a decision; a change of mind becomes a +`plan.md` decision and the overview is regenerated. No phase reads the overview +as input. The writer packet in `writers/plan-overview.md` owns the overview +contract. ## Artifact Ownership @@ -148,6 +148,12 @@ The protocol separates durable planning truth from local runtime evidence: - The human approval decisions live in their owning artifacts: Design Acceptance in `plan.md` and Implementation Authorization in `tasks.md`. The preset produces no separate `analysis.md` aggregate. +- `plan-overview.md` is the generated, non-normative human view of `plan.md`. + `plan.md` prevails on conflict, and no phase reads the overview as input. +- `review-dispositions.md` records, per answered plan review batch, each + finding's disposition and the human's reason. Only the `plan-design` and + `plan-clarity` reviewers read it, so reruns can tie new findings to earlier + fixes and do not raise declined findings again without new evidence. - `specs//progress.md` is an ignored local ledger for concrete workers and models, workspaces, dispatch and test evidence, checkpoints, blockers, failures, integration state, and resume decisions. It does not duplicate @@ -169,7 +175,9 @@ approval until the reviews permit it: - `/speckit.plan` requires most-capable `plan-design`, which judges technical coherence of the plan, and mid-tier `plan-clarity`, which judges cold-reader - clarity of the plan. Both feed Design Acceptance in `plan.md`. + clarity of the plan. After both pass, mid-tier `plan-overview-fidelity` checks + that `plan-overview.md` matches `plan.md`. All three feed Design Acceptance in + `plan.md`. - `/speckit.tasks` requires mid-tier `tasks-plan-fidelity`, which traces the accepted plan and Feature Definition into the task package, and most-capable `tasks-executability`, which judges decomposition feasibility and testable @@ -260,8 +268,7 @@ skills, consume their plan format, or depend on them at runtime. ## Verified Scope Deterministic validation covers the manifest, structural package inventory, -command and template mappings, optional human-review command/reference -projections, project installation and remove/add refresh, all six template +command and template mappings, project installation and remove/add refresh, all six template resolutions, generated OpenCode commands, project-relative preset references, tracked asset behavior, and targeted chezmoi rendering. These checks do not invoke generated commands through a model and do not prove semantic runtime diff --git a/dot_claude/agents/mid-tier-plan-overview-fidelity-reviewer.md.tmpl b/dot_claude/agents/mid-tier-plan-overview-fidelity-reviewer.md.tmpl new file mode 100644 index 0000000..6c8ee33 --- /dev/null +++ b/dot_claude/agents/mid-tier-plan-overview-fidelity-reviewer.md.tmpl @@ -0,0 +1,7 @@ +--- +name: mid-tier-plan-overview-fidelity-reviewer +description: "Use this agent to review the human plan overview (plan-overview.md) in the Spec Kit timors-agentic-workflow preset for fidelity to the normative plan (plan.md). Mid-tier role. Runs after the plan design and clarity reviews pass. Checks that the overview names the current plan Revision, agrees with the Feature Definition intent, does not contradict, bend, or add to any plan decision, and explains or lists every titled Design Decision. Does not review plan design or clarity.\n\n\nContext: A plan passed design and clarity review and its overview was regenerated.\nuser: \"Check specs/003-auth/plan-overview.md against plan.md for fidelity.\"\nassistant: \"I'll check that the overview matches the plan and append fidelity findings.\"\n" +tools: Read, Glob, Grep, Write, Edit +--- + +{{ template "agent-mid-tier-plan-overview-fidelity-reviewer.md.tmpl" . }} diff --git a/dot_claude/agents/mid-tier-technical-writer.md.tmpl b/dot_claude/agents/mid-tier-technical-writer.md.tmpl index c3a8b6e..e794158 100644 --- a/dot_claude/agents/mid-tier-technical-writer.md.tmpl +++ b/dot_claude/agents/mid-tier-technical-writer.md.tmpl @@ -1,6 +1,6 @@ --- name: mid-tier-technical-writer -description: Authors and edits human-readable engineering documentation — design docs and RFC narratives written for a person to understand a design, not for an agent to execute it. Use it to create such a doc from a source (design notes or an existing agent-oriented RFC), normally section by section with review between chunks; and use it again for later editing passes on the same doc — clarifying wording, simplifying dense or math-heavy passages, restructuring, fixing terminology, or stripping jargon and code-level detail. It writes narrative-first (set up the question, state the point, then why), glosses technical and math terms for non-specialist and non-native readers, keeps code-level detail out of the prose unless precision needs it, and prefers the project's established vocabulary. Not for agent-targeted RFCs or execution plans, nor for domain/architecture/component reference docs. +description: Authors and edits human-readable engineering documentation — design docs and RFC narratives written for a person to understand a design, not for an agent to execute it. Use it to create such a doc from a source (design notes or an existing agent-oriented RFC), in one pass or section by section, as the caller directs; and use it again for later editing passes on the same doc — clarifying wording, simplifying dense or math-heavy passages, restructuring, fixing terminology, or stripping jargon and code-level detail. It writes narrative-first (set up the question, state the point, then why), glosses technical and math terms for non-specialist and non-native readers, keeps code-level detail out of the prose unless precision needs it, and prefers the project's established vocabulary. Not for agent-targeted RFCs or execution plans, nor for domain/architecture/component reference docs. tools: Read, Write, Edit model: sonnet effort: medium diff --git a/private_dot_config/opencode/agents/mid-tier-plan-overview-fidelity-reviewer.md.tmpl b/private_dot_config/opencode/agents/mid-tier-plan-overview-fidelity-reviewer.md.tmpl new file mode 100644 index 0000000..be9333d --- /dev/null +++ b/private_dot_config/opencode/agents/mid-tier-plan-overview-fidelity-reviewer.md.tmpl @@ -0,0 +1,15 @@ +--- +name: mid-tier-plan-overview-fidelity-reviewer +description: "Use this agent to review the human plan overview (plan-overview.md) in the Spec Kit timors-agentic-workflow preset for fidelity to the normative plan (plan.md). Mid-tier role. Runs after the plan design and clarity reviews pass. Checks that the overview names the current plan Revision, agrees with the Feature Definition intent, does not contradict, bend, or add to any plan decision, and explains or lists every titled Design Decision. Does not review plan design or clarity.\n\n\nContext: A plan passed design and clarity review and its overview was regenerated.\nuser: \"Check specs/003-auth/plan-overview.md against plan.md for fidelity.\"\nassistant: \"I'll check that the overview matches the plan and append fidelity findings.\"\n" +mode: subagent +permission: + edit: allow + bash: deny + webfetch: deny + task: + "*": deny + skill: + "*": deny +--- + +{{ template "agent-mid-tier-plan-overview-fidelity-reviewer.md.tmpl" . }} diff --git a/private_dot_config/opencode/agents/mid-tier-technical-writer.md.tmpl b/private_dot_config/opencode/agents/mid-tier-technical-writer.md.tmpl index bf80bb4..7636655 100644 --- a/private_dot_config/opencode/agents/mid-tier-technical-writer.md.tmpl +++ b/private_dot_config/opencode/agents/mid-tier-technical-writer.md.tmpl @@ -1,6 +1,6 @@ --- name: mid-tier-technical-writer -description: Authors and edits human-readable engineering documentation — design docs and RFC narratives written for a person to understand a design, not for an agent to execute it. Use it to create such a doc from a source (design notes or an existing agent-oriented RFC), normally section by section with review between chunks; and use it again for later editing passes on the same doc — clarifying wording, simplifying dense or math-heavy passages, restructuring, fixing terminology, or stripping jargon and code-level detail. It writes narrative-first (set up the question, state the point, then why), glosses technical and math terms for non-specialist and non-native readers, keeps code-level detail out of the prose unless precision needs it, and prefers the project's established vocabulary. Not for agent-targeted RFCs or execution plans, nor for domain/architecture/component reference docs. +description: Authors and edits human-readable engineering documentation — design docs and RFC narratives written for a person to understand a design, not for an agent to execute it. Use it to create such a doc from a source (design notes or an existing agent-oriented RFC), in one pass or section by section, as the caller directs; and use it again for later editing passes on the same doc — clarifying wording, simplifying dense or math-heavy passages, restructuring, fixing terminology, or stripping jargon and code-level detail. It writes narrative-first (set up the question, state the point, then why), glosses technical and math terms for non-specialist and non-native readers, keeps code-level detail out of the prose unless precision needs it, and prefers the project's established vocabulary. Not for agent-targeted RFCs or execution plans, nor for domain/architecture/component reference docs. mode: subagent model: openai/gpt-5.6-terra reasoningEffort: medium diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/README.md b/private_dot_config/specify/presets/timors-agentic-workflow/README.md index 61ef20b..79c7a26 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/README.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/README.md @@ -1,10 +1,12 @@ # Timor's Agentic Workflow -Preset `0.4.1` supplies one project-installed lifecycle: +Preset `0.5.0` supplies one project-installed lifecycle: `specify` → `clarify` when Draft → `plan` → `tasks` → `implement`. `spec.md` is the Feature Definition, `plan.md` is the sole normative plan, +`plan-overview.md` is its generated, non-normative human view, +`review-dispositions.md` records human answers to plan review findings, `tasks.md` and `subplans/` are the reviewed execution package, and ignored local `progress.md` is coordinator runtime evidence. Design Acceptance precedes task creation; Implementation Authorization precedes mutation. @@ -38,9 +40,10 @@ Task packages contain provider-neutral tiers and the skills each group needs, no concrete workers, model IDs, credentials, local workspace paths, or dispatch identities. Binding is just in time. An implementation group requires its tier, skills, discoverability, invokability, correct workspace targeting, and -attributable results. A reviewer role requires its tier and a single candidate +attributable results. A reviewer or writer role requires its tier and a single candidate whose description matches the role. The reviewer does not modify the reviewed -artifacts and writes only its review report. Project-local +artifacts and writes only its review report; the writer modifies only its +declared output. Project-local candidates are preferred; ambiguity requires a human choice. Runtime considerations neither grant access nor alter eligibility. @@ -52,7 +55,8 @@ order as one repository-policy-compliant commit per packet. Nothing is pushed. ## Replacement Cautions -This release performs no migration. It does not interpret old atomic task lists, +This release performs no migration. A plan created under `0.4.x` lacks the +`plan_overview_fidelity` Review Record entry and restarts its plan phase. It does not interpret old atomic task lists, old execution or review artifacts, or old local runtime state. A non-executing old feature starts again at `specify`. Before replacement, finish or explicitly abandon an in-flight old run while its old installed copy remains available. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.plan.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.plan.md index 05dddb5..ba29722 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.plan.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.plan.md @@ -1,5 +1,5 @@ --- -description: Ground, design, review, and obtain acceptance for the normative plan. +description: Ground, design, review, explain, and obtain acceptance for the normative plan. --- ## Authority and Inputs @@ -11,10 +11,15 @@ reading any artifact. Read `.specify/presets/timors-agentic-workflow/references/artifact-contracts.md`, `.specify/presets/timors-agentic-workflow/references/planning-grounding.md`, `.specify/presets/timors-agentic-workflow/references/plan-lifecycle.md`, `.specify/presets/timors-agentic-workflow/references/review-lifecycle.md`, `.specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md`, and reviewer packets -`.specify/presets/timors-agentic-workflow/reviewers/plan-design.md` and `.specify/presets/timors-agentic-workflow/reviewers/plan-clarity.md`. Use +`.specify/presets/timors-agentic-workflow/reviewers/plan-design.md`, `.specify/presets/timors-agentic-workflow/reviewers/plan-clarity.md`, and +`.specify/presets/timors-agentic-workflow/reviewers/plan-overview-fidelity.md`, and writer packet +`.specify/presets/timors-agentic-workflow/writers/plan-overview.md`. Use `.specify/presets/timors-agentic-workflow/templates/grounding-notes-template.md`, `.specify/presets/timors-agentic-workflow/templates/research-template.md`, -`.specify/presets/timors-agentic-workflow/templates/plan-template.md`, and `.specify/presets/timors-agentic-workflow/templates/review-report-template.md`. A project -constitution is optional governance input. `plan.md` is the sole normative plan. +`.specify/presets/timors-agentic-workflow/templates/plan-template.md`, `.specify/presets/timors-agentic-workflow/templates/review-report-template.md`, +`.specify/presets/timors-agentic-workflow/templates/plan-overview-template.md`, and +`.specify/presets/timors-agentic-workflow/templates/review-dispositions-template.md`. A project +constitution is optional governance input. `plan.md` is the sole normative plan; +`plan-overview.md` is its non-normative human view. ## Procedure @@ -32,13 +37,28 @@ constitution is optional governance input. `plan.md` is the sole normative plan. planning. Classify changes before writing, apply Revision, acceptance, and review-pointer transitions exactly as `.specify/presets/timors-agentic-workflow/references/plan-lifecycle.md` requires, and refuse a material change after the package lock. -4. Bind, invoke, and record independent design and clarity reviews under +4. Bind the writer under + `.specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md` + and have it generate `plan-overview.md` for the current Revision. Present it to + the human to confirm direction before any review. A change of direction is a + human decision: record it in `plan.md` under step 3 (or return `spec.md` to + Draft when intent changes), then regenerate the overview. This overview is not + fidelity-reviewed. +5. Bind, invoke, and record independent design and clarity reviews under `.specify/presets/timors-agentic-workflow/references/review-lifecycle.md`. Remediate - only findings that review lifecycle permits directly or a human accepted. Rerun only - applicable scope; retain unaffected roles only through the stated retained - pointer transition. At review quiescence present one collected blocker and - proposed-remediation interaction. A started incomplete review uses recovery, - never self-review. -5. Request Design Acceptance only when both pointers are current, attributable, - and non-blocking for the current plan Revision. Record the human decision and + only findings that review lifecycle permits directly or a human accepted. After + each human answer, append its dispositions to `review-dispositions.md` before + any rerun. Rerun only applicable scope; retain unaffected roles only through the + stated retained pointer transition. At review quiescence present one collected + blocker and proposed-remediation interaction. A started incomplete review uses + recovery, never self-review. +6. When `plan_design` and `plan_clarity` are current and non-blocking, have the + writer regenerate `plan-overview.md` for the current Revision, then bind, + invoke, and record the overview fidelity review. The writer applies fidelity + fixes that only bring the overview into agreement with `plan.md`, then the + review reruns. A fidelity finding located in `plan.md` is a proposed + remediation and returns to step 5 after the material change. +7. Request Design Acceptance only when all three pointers are current, + attributable, and non-blocking for the current plan Revision, and present + `plan-overview.md` as the human's reading basis. Record the human decision and rationale in `plan.md`. Only current Revision Accepted permits `tasks`. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/preset.yml b/private_dot_config/specify/presets/timors-agentic-workflow/preset.yml index 1676e8a..71fa9ff 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/preset.yml +++ b/private_dot_config/specify/presets/timors-agentic-workflow/preset.yml @@ -3,7 +3,7 @@ schema_version: "1.0" preset: id: "timors-agentic-workflow" name: "Timor's Agentic Workflow" - version: "0.4.1" + version: "0.5.0" description: "Plan-backed feature definition, reviewed task packages, and isolated packet execution." author: "Timor Gruber" license: "MIT" @@ -28,7 +28,7 @@ provides: - type: "command" name: "speckit.plan" file: "commands/speckit.plan.md" - description: "Ground, review, and accept the normative plan." + description: "Ground, review, explain, and accept the normative plan." strategy: "replace" replaces: "speckit.plan" - type: "command" diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-contracts.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-contracts.md index f23f6fc..1220d9f 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-contracts.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-contracts.md @@ -4,6 +4,8 @@ |---|---|---| | `spec.md` | Feature Definition | `status: Ready` before `plan` | | `plan.md` | Sole normative plan | current Revision has human Design Acceptance `Accepted` before `tasks` | +| `plan-overview.md` | non-normative human view of `plan.md` | none; no phase reads it, and `plan.md` prevails on conflict | +| `review-dispositions.md` | human dispositions of plan review findings | read only by `plan_design` and `plan_clarity` reviewers; no `tasks` or `implement` input | | `tasks.md` and indexed `subplans/` | immutable execution package | both current reviews permit and `authorization: approved` before `implement` | | role reports | cumulative review evidence | pointer resolves to an attributable applicable non-blocking complete round | | ignored `progress.md` | coordinator-owned runtime evidence | exact durable evidence before resume, integration, or completion | diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md index 20b7b02..457317b 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md @@ -1,12 +1,13 @@ # Binding, Runtime Conditions, and Result Attribution -A tracked reviewer names a provider-neutral tier and a role description. A tracked +A tracked reviewer or writer names a provider-neutral tier and a role description. A tracked implementation packet names a provider-neutral tier and the skills and capabilities the group needs. Eligibility requires the requested tier, native discoverability, invokability, correct workspace targeting, and attributable results; a reviewer additionally must not modify the artifacts it reviews and -writes only its review report, outside the reviewed set. Prefer a -project-local candidate. For a reviewer, match the role description against the +writes only its review report, outside the reviewed set; a writer additionally +modifies only its declared output. Prefer a +project-local candidate. For a reviewer or writer, match the role description against the candidate descriptions and select a single clear fit. For an implementation packet, match the named skills and capabilities and select a single eligible candidate. A unique fit, a sole eligible candidate, or an explicit human choice @@ -30,4 +31,6 @@ verification, handoff, or semantic contract content. On conflict the selected sub-plan prevails. An applicable empty runtime-outcome set is explicit. Reviewer results additionally prove role, reviewed paths, round, verdict, that no reviewed artifact was modified, and attribution; a modification of any reviewed artifact -rejects the result. +rejects the result. Writer results additionally prove role, written path, +reflected plan Revision, and that no other artifact was modified; a modification +of any other artifact rejects the result. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/plan-lifecycle.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/plan-lifecycle.md index b2b4a41..fdad7ab 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/plan-lifecycle.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/plan-lifecycle.md @@ -20,7 +20,8 @@ planning. A material plan change increments Revision and, before writing, makes Accepted or Rejected acceptance Stale; Pending stays Pending. Editorial changes retain Revision and acceptance. Refuse a material write after the progress lock. -The Review Record has fixed `plan_design` and `plan_clarity` records, each with +The Review Record has fixed `plan_design`, `plan_clarity`, and +`plan_overview_fidelity` records, each with report path, round (`RNN` or `None`), plan revision (`RNN` or `None`), Status (`Pending`, `Reviewed`, `Retained`, `Recovery required`), and Verdict (`Pending`, `Passed`, `Passed with concerns`, `Blocking`). A role is current only if Reviewed @@ -28,7 +29,11 @@ or Retained, its round exists in its report, its revision equals current Revisio and its verdict passes or passes with concerns. See `references/review-lifecycle.md` for dispatch and recovery. -First complete plan review runs both roles. Editorial, evidence repair, or a +First complete plan review runs `plan_design` and `plan_clarity`. +`plan_overview_fidelity` runs only after both are current and non-blocking for +the current Revision, against `plan-overview.md` regenerated for that Revision. +Any material plan change makes it Pending, because the overview is regenerated; +an editorial plan change leaves it Retained. Editorial, evidence repair, or a finding-specific repair needs no rerun only when it leaves architecture, boundary, contract, flow, state, compatibility, migration, failure behavior, risk posture, and cold-reader meaning unchanged. Otherwise rerun affected role scope. Before a diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/review-lifecycle.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/review-lifecycle.md index bfd3388..16188f0 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/review-lifecycle.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/review-lifecycle.md @@ -41,7 +41,17 @@ the phase completion report. Every other fix, including one that fills a gap no human decided, is a proposed remediation: collect it with its finding, the reviewer recommendation, and the affected artifact sections, and apply it only after a human accepts it. Report each declined proposal with its human disposition -at phase completion. +at phase completion. A `plan_overview_fidelity` fix that only brings +`plan-overview.md` into agreement with `plan.md` changes no decision: the bound +writer applies it directly, and it is listed in the phase completion report. A +fidelity finding located in `plan.md` is a proposed remediation. + +After a human answers a batch of plan review findings, and before any rerun, +the producing phase appends one section to `review-dispositions.md` from +`.specify/presets/timors-agentic-workflow/templates/review-dispositions-template.md`: +each finding title, its role and round, accepted or declined, the applied +`plan.md` location, and the human's reason. Plan reviewers read it; no other +phase does. A producing phase is quiescent only when no pending role can safely dispatch, resume, or complete without a collected binding or recovery blocker. Then present diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-clarity.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-clarity.md index 83ec74b..64cf203 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-clarity.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-clarity.md @@ -2,7 +2,7 @@ - **Tier**: mid-tier - **Role**: plan clarity reviewer that judges whether a cold reader can follow the plan -- **Inputs**: current `spec.md`, `plan.md`, prior role report +- **Inputs**: current `spec.md`, `plan.md`, prior role report, `review-dispositions.md` when present - **Workspace**: correctly targeted feature/repository view that the reviewer does not modify - **Exclusions**: no modification of any reviewed artifact, no design substitution, no human acceptance decision - **Output**: your review report only, written outside the reviewed set @@ -13,3 +13,7 @@ verification, and planning handoff without conflicting or missing authority. Identify ambiguity, unexplained consequence, or unreviewable handoff as semantic findings. Return an attributable complete current-state round with reviewed paths, trigger, scope, blocking/concern findings, and verdict. + +When `review-dispositions.md` exists, tie any finding caused by an earlier +accepted fix to that fix's finding title. Do not raise a declined finding again +unless new evidence exists, and name that evidence. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-design.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-design.md index cf0d81b..7248731 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-design.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-design.md @@ -2,7 +2,7 @@ - **Tier**: most-capable - **Role**: plan design reviewer that judges the technical coherence and architecture of the plan -- **Inputs**: current `spec.md`, `plan.md`, relevant grounding/research, prior role report +- **Inputs**: current `spec.md`, `plan.md`, relevant grounding/research, prior role report, `review-dispositions.md` when present - **Workspace**: correctly targeted feature/repository view that the reviewer does not modify - **Exclusions**: no modification of any reviewed artifact, no binding choice, no human acceptance decision - **Output**: your review report only, written outside the reviewed set @@ -14,3 +14,7 @@ Definition alignment. Check that durable decisions are in `plan.md`, not only supporting workspaces. Return an attributable complete current-state round with reviewed paths, trigger, scope, semantic blocking/concern findings, and verdict. A passing verdict never implies Design Acceptance. + +When `review-dispositions.md` exists, tie any finding caused by an earlier +accepted fix to that fix's finding title. Do not raise a declined finding again +unless new evidence exists, and name that evidence. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-overview-fidelity.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-overview-fidelity.md new file mode 100644 index 0000000..8c46e08 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-overview-fidelity.md @@ -0,0 +1,21 @@ +# Plan Overview Fidelity Review Packet + +- **Tier**: mid-tier +- **Role**: plan overview fidelity reviewer that checks the human plan overview against the normative plan +- **Inputs**: current `spec.md` intent, `plan.md`, `plan-overview.md`, overview contract in `.specify/presets/timors-agentic-workflow/writers/plan-overview.md`, prior role report +- **Workspace**: correctly targeted feature/repository view that the reviewer does not modify +- **Exclusions**: no modification of any reviewed artifact, no plan design or clarity review, no human acceptance decision +- **Output**: your review report only, written outside the reviewed set + +This review runs only after `plan_design` and `plan_clarity` are current and +non-blocking for the current Revision. Independently determine whether +`plan-overview.md` faithfully reflects the current `plan.md`: the header names +the current Revision; the intent restatement agrees with `spec.md`; no statement +contradicts, bends, or adds to a `plan.md` decision; and every titled Design +Decision is explained in the body or named in Not Covered Here. A one-line Not +Covered Here entry fully satisfies coverage. Do not flag the overview as too +short, ask to move a listed item into the body, or raise plan design or clarity +issues those roles own. When `plan.md` itself prevents a faithful overview, +report that finding at its `plan.md` location. Return an attributable complete +current-state round with reviewed paths, trigger, scope, semantic +blocking/concern findings, and verdict. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-overview-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-overview-template.md new file mode 100644 index 0000000..4d3f5fa --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-overview-template.md @@ -0,0 +1,18 @@ +# Plan Overview: [Feature Name] + +- **Reflects Plan Revision**: RNN +- **Authority**: Non-normative human view of `plan.md`. `plan.md` prevails on + any conflict. No workflow phase reads this file. + +## Intent + +[Short restatement of the Feature Definition intent from `spec.md`.] + +## [Decision-Focused Section] + +[What was decided and why, limited to what the human needs to accept or reject +the design.] + +## Not Covered Here + +- [Omitted topic] — `plan.md` › [Section path] diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-template.md index 8862238..537c452 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-template.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-template.md @@ -46,6 +46,7 @@ |---|---|---|---|---|---| | plan_design | reviews/plan-design.md | None | None | Pending | Pending | | plan_clarity | reviews/plan-clarity.md | None | None | Pending | Pending | +| plan_overview_fidelity | reviews/plan-overview-fidelity.md | None | None | Pending | Pending | ## Design Acceptance diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-dispositions-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-dispositions-template.md new file mode 100644 index 0000000..8521c99 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-dispositions-template.md @@ -0,0 +1,17 @@ +# Review Dispositions: [Feature Name] + +Human dispositions of plan review findings, one section per answered review +batch. Plan reviewers read this file. No task-planning or implementation phase +reads it. + +## Batch NN + +- **Plan Revision**: RNN + +### [Semantic Finding Title] + +- **Role**: plan_design | plan_clarity | plan_overview_fidelity +- **Round**: RNN +- **Disposition**: accepted | declined +- **Applied Change**: [Semantic `plan.md` location, or `None`] +- **Human Reason**: [Reason the human gave] diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/writers/plan-overview.md b/private_dot_config/specify/presets/timors-agentic-workflow/writers/plan-overview.md new file mode 100644 index 0000000..5eb510d --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/writers/plan-overview.md @@ -0,0 +1,24 @@ +# Plan Overview Writer Packet + +- **Tier**: mid-tier +- **Role**: technical writer who explains a settled design to a human reader +- **Inputs**: current `spec.md` intent, current `plan.md`, existing `plan-overview.md` when present, current plan-overview-fidelity report when correcting +- **Workspace**: correctly targeted feature/repository view in which only the output is written +- **Exclusions**: no modification of any input other than the output, no design decision, no human acceptance decision +- **Output**: `plan-overview.md` only + +Write a non-normative human view of the current `plan.md` from +`.specify/presets/timors-agentic-workflow/templates/plan-overview-template.md`. +The header names the plan Revision it reflects and states that `plan.md` +prevails. Open with a short restatement of the Feature Definition intent so the +overview reads on its own. Explain what was decided and why. Put a point in the +body only if the human needs it to accept or reject the design; every other +topic goes to Not Covered Here as one line with a pointer to its `plan.md` +section. Every titled Design Decision in `plan.md` is either explained in the +body or named in that list. + +Never add, change, or settle a decision. When `plan.md` is unclear, +contradictory, or missing a decision the overview would need, do not resolve it +in prose; return it to the planner as a blocker. A correction pass applies only +fidelity findings that bring the overview into agreement with `plan.md`. Return +the written path, the reflected Revision, and any blockers. From ad8197fd5e962845ea5ef4c37d9b81b1377695f4 Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Wed, 11 Nov 2026 23:46:03 +0200 Subject: [PATCH 2/2] update the Spec Kit architecture doc to the 0.5.0 preset The architecture doc still described an older preset: a package integrity preflight, composed upstream commands, task checkboxes, execution groups, and checkpoint-based integration. It now matches the 0.5.0 references, including the plan overview, review dispositions, human approval of design-changing fixes, and per-packet integration. Tool-version validation history is dropped, since it goes stale faster than it can be maintained. --- docs/spec-kit-workflow/architecture.md | 307 +++++++++++++------------ 1 file changed, 156 insertions(+), 151 deletions(-) diff --git a/docs/spec-kit-workflow/architecture.md b/docs/spec-kit-workflow/architecture.md index 9b13c7a..c3f082d 100644 --- a/docs/spec-kit-workflow/architecture.md +++ b/docs/spec-kit-workflow/architecture.md @@ -3,19 +3,13 @@ ## Overview `timors-agentic-workflow` is a project-installed Spec Kit preset that connects -grounded planning, a generated human plan overview, reviewed execution decomposition, -explicit human approval, and delegated implementation through a versioned -Markdown protocol. The preset is provider-neutral: it defines command and -artifact contracts, while the active coding integration supplies concrete -workers, models, skills, and permissions. Its preset version is `0.5.0` and its -protocol version is `0.1.0`; it supports Spec Kit `>=0.12.11` without an upper -support boundary. - -The implemented package and installation behavior have been validated with -Spec Kit 0.12.11 and OpenCode 1.17.18. Runtime review and implementation have -not yet been exercised, so this document describes the implemented contracts -without claiming operational runtime support. This validation is operational -history, not a support boundary. +a human-owned Feature Definition, grounded planning, a generated human plan +overview, a reviewed execution package, explicit human approval, and delegated +implementation in isolated worktrees through Markdown contracts. The preset is +provider-neutral: it defines command and artifact contracts, while the active +coding integration supplies concrete workers, models, skills, and permissions. +Its preset version is `0.5.0`; it supports Spec Kit `>=0.12.11` without an +upper support boundary. ## Source, Installation, And Activation Boundaries @@ -40,18 +34,12 @@ installation. Installation copies the package into the tracked project path `.specify/presets/timors-agentic-workflow/` and generates tracked command files for the active coding integration. Generated commands refer to the installed, project-relative preset path rather than the global source, leaving the project -independent of the dotfiles repository after installation. +independent of the dotfiles repository after installation. Project copies stay +pinned until an operator refreshes them with an explicit remove/add. -For the verified OpenCode integration, those generated files are under +For the OpenCode integration, those generated files are under `.opencode/commands/`. -During the non-normative Spec Kit 0.12.11 installation validation, a project -received global source changes through an explicit remove/add refresh, and -`preset resolve` accepted template names only. Command installation was instead -evidenced by generated integration commands and their project-relative -installed-preset references. These observations are operational history, not -future compatibility constraints. - ```mermaid flowchart TD source["Chezmoi source package"] @@ -60,47 +48,42 @@ flowchart TD commands["Tracked integration commands"] artifacts["Tracked feature artifacts"] runtime["Native project/global workers"] + worktrees["Packet branches and worktrees"] progress["Ignored local progress"] source -->|"chezmoi source-to-target mapping"| global global -->|"explicit preset add; remove/add to refresh"| installed installed -->|"generates project-relative references"| commands - commands -->|"plan, decompose, review, execute"| artifacts + commands -->|"define, plan, decompose, review"| artifacts commands -->|"metadata binding; real-work dispatch"| runtime - runtime -->|"attributable results"| commands + runtime -->|"packet-scoped commits"| worktrees + worktrees -->|"one integrated commit per packet"| commands commands -->|"runtime evidence and resume state"| progress ``` -## Package-Integrity Command Boundary - -Every command composed or replaced by the preset begins with the same complete -installed package-integrity gate. It checks the manifest and active `specify` -version, complete required package inventory, declared mappings and strategies, -and preset/protocol identity before extension hooks, prerequisite scripts, -dispatch, or writes. It fails closed only below the minimum, on an explicit -installed-manifest exclusion, or when a required contract is missing, malformed, -or incoherent. Newer untested CLI versions neither warn nor block. This protects -generated commands that remain in a project after the CLI changes without -changing required public integration behavior. The accepted execution-package -protocol is likewise `0.1.0`; unsupported or malformed protocol artifacts return -to their owning generation command rather than being migrated or inferred. - -The preset deliberately uses different integration strategies by phase: - -- `/speckit.specify` composes with upstream specification generation, retaining - its behavior; - `/speckit.clarify` remains upstream and owns product clarification. -- `/speckit.plan` and `plan-template` compose with upstream planning, retaining - its design artifacts, adding verified grounding and integration context, and - generating the human plan overview. -- `/speckit.tasks`, `tasks-template`, and `/speckit.implement` replace their - upstream surfaces because decomposition, independent review, approval, and - delegated execution share a stronger protocol. The preset provides no - `/speckit.analyze`; it folds independent review and human approval into - `/speckit.plan` and `/speckit.tasks`. The stock `/speckit.analyze` resolves from - a lower layer and is not part of this lifecycle. -- Auxiliary templates provide the indexed sub-plans, cumulative review reports, - and local progress ledger used by those replacements. +## Command Integration Boundary + +The manifest replaces all five lifecycle commands (`/speckit.specify`, +`/speckit.clarify`, `/speckit.plan`, `/speckit.tasks`, `/speckit.implement`) and +the `spec-template`, `plan-template`, and `tasks-template` templates. Every phase +shares one protocol of artifact authorities, human gates, and invalidation rules, +so composing with upstream bodies would mix two sets of rules. The preset provides +no `/speckit.analyze`; it folds independent review and human approval into +`/speckit.plan` and `/speckit.tasks`. The stock `/speckit.analyze` resolves from a +lower layer and is not part of this lifecycle. + +The other templates (grounding notes, research, plan overview, review dispositions, +review report, sub-plan, and progress) and the reviewer and writer packets are not +registered in the manifest. Commands read them by their installed project-relative +path. + +Commands run no package, manifest, installed-inventory, mapping, or CLI-version +preflight. The only version requirement is the manifest's +`requires.speckit_version`. Instead, every command first resolves the canonical +feature directory, and each consumer checks the concrete fields its phase reads +and fails closed on missing, partial, contradictory, or malformed state. Old +artifacts are never migrated or inferred; they return to their owning phase or +restart the lifecycle. The preset does not run Spec Kit extension hooks. Stock command bodies dispatch `before_*` and `after_*` hooks from `.specify/extensions.yml`. The preset @@ -108,11 +91,8 @@ replacements omit that mechanism, so no phase runs an extension automatically. T git extension branch and commit hooks never fire from the workflow. An operator runs an extension command manually when wanted. -The installed preset references are the normative source for workflow behavior, -artifact schemas, and CLI/package compatibility. The minimum supported version and -the structural package-integrity contract come from the installed manifest and its -`requires.speckit_version`, as described in the Package-Integrity Command Boundary -section above. This architecture overview summarizes those boundaries without +The installed preset references are the normative source for workflow behavior and +artifact schemas. This architecture overview summarizes those boundaries without redefining them. ### Plan Overview @@ -133,45 +113,60 @@ contract. The protocol separates durable planning truth from local runtime evidence: -- `spec.md`, `plan.md`, and the normal design artifacts provide requirements, - technical design, decisions, data models, contracts, and other planning - inputs. -- `tasks.md` is the sole atomic task ledger. It owns task identity, task text, - paths, story labels, task-local parallel hints, and completion checkboxes. -- The indexed `subplans/` own execution groups, the dependency graph and order, - file ownership, cross-group contracts and data flow, semantic model tiers, - required skills and capabilities, tests, acceptance criteria, and - verification. -- `specs//reviews/.md` files are tracked cumulative sources of - reviewer findings. Reruns append current-state rounds rather than replacing - review history. -- The human approval decisions live in their owning artifacts: Design Acceptance - in `plan.md` and Implementation Authorization in `tasks.md`. The preset produces - no separate `analysis.md` aggregate. +- `spec.md` is the Feature Definition and the only authority for product intent. + It is `Draft` or `Ready`. `/speckit.specify` writes it without asking + questions; `/speckit.clarify` converges it through one-question human dialogue. + It excludes repository feasibility on purpose. +- `grounding-notes.md` stores attributed repository evidence with no + recommendations. `research.md` is tracked, non-normative working space for + alternatives and working decisions. +- `plan.md` is the sole normative plan. It restates every decision task planning + needs, carries a `Revision` (`R0`, `R1`, ...), the Review Record pointers, and + the human Design Acceptance. - `plan-overview.md` is the generated, non-normative human view of `plan.md`. `plan.md` prevails on conflict, and no phase reads the overview as input. - `review-dispositions.md` records, per answered plan review batch, each finding's disposition and the human's reason. Only the `plan-design` and `plan-clarity` reviewers read it, so reruns can tie new findings to earlier fixes and do not raise declined findings again without new evidence. -- `specs//progress.md` is an ignored local ledger for concrete workers - and models, workspaces, dispatch and test evidence, checkpoints, blockers, - failures, integration state, and resume decisions. It does not duplicate - atomic task completion truth. +- `tasks.md` is the execution package index. Its closed frontmatter is the sole + machine authority for sub-plan identities, the predecessor graph, task review + pointers, and Implementation Authorization. It holds no atomic tasks or + checkboxes; its ledger table and Mermaid graph are human projections. +- Each indexed `subplans/` file is one packet. It owns its primary files, + semantic model tier, required skills, test mode and basis, acceptance and + verification, and the contracts it produces or consumes. A producer's + sub-plan holds the only definition of each contract it produces. +- `reviews/.md` files are tracked cumulative reviewer reports. Reruns + append complete current-state rounds rather than replacing review history. +- `progress.md` is an ignored local ledger owned by the coordinator. It records + concrete bindings, packet states, signing policy, the protected baseline, test + evidence, contract outputs, blockers, and final verification. + +The human approval decisions live in their owning artifacts: Design Acceptance in +`plan.md` and Implementation Authorization in `tasks.md`. The preset produces no +separate `analysis.md` aggregate. + +Creating `progress.md` is the lock event. After it, the tracked feature directory +is immutable, and material `spec.md` or `plan.md` writes are refused. Before the +lock, a material Feature Definition or plan change marks Design Acceptance +`Stale`, returns authorization to `pending`, and makes affected review pointers +pending, so no gate stays valid for changed content. This split keeps provider- and machine-specific details out of tracked planning -artifacts while preserving a reviewable decomposition and approval record. +artifacts while preserving a reviewable package and approval record. ## Planning And Review Flow -Task generation reads the specification, plan, and available design artifacts, -then creates `tasks.md` and its indexed `subplans/` as one normalized set. It -validates the set before writing, so task descriptions and checkboxes remain in -the task ledger while execution policy remains in the sub-plans. +Planning grounds repository reality before it designs, writes `plan.md`, and +generates the first overview. Task generation reads the accepted plan and creates +`tasks.md` and its indexed `subplans/` together. Before review, it applies every +closed-schema and structural check in the task-planning reference; a failure +blocks review and authorization. Independent review runs inside two phases, not a separate command. Each producing -phase dispatches fresh-context, read-only reviewers and blocks its own human -approval until the reviews permit it: +phase dispatches fresh-context reviewers that do not modify the artifacts they +review, and blocks its own human approval until the reviews permit it: - `/speckit.plan` requires most-capable `plan-design`, which judges technical coherence of the plan, and mid-tier `plan-clarity`, which judges cold-reader @@ -180,42 +175,52 @@ approval until the reviews permit it: `plan.md`. - `/speckit.tasks` requires mid-tier `tasks-plan-fidelity`, which traces the accepted plan and Feature Definition into the task package, and most-capable - `tasks-executability`, which judges decomposition feasibility and testable + `tasks-executability`, which judges decomposition, dependencies, and testable work. Both feed Implementation Authorization in `tasks.md`. -Before task review, the shared installed structural validator runs first. A -structural failure blocks before reviewer dispatch or report writes. Projects may -select additional project-owned reviewer packets. Each role appends to its -cumulative report under `specs//reviews/`, and the producing phase -preserves source finding ownership. No phase performs a fallback self-review, and -no phase produces an `analysis.md` aggregate. Implementation remains blocked until -the latest reviews are complete and the recorded human approval authorizes it. +The producing phase never applies a finding on its own judgment. It applies +wording, formatting, or citation fixes directly and lists them. Every other fix, +including one that fills a gap no human decided, is a proposed remediation that +waits for human acceptance. This keeps design decisions from entering the plan +without the human seeing them. The one exception is an overview fidelity fix that +only brings `plan-overview.md` back into agreement with `plan.md`; it changes no +decision, so the writer applies it directly. + +Each role appends to its cumulative report, and the producing phase preserves +source finding ownership. At quiescence, the phase presents all current blockers +and proposed remediations in one interaction. No phase performs a fallback +self-review. Implementation remains blocked until the latest reviews are complete +and the recorded human approval authorizes it. ## Delegated Implementation Flow -Before mutation, implementation repeats the same installed structural -validation and checks report consistency and human authorization. It then -initializes or reconciles local progress and processes only groups made ready by -the approved dependency graph. - -For each ready group, the coordinator binds the planned semantic tier, skills, -capabilities, and workspace requirements to an eligible native worker. It -constructs a deterministic packet from the canonical group record, group -details, owned task lines, and checkpointed prerequisite contract outputs. It -does not redesign groups or silently change their dependencies, ownership, -contracts, model tiers, tests, or acceptance criteria. - -Policy-permitted parallel groups run in separate worktrees only after every -member of the dispatch set passes readiness and output/cache safety checks. -Completed results are integrated and verified, then retained in signed local -checkpoints before task checkboxes and group state become complete. Dependent -groups consume verified checkpoint outputs rather than uncommitted files. Once -all groups pass final verification, checkpoint history is materialized as one -aggregate dirty review diff while a local checkpoint reference preserves -recovery evidence. - -These are implemented command contracts, but their runtime operation has not -yet been exercised through a normal feature. +Before mutation, implementation requires a Ready `spec.md`, an accepted current +plan Revision, a reviewed and approved package, and a clean, named active branch. +It resolves and pins the repository's signing policy, then creates `progress.md`, +which pins the active branch, its starting commit, and the protected baseline of +every tracked feature-directory file. + +The predecessor graph in `tasks.md` frontmatter is the only scheduling authority. +Every ready packet is dispatched concurrently unless a concrete binding, harness, +resource, or workspace limit forces serialization. For each packet, the +coordinator binds an eligible native worker to the planned tier and skills, +creates a dedicated branch and worktree, and sends the packet's identity and +locator plus verified evidence for each consumed contract, not the packet text. +The worker reads its packet from the sub-plan. The coordinator does not redesign +packets or change their dependencies, ownership, contracts, tiers, tests, or +acceptance. + +Workers commit only on their packet branch. The coordinator checks the returned +diff, ownership, tests, acceptance, contract-output evidence, attribution, and +the protected baseline. It then integrates packets in approved topological order: +rebase, build a separately inspectable squash candidate, verify it, and +fast-forward the active branch by exactly one policy-compliant commit per packet. +A consumer becomes ready only after its producer's final commit and contract +evidence are recorded. Nothing is pushed. + +After all packets are done, aggregate verification and an independent +most-capable `component-docs` review gate completion. Bounded in-scope repairs +land as corrective commits; new scope returns to its owning phase. ## Provider-Neutral Runtime Binding @@ -228,35 +233,39 @@ dispatch evidence stays in ignored progress or transient runtime state. Suitability checks inspect runtime metadata and configuration only. Preflight does not invoke a worker, calibration task, probe, canary, or sacrificial call. -The first worker invocation carries the real assigned review or implementation -work. Missing evidence for tier, concrete model, permissions, invokability, fresh -context or attribution, workspace targeting, dispatch, or result identity blocks -the applicable role or group. A reviewer role additionally requires a read-only -workspace and a single candidate whose description matches the role. An -implementation group additionally requires the skills and capabilities that the -sub-plan names. +The first worker invocation carries the real assigned work. Every role or packet +requires its tier, native discoverability, invokability, correct workspace +targeting, and attributable results: + +- A reviewer or writer role binds the single candidate whose description matches + the role description. A reviewer does not modify the artifacts it reviews and + writes only its report; a writer modifies only its declared output. +- An implementation packet binds a candidate that has the skills the sub-plan + names. + +Zero or several plausible candidates become a collected blocker for one human +choice. ## Failure And Recovery Boundaries The protocol fails closed at ownership boundaries rather than repairing state in a later phase: -- Unsupported, missing, or malformed task/execution artifacts are regenerated - by `/speckit.tasks`; invalid review reports or approval state return to their - producing phase (`/speckit.plan` or `/speckit.tasks`) with explicit - confirmation where history could be lost. -- An incomplete review round or a role marked `Recovery required` blocks - implementation. Ambiguous started invocations are retained for explicit +- Missing, malformed, or old task artifacts are regenerated by `/speckit.tasks`; + invalid review reports or approval state return to their producing phase + (`/speckit.plan` or `/speckit.tasks`). +- An incomplete review round or a role marked `Recovery required` blocks the + phase's human gate. Ambiguous started invocations are retained for explicit recovery and are not automatically redispatched. -- Unsafe worker binding, worktree targeting, dirty state, test evidence, - integration, checkpoint signing, or prerequisite state blocks the affected - execution boundary. -- Missing checkpoint, artifact, verification, or attributable result evidence - cannot be replaced by checked task boxes or optimistic inference. -- Branches, worktrees, checkpoint references, unrelated dirty files, and - feature artifacts are never automatically stashed, discarded, reset, - committed, or deleted. Recovery or abandonment requires an explicit human - disposition. +- Unsafe worker binding, worktree targeting, baseline change, test evidence, + integration, signing, or prerequisite state blocks the affected packet and its + dependents, while independent ready packets continue. +- Missing contract output, verification, or attributable result evidence cannot + be replaced by inference from commits. +- Branches, worktrees, unrelated dirty files, and feature artifacts are never + automatically stashed, discarded, reset, or deleted, and unrelated files are + never committed. Abandonment requires an explicit human disposition and + archives progress rather than deleting it. ## Coexistence With Existing Workflows @@ -265,22 +274,18 @@ separate and unchanged. The preset adapts compatible guarantees into its own Spec Kit artifacts and installed references, but it does not invoke those skills, consume their plan format, or depend on them at runtime. -## Verified Scope - -Deterministic validation covers the manifest, structural package inventory, -command and template mappings, project installation and remove/add refresh, all six template -resolutions, generated OpenCode commands, project-relative preset references, -tracked asset behavior, and targeted chezmoi rendering. These checks do not -invoke generated commands through a model and do not prove semantic runtime -operation. Runtime review, binding, and implementation remain **Not exercised** -until a normal feature completes them with real assigned work. +## References -See the [preset README][preset-readme] for installation and diagnostic commands. -[Artifact contracts][artifact-contracts], [review lifecycle][review-lifecycle], -and [execution lifecycle][execution] define their respective installed protocol -contracts. +See the [preset README][preset-readme] for installation and replacement cautions. +[Artifact contracts][artifact-contracts], [plan lifecycle][plan-lifecycle], +[review lifecycle][review-lifecycle], [task planning][task-planning], +[execution lifecycle][execution], and [workspace isolation][workspace-isolation] +define their respective installed protocol contracts. [preset-readme]: ../../private_dot_config/specify/presets/timors-agentic-workflow/README.md [artifact-contracts]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-contracts.md +[plan-lifecycle]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/plan-lifecycle.md [review-lifecycle]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/review-lifecycle.md +[task-planning]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/task-planning.md [execution]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/execution-lifecycle.md +[workspace-isolation]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/workspace-isolation.md