diff --git a/docs/spec-kit-workflow/architecture.md b/docs/spec-kit-workflow/architecture.md index 334d09c5..dce1a548 100644 --- a/docs/spec-kit-workflow/architecture.md +++ b/docs/spec-kit-workflow/architecture.md @@ -7,7 +7,7 @@ grounded planning, optional human review, 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.2.1` and its +workers, models, skills, and permissions. Its preset version is `0.4.0` and its protocol version is `0.1.0`; it supports Spec Kit `>=0.12.11` without an upper support boundary. @@ -81,7 +81,7 @@ 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-plan +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. @@ -93,25 +93,35 @@ The preset deliberately uses different integration strategies by phase: - `/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. -- `/speckit.tasks`, `tasks-template`, `/speckit.analyze`, and - `/speckit.implement` replace their upstream surfaces because decomposition, - independent review, approval, and delegated execution share a stronger - protocol. -- Auxiliary templates provide the execution plan, cumulative review reports, - aggregate analysis, and local progress ledger used by those replacements. +- `/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. + +The preset does not run Spec Kit extension hooks. Stock command bodies dispatch +`before_*` and `after_*` hooks from `.specify/extensions.yml`. The preset +replacements omit that mechanism, so no phase runs an extension automatically. The +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. In particular, -[protocol compatibility][compatibility] owns the minimum-version and structural -package-integrity contract. This architecture overview summarizes those -boundaries without redefining them. +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 +redefining them. ### Optional Human Review 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 analysis. +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 @@ -128,15 +138,16 @@ The protocol separates durable planning truth from local runtime evidence: 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. -- `execution-plan.md` owns execution groups, the dependency graph and order, +- 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. -- `analysis.md` is the tracked aggregate of applicable review rounds and the - location of the explicit human approval decision. +- 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. - `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 @@ -148,29 +159,29 @@ artifacts while preserving a reviewable decomposition and approval record. ## Planning And Review Flow Task generation reads the specification, plan, and available design artifacts, -then creates `tasks.md` and `execution-plan.md` as one normalized pair. It -validates the pair before writing either artifact, so task descriptions and -checkboxes remain in the task ledger while execution policy remains in the -orchestration plan. - -Before semantic review, analysis consumes the shared installed structural -validator. Structural failure blocks before reviewer dispatch or report writes. -After a successful preflight, the coordinator requires independent -fresh-context reviews from: - -- Mid-tier `artifact-fidelity`, which traces the approved inputs into the - planned work; -- Most capable `decomposition-design`, which judges execution feasibility and - decomposition quality; and -- Mid-tier `plan-clarity`, which judges whether the handoff is unambiguous to a - cold reader. - -Projects may select additional project-owned reviewer packets. Each required -role writes to its cumulative report, and the coordinator preserves source -finding ownership while producing `analysis.md`. The coordinator validates and -aggregates reviewer output but does not perform a fallback semantic review. -Implementation remains blocked until the latest run is complete and the human -approval record authorizes it. +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. + +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: + +- `/speckit.plan` requires most-capable `rfc-design`, which judges technical + coherence of the RFC, and mid-tier `rfc-clarity`, which judges cold-reader + clarity of the RFC. Both feed Design Acceptance in `plan.md`. +- `/speckit.tasks` requires mid-tier `tasks-rfc-fidelity`, which traces the + accepted RFC and Feature Definition into the task package, and most-capable + `tasks-executability`, which judges decomposition feasibility 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. ## Delegated Implementation Flow @@ -210,9 +221,12 @@ 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, skills, permissions, -invokability, fresh context or attribution, workspace targeting, dispatch, or -result identity blocks the applicable role or group. +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. ## Failure And Recovery Boundaries @@ -220,9 +234,10 @@ 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 aggregate state return to - `/speckit.analyze` with explicit confirmation where history could be lost. -- An incomplete analysis run or a role marked `Recovery required` blocks + 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 recovery and are not automatically redispatched. - Unsafe worker binding, worktree targeting, dirty state, test evidence, @@ -254,12 +269,11 @@ operation. Runtime review, binding, and implementation remain **Not exercised** until a normal feature completes them with real assigned work. See the [preset README][preset-readme] for installation and diagnostic commands. -[Protocol compatibility][compatibility], [artifact validation][artifact-validation], -[analysis and approval][analysis], and [execution lifecycle][execution] define -their respective installed protocol contracts. +[Artifact contracts][artifact-contracts], [review lifecycle][review-lifecycle], +and [execution lifecycle][execution] define their respective installed protocol +contracts. [preset-readme]: ../../private_dot_config/specify/presets/timors-agentic-workflow/README.md -[compatibility]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/protocol-compatibility.md -[artifact-validation]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-validation.md -[analysis]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/analysis-and-approval.md +[artifact-contracts]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-contracts.md +[review-lifecycle]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/review-lifecycle.md [execution]: ../../private_dot_config/specify/presets/timors-agentic-workflow/references/execution-lifecycle.md 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 318ecf91..c0a3bc71 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/README.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/README.md @@ -1,6 +1,6 @@ # Timor's Agentic Workflow -Preset `0.3.0` supplies one project-installed lifecycle: +Preset `0.4.0` supplies one project-installed lifecycle: `specify` → `clarify` when Draft → `plan` → `tasks` → `implement`. @@ -34,12 +34,14 @@ operator-controlled, not a workflow command gate. ## Execution Boundaries -Task packages contain provider-neutral tiers and exact skills, not concrete -workers, model IDs, credentials, local workspace paths, or dispatch identities. -Binding is just in time and requires tier, skills, discoverability, invokability, -correct workspace targeting, and attributable results. Project-local candidates -are preferred; ambiguity requires a human choice. Runtime considerations neither -grant access nor alter eligibility. +Task packages contain provider-neutral tiers and the skills each group needs, not +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, a read-only workspace, +and a single candidate whose description matches the role. Project-local +candidates are preferred; ambiguity requires a human choice. Runtime +considerations neither grant access nor alter eligibility. Each packet has a dedicated branch and worktree. Workers may commit only there; the coordinator alone advances the active branch. The approved tracked feature diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.clarify.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.clarify.md index 0c5bdfd4..3c8478ce 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.clarify.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.clarify.md @@ -4,9 +4,11 @@ description: Converge a Feature Definition through one-question human dialogue. ## Authority and Inputs -Read canonical `spec.md`, `references/artifact-contracts.md`, -`references/feature-definition.md`, `references/clarification.md`, and -`references/review-lifecycle.md`. `spec.md` is the only authority for product +Resolve the canonical feature directory from `.specify/feature.json` per +`.specify/presets/timors-agentic-workflow/references/artifact-contracts.md` before +any read. Read canonical `spec.md`, `.specify/presets/timors-agentic-workflow/references/artifact-contracts.md`, +`.specify/presets/timors-agentic-workflow/references/feature-definition.md`, `.specify/presets/timors-agentic-workflow/references/clarification.md`, and +`.specify/presets/timors-agentic-workflow/references/review-lifecycle.md`. `spec.md` is the only authority for product intent. Do not inspect repository reality or make technical design choices. ## Procedure diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.implement.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.implement.md index 4e40a8d8..a7dbab37 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.implement.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.implement.md @@ -6,31 +6,34 @@ description: Execute approved sub-plans in isolated worktrees and integrate pack Require Ready canonical `spec.md`; canonical `plan.md` Design Acceptance Accepted for its current Revision; a closed, reviewed `tasks.md`; `authorization: approved`; -and a fully clean, named, stable active branch. Read -`references/artifact-contracts.md`, `references/execution-lifecycle.md`, -`references/workspace-isolation.md`, `references/scheduling-policy.md`, -`references/model-and-worker-selection.md`, `references/testable-work.md`, and -`references/documentation-planning.md`. Use `templates/progress-template.md` and, -when required, `reviewers/component-docs.md` with -`templates/review-report-template.md`. +and a fully clean, named, stable active branch. Resolve the canonical feature +directory from `.specify/feature.json` per +`.specify/presets/timors-agentic-workflow/references/artifact-contracts.md` before +reading any artifact. Read +`.specify/presets/timors-agentic-workflow/references/artifact-contracts.md`, `.specify/presets/timors-agentic-workflow/references/execution-lifecycle.md`, +`.specify/presets/timors-agentic-workflow/references/workspace-isolation.md`, `.specify/presets/timors-agentic-workflow/references/scheduling-policy.md`, +`.specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md`, `.specify/presets/timors-agentic-workflow/references/testable-work.md`, and +`.specify/presets/timors-agentic-workflow/references/documentation-planning.md`. Use `.specify/presets/timors-agentic-workflow/templates/progress-template.md` and, +when required, `.specify/presets/timors-agentic-workflow/reviewers/component-docs.md` with +`.specify/presets/timors-agentic-workflow/templates/review-report-template.md`. ## Procedure -1. Perform the concrete phase checks in `references/execution-lifecycle.md`; do +1. Perform the concrete phase checks in `.specify/presets/timors-agentic-workflow/references/execution-lifecycle.md`; do not redesign the approved package. Resolve, pin, and later refresh signing - policy exactly under `references/workspace-isolation.md`. Add the exact local + policy exactly under `.specify/presets/timors-agentic-workflow/references/workspace-isolation.md`. Add the exact local progress path to `.git/info/exclude` after clean preflight, then create initial progress from its template. Creation is the lock event and records active branch, starting commit, complete protected baseline, and policy evidence. 2. For each ready canonical identity, validate closed package structure, selected tracked regular file, predecessor status and contract evidence, ownership, test mode/basis, and baseline equality. Bind a worker under - `references/model-and-worker-selection.md`. Create a dedicated branch/worktree, + `.specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md`. Create a dedicated branch/worktree, derive and record its worktree-root-relative locator, and dispatch only the identity, locator, invocation-specific constraints, prerequisite evidence, recovery context, and limited result envelope. Do not copy packet prose into the prompt. -3. Let `references/scheduling-policy.md` control waves. Workers may browse but not +3. Let `.specify/presets/timors-agentic-workflow/references/scheduling-policy.md` control waves. Workers may browse but not expand authority, modify protected feature files, rewrite history, merge unrelated work, or push. Validate returned changed paths, commits, verification, output evidence, runtime outcomes, attribution, clean branch, and baseline at 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 38487c8d..a2e2eb33 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 @@ -4,13 +4,16 @@ description: Ground, design, review, and obtain acceptance for the normative RFC ## Authority and Inputs -Require canonical `spec.md` with status Ready. Read -`references/artifact-contracts.md`, `references/planning-grounding.md`, -`references/rfc-planning.md`, `references/review-lifecycle.md`, -`references/model-and-worker-selection.md`, and reviewer packets -`reviewers/rfc-design.md` and `reviewers/rfc-clarity.md`. Use -`templates/grounding-notes-template.md`, `templates/research-template.md`, -`templates/plan-template.md`, and `templates/review-report-template.md`. A project +Require canonical `spec.md` with status Ready. Resolve the canonical feature +directory from `.specify/feature.json` per +`.specify/presets/timors-agentic-workflow/references/artifact-contracts.md` before +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/rfc-planning.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/rfc-design.md` and `.specify/presets/timors-agentic-workflow/reviewers/rfc-clarity.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 RFC. ## Procedure @@ -27,10 +30,10 @@ constitution is optional governance input. `plan.md` is the sole normative RFC. Draft and `clarify` before this command continues. 3. Write a self-contained RFC that restates every durable decision needed by task planning. Classify changes before writing, apply Revision, acceptance, and - review-pointer transitions exactly as `references/rfc-planning.md` requires, + review-pointer transitions exactly as `.specify/presets/timors-agentic-workflow/references/rfc-planning.md` requires, and refuse a material change after the package lock. 4. Bind, invoke, and record independent design and clarity reviews under - `references/review-lifecycle.md`. Remediate accepted findings. Rerun only + `.specify/presets/timors-agentic-workflow/references/review-lifecycle.md`. Remediate accepted findings. Rerun only applicable scope; retain unaffected roles only through the stated retained pointer transition. At review quiescence present one collected blocker interaction. A started incomplete review uses recovery, never self-review. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.specify.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.specify.md index 0b41dd31..a2bc525f 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.specify.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.specify.md @@ -5,28 +5,38 @@ description: Create or reconcile a Feature Definition without interactive questi ## Authority and Inputs Read supplied intent, canonical feature `spec.md` when present, -`references/artifact-contracts.md`, `references/feature-definition.md`, and -`references/review-lifecycle.md`. Render `templates/spec-template.md`. `spec.md` +`.specify/presets/timors-agentic-workflow/references/artifact-contracts.md`, `.specify/presets/timors-agentic-workflow/references/feature-definition.md`, and +`.specify/presets/timors-agentic-workflow/references/review-lifecycle.md`. Render `.specify/presets/timors-agentic-workflow/templates/spec-template.md`. `spec.md` is the product-intent authority. Do not inspect the repository, ask a question, choose technical architecture, or supply a default. ## Procedure -1. Construct or reconcile the complete Feature Definition from positive supplied +1. Resolve the canonical feature directory. When the caller supplied a feature + directory, use it. Otherwise derive it under `specs/`: read `feature_numbering` + from `.specify/init-options.json`, prefix the name with the current + `YYYYMMDD-HHMMSS` when the value is `timestamp` or with the next zero-padded + three-digit number after the existing `specs/` entries otherwise, and name the + directory `-` from a slug of the supplied intent. Do not + write anything yet. +2. Construct or reconcile the complete Feature Definition from positive supplied information only. Preserve semantically titled requirements and their inline acceptance evidence. Include conditional actors, journeys, failures, risks, accessibility, localization, compatibility, or operations only when relevant. -2. Scan every Ready criterion in `references/feature-definition.md`. When any +3. Scan every Ready criterion in `.specify/presets/timors-agentic-workflow/references/feature-definition.md`. When any criterion is not positively established, record every material unanswered question in `Material Open Questions`, set `status: Draft`, and do not infer a resolution. Otherwise set `status: Ready` and state why it satisfies the predicate. -3. Before a material write, check whether local `progress.md` exists with a locked +4. Before a material write, check whether local `progress.md` exists with a locked in-progress, blocked, or complete package. If so, refuse the change. Before a permitted material write, make the ordered invalidations in - `references/review-lifecycle.md`; do not erase downstream artifacts or prior - review history. -4. Report the canonical path, status, material questions, invalidated records, and + `.specify/presets/timors-agentic-workflow/references/review-lifecycle.md`; do not erase downstream artifacts or prior + review history. Create the feature directory when absent. Seed `spec.md` from + `.specify/presets/timors-agentic-workflow/templates/spec-template.md` when it does not already exist. Write the + Feature Definition to `spec.md`. Persist the resolved directory to + `.specify/feature.json` as `{"feature_directory": ""}`. +5. Report the canonical path, status, material questions, invalidated records, and only the next permitted phase: Draft hands off to `clarify`; Ready may hand off to `plan`. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.tasks.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.tasks.md index 1aee4975..ebcecafb 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.tasks.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.tasks.md @@ -5,13 +5,16 @@ description: Produce, review, and authorize an immutable sub-plan task package. ## Authority and Inputs Require Ready canonical `spec.md` and canonical `plan.md` with Design Acceptance -Accepted for its current Revision. Read `references/artifact-contracts.md`, -`references/task-planning.md`, `references/scheduling-policy.md`, -`references/testable-work.md`, `references/documentation-planning.md`, -`references/model-and-worker-selection.md`, and `references/review-lifecycle.md`. -Use `templates/tasks-template.md`, `templates/subplan-template.md`, and -`templates/review-report-template.md`; use reviewer packets -`reviewers/tasks-rfc-fidelity.md` and `reviewers/tasks-executability.md`. +Accepted for its current Revision. Resolve the canonical feature directory from +`.specify/feature.json` per +`.specify/presets/timors-agentic-workflow/references/artifact-contracts.md` before +reading any artifact. Read `.specify/presets/timors-agentic-workflow/references/artifact-contracts.md`, +`.specify/presets/timors-agentic-workflow/references/task-planning.md`, `.specify/presets/timors-agentic-workflow/references/scheduling-policy.md`, +`.specify/presets/timors-agentic-workflow/references/testable-work.md`, `.specify/presets/timors-agentic-workflow/references/documentation-planning.md`, +`.specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md`, and `.specify/presets/timors-agentic-workflow/references/review-lifecycle.md`. +Use `.specify/presets/timors-agentic-workflow/templates/tasks-template.md`, `.specify/presets/timors-agentic-workflow/templates/subplan-template.md`, and +`.specify/presets/timors-agentic-workflow/templates/review-report-template.md`; use reviewer packets +`.specify/presets/timors-agentic-workflow/reviewers/tasks-rfc-fidelity.md` and `.specify/presets/timors-agentic-workflow/reviewers/tasks-executability.md`. ## Procedure @@ -19,18 +22,18 @@ Use `templates/tasks-template.md`, `templates/subplan-template.md`, and Otherwise create or reconcile `tasks.md` and all indexed sub-plans together. Do not create atomic tasks, checkboxes, a separate execution artifact, or provider-specific runtime state. -2. Apply every closed-schema and structural check in `references/task-planning.md`: +2. Apply every closed-schema and structural check in `.specify/presets/timors-agentic-workflow/references/task-planning.md`: canonical identity resolution, ordered path-only DAG, ledger projection, predecessor-table agreement, ownership and concurrency, four-mode testing, producer body/frontmatter one-to-one agreement, consumer joins, and handoff. Missing, unknown, ambiguous, escaping, unmatched, or contradictory data blocks review and authorization; do not infer or migrate it. 3. Add a final documentation packet only under - `references/documentation-planning.md` conditions. Record the required or + `.specify/presets/timors-agentic-workflow/references/documentation-planning.md` conditions. Record the required or not-applicable component-documentation handoff with paths or substantive reason. 4. Dispatch the two independent reviewers using the shared binding, attribution, quiescence, selective-rerun, retained-pointer, and started-review-recovery rules - in `references/review-lifecycle.md`. Append complete report rounds and preserve + in `.specify/presets/timors-agentic-workflow/references/review-lifecycle.md`. Append complete report rounds and preserve history. No blocking, pending, recovery, stale, or contradictory pointer may reach authorization. 5. Request the scalar Implementation Authorization only after both current reviews 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 8c8d0c06..1f3e8626 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.3.0" + version: "0.4.0" description: "RFC-backed feature definition, reviewed task packages, and isolated packet execution." author: "Timor Gruber" license: "MIT" 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 d00fe0b0..7e270308 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 @@ -8,8 +8,12 @@ | 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 | -The canonical feature directory is the command-resolved directory containing the -canonical `tasks.md`; its `spec.md` and `plan.md` have canonical locations there. +The canonical feature directory is resolved deterministically before any artifact +read. The resolution order is a caller-supplied feature directory, then the +`feature_directory` value in `.specify/feature.json`, then the single feature +directory under `specs/` when exactly one exists. Two or more `specs/` candidates +without a `.specify/feature.json` anchor fail closed rather than resolve by guess. +The resolved directory holds the canonical `spec.md`, `plan.md`, and `tasks.md`. Consumers read concrete fields and invariants needed for their own phase and fail closed on missing, partial, contradictory, or malformed state. The installed project copy is runtime policy; commands do not consult the global distribution 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 524193c0..adadb8d9 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,18 @@ # Binding, Runtime Conditions, and Result Attribution -Tracked reviewers and implementation packets name only a provider-neutral tier and -exact skills. Eligibility requires those exact values plus native discoverability, -invokability, correct workspace targeting, and attributable results. Prefer a -project-local candidate. Select a unique preferred candidate, sole eligible -candidate, or an explicit human choice. Abstract capabilities and permission -breadth are excluded. Zero or ambiguous candidates are collected blockers. Do not -provision a worker or perform a suitability probe; first invocation is real work. +A tracked reviewer 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 requires a read-only workspace. Prefer a +project-local candidate. For a reviewer, 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 +binds; zero clear or several plausible candidates are collected blockers. Abstract +capabilities and permission breadth neither grant nor gate eligibility. Do not +provision a worker or perform a suitability probe; the first invocation is real +work. Record the concrete binding in runtime evidence, never in a tracked artifact. Runtime Considerations are anticipated network, local tool, nested-dispatch, cache, or similar conditions. They are planning context only: neither access grants 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 f1131568..31a93f18 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 @@ -1,11 +1,15 @@ # Independent Review Lifecycle -Review roles are independent and read-only. Bind only a candidate with requested -tier, exact skills, native discoverability, invokability, correct workspace -targeting, and attributable results; project-local candidates are preferred. -Select a unique preferred candidate, a sole eligible candidate, or an explicit -human choice. Abstract capabilities and permission breadth are not eligibility -inputs. The first invocation is the real review assignment; there is no probe. +Review roles are independent and read-only. Each role names a tier and a role +description. Bind a candidate that meets the requested tier and is natively +discoverable, invokable, correctly targeted to a read-only workspace, and able to +attribute results; project-local candidates are preferred. Among these safe +candidates, match the role description against the candidate descriptions and bind +only a single clear fit. Zero clear fits or several plausible fits produce a +collected blocker for one human choice. Record the chosen binding in runtime +evidence; no tracked artifact names a candidate. Declared skills, abstract +capabilities, permission breadth, and worker names are not eligibility inputs. The +first invocation is the real review assignment; there is no probe. Every role report is cumulative and appends a complete current-state round with trigger, scope, reviewed paths, binding/invocation/workspace/start/result evidence, diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/component-docs.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/component-docs.md index 428cbc62..8f36731e 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/component-docs.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/component-docs.md @@ -1,7 +1,7 @@ # Component Documentation Review Packet - **Tier**: most-capable -- **Required skills**: exact project component-documentation skill identifiers +- **Role**: component-documentation reviewer that finds documentation made stale or wrong by the final code - **Inputs**: final integrated code, relevant current documentation, Execution Handoff, progress evidence - **Workspace**: correctly targeted read-only repository view after final code - **Exclusions**: no mutation, no scope expansion, no authorization decision diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-clarity.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-clarity.md index 5b17c06d..889ecb4b 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-clarity.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-clarity.md @@ -1,7 +1,7 @@ # RFC Clarity Review Packet - **Tier**: mid-tier -- **Required skills**: exact project cold-reader and technical-writing skill identifiers +- **Role**: RFC clarity reviewer that judges whether a cold reader can follow the RFC - **Inputs**: current `spec.md`, `plan.md`, prior role report - **Workspace**: correctly targeted read-only feature/repository view - **Exclusions**: no mutation, no design substitution, no human acceptance decision diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-design.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-design.md index d334a84a..a0afe1cb 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-design.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-design.md @@ -1,7 +1,7 @@ # RFC Design Review Packet - **Tier**: most-capable -- **Required skills**: exact project RFC and architecture-review skill identifiers +- **Role**: RFC design reviewer that judges the technical coherence and architecture of the RFC - **Inputs**: current `spec.md`, `plan.md`, relevant grounding/research, prior role report - **Workspace**: correctly targeted read-only feature/repository view - **Exclusions**: no mutation, no binding choice, no human acceptance decision diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-executability.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-executability.md index 92c0e0e6..23e5781e 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-executability.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-executability.md @@ -1,7 +1,7 @@ # Task Executability Review Packet - **Tier**: most-capable -- **Required skills**: exact project decomposition, testing, and execution-review skill identifiers +- **Role**: task executability reviewer that judges decomposition, dependencies, and testable work - **Inputs**: accepted RFC, `tasks.md`, indexed sub-plans, prior report - **Workspace**: correctly targeted read-only feature/repository view - **Exclusions**: no mutation, no worker provisioning, no authorization decision diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-rfc-fidelity.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-rfc-fidelity.md index 9f2fe509..997e98de 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-rfc-fidelity.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-rfc-fidelity.md @@ -1,7 +1,7 @@ # Task RFC-Fidelity Review Packet - **Tier**: mid-tier -- **Required skills**: exact project RFC-reading and task-review skill identifiers +- **Role**: task RFC-fidelity reviewer that traces the accepted RFC into the task package - **Inputs**: Ready `spec.md`, current accepted `plan.md`, `tasks.md`, indexed sub-plans, prior report - **Workspace**: correctly targeted read-only feature/repository view - **Exclusions**: no mutation, no implementation dispatch, no authorization decision diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-report-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-report-template.md index e3afddad..08bafcd1 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-report-template.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-report-template.md @@ -12,7 +12,7 @@ - **Trigger**: initial | targeted change | recovery - **Scope**: [Complete current-state review scope] - **Reviewed Paths**: [Project-relative paths] -- **Binding Evidence**: [Candidate, tier/skills, workspace, invocation, start, result] +- **Binding Evidence**: [Candidate, tier, role match, workspace, invocation, start, result] - **Verdict**: passed | passed-with-concerns | blocking #### Current Findings