Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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.
342 changes: 177 additions & 165 deletions docs/spec-kit-workflow/architecture.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
@@ -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<example>\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</example>"
tools: Read, Glob, Grep, Write, Edit
---

{{ template "agent-mid-tier-plan-overview-fidelity-reviewer.md.tmpl" . }}
2 changes: 1 addition & 1 deletion dot_claude/agents/mid-tier-technical-writer.md.tmpl
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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<example>\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</example>"
mode: subagent
permission:
edit: allow
bash: deny
webfetch: deny
task:
"*": deny
skill:
"*": deny
---

{{ template "agent-mid-tier-plan-overview-fidelity-reviewer.md.tmpl" . }}
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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

Expand All @@ -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`.
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
Loading
Loading