Planning Artifacts

Tiered Brief / Plan promotion gate

The gap planning artifacts close

Before planning artifacts, three forward-producing layers existed:

  • architect - produces "what to build"
  • orchestration-planner - produces "how to decompose it"
  • engineer - implements the units

What was missing: a committed answer to "what problem are we solving and how will we know it is done?"

Without that commitment, multi-unit fan-out and cross-session resume drifted - each engineer spawned against an informal interpretation rather than a locked problem statement, success criteria, and verification plan.

Also missing: operator participation in framing. The Brief was conductor-synthesized, not operator-negotiated. The /ds-brief command adds operator negotiation before the architect spawns.

Planning artifacts add the missing layer: a gate that commits to the framing before the first engineer spawns, keeping that commitment alive through fan-out and resume.

Where it sits in the flow

[PRIMARY] operator runs /ds-brief -> dialogue -> operator-confirmed Brief committed
                                           -> architect (brief_path pre-populated)

[BACKSTOP] Risk classified Elevated (no /ds-brief session)
  -> architect
  -> Skeptic on architect plan
  -> Open Questions resolved
  -> orchestration-planner
  -> [PROMOTION CHECK]
       0-1 Elevated units:   no artifact (current behavior)
       2-5 Elevated units:   Brief -> Skeptic on Brief (full framing review)
       6+ Elevated units:    Plan  -> Skeptic on Plan
       cross-track / multi-session: Plan (+ ADR if arch-decision-constraining)

Both paths -> engineer(s) spawned with brief_path / plan_path in execution contract
Two entry points: /ds-brief (preferred for features still being framed) and the mechanical promotion gate (backstop for well-specified tickets). The promotion check is downstream of the planner (unit count is known) and upstream of the first engineer spawn (no work has started). It is a gate, not a suggestion.

Two paths to a Brief

Interactive /ds-brief path (preferred)

  • Operator has exploratory framing ("I want to build...")
  • Conductor auto-triggers or operator invokes /ds-brief [topic]
  • Multi-turn dialogue: intent, gray areas, Q&A, draft, iterate
  • Brief committed to conductor's branch BEFORE architect spawns (no worktree)
  • brief_source: operator - Skeptic does completeness-only review

Mechanical promotion path (backstop)

  • Work arrives as a well-specified ticket; no /ds-brief session
  • architect -> Skeptic -> planner -> promotion check
  • Brief authored by conductor from planner output (2-5 units)
  • brief_source: conductor - Skeptic does full framing review
  • Retroactive Brief possible if unit count escalates mid-work
Interactive path is preferred for features still being framed. Mechanical path is the backstop for well-specified tickets. Both converge on the same artifact: docs/planning/<slug>.md.

Trigger table

Condition Artifact required
0-1 Elevated units (or planner skipped) None - architect plan only
2-5 Elevated units Brief + architect plan
6+ Elevated units OR cross-track OR multi-session Plan (Brief + assembled artifacts + 3 coverage docs)
Cross-track OR architecture-decision-constraining Plan + ADR

Unit counting rule: only units whose risk is Elevated or above count. Trivial units contribute zero.

"Cross-track" (mechanical): a depth-1 directory under the repo root with its own AGENTS.md. Nested AGENTS.md files (e.g. helios/factory/AGENTS.md) do not create new tracks.

All triggers are mechanical. Operator judgment is not a field. Evaluate after orchestration-planner returns.

Cross-artifact alignment check

After orchestration-planner returns and before Skeptic-on-Brief runs, the conductor maps every Brief success criterion to at least one unit's acceptance_criteria in the planner JSONL:

  • Covered - criterion maps to at least one unit. Proceed to Skeptic-on-Brief.
  • Uncovered - criterion has no corresponding unit. Blocks Skeptic-on-Brief until resolved.

Resolution paths for uncovered criteria: re-spawn planner with the gap called out, or surface a descope/expand decision to the operator.

When no unit has non-empty acceptance_criteria, emit [phase: cross-artifact-check-skipped | no criteria to map] and proceed.

Mechanical and conductor-direct - no agent spawn needed. Complements the adversarial Skeptic-on-Brief; does not replace it. An uncovered criterion is a planning gap: the Brief commits to an outcome no unit is scoped to deliver.

Brief template (fields 1-5)

Canonical path: docs/planning/<slug>.md. Must fit on one screen (~15-20 lines).

# Brief: <feature name>
**Problem:**           <1-2 sentences. Behavior gap in user/system terms, not implementation.>
**Success criteria:**  <Bulleted, observable from outside. Max 4 bullets.>
- <criterion 1>
- <criterion 2>
**Non-goals:**         <What this explicitly does NOT do. Max 3 bullets.>
- <non-goal 1>
**Constraints:**       <Hard constraints only - contracts, perf budgets, compat targets, deadlines.>
**Verification:**      <Non-skippable. Tests, gates, qa.md trigger patterns, and regression
                        tests from .agentic/findings.md. "Cannot specify" blocks sign-off.>

Brief template (cont.) — fields 6-8

**Outcome rubric:**    <Pass/fail lines (max 6), each tagged
                        verification_type: deterministic | judgment.
                        Required for Elevated; absence is a Critical Skeptic finding.>
- [ ] <e.g. all existing tests pass with zero regressions> [deterministic]
- [ ] <e.g. the new flow is coherent from an operator perspective> [judgment]

**QA criteria:**       <Required for Elevated. YAML block: qa_skip (one of 5 valid
                        enums or null), qa_skip_rationale (if qa_skip != null),
                        viewport, scenarios[] (method in {browser, api,
                        runtime-required, visual_conformance, accessibility,
                        perceptual_diff, motion}), manual_smoke.
                        Absence on Elevated is a Critical Skeptic finding.>

**Linked artifacts:**  architect-plan: <path>; orchestration: <path or inline JSONL>

Brief field guidance

  • Problem - behavior gap, not solution. If you wrote "add X", restate as "users cannot Y".
  • Success criteria - pass/fail testable from outside. Drives Skeptic completion review.
  • Non-goals - written to defeat the most likely scope-creep direction.
  • Constraints - only what would change the architect's design if violated.
  • Verification - non-skippable. Name the concrete tests, gates, qa.md trigger patterns, and regression tests from the findings flywheel. If verification cannot be specified, that is a planning gap - Brief is not Skeptic-eligible until it is named.
  • Outcome rubric - distinct from Verification. Verification names gate commands; the Outcome rubric is the operator's semantic definition of done. Deterministic lines name a gate; judgment lines are graded adversarially by the Skeptic.
  • QA criteria - required for Elevated. YAML block with qa_skip enum (or null) and scenarios[]. Absence on Elevated is a Critical Skeptic finding.
  • Linked artifacts - makes the Brief auditable against its own inputs.
<=20 lines total. If the Brief exceeds one screen, it is a mini-spec - rework it. The Brief is a commitment, not a design document.

Plan-tier directory

docs/planning/<slug>/
  brief.md                  # Brief template (assembled)
  architect-plan.md         # architect's existing output, as-is (assembled)
  orchestration.jsonl       # orchestration-planner output, verbatim (assembled)
  risk-register.md          # <=10 lines, conductor-authored (coverage)
  rollback.md               # <=10 lines, conductor-authored (coverage)
  verification-gate.md      # see template, conductor-authored (coverage)

Most of the Plan is stapled artifacts. Only 3 short files are conductor-authored:

  • risk-register.md - operational risk, not covered by the architect plan
  • rollback.md - procedure to undo, not covered anywhere upstream
  • verification-gate.md - trigger for rollback; owns the "how we know it failed" signal
If any of the three authored files exceeds 10 lines, the Plan is too large. Split into multiple Briefs.

Verification gate

verification-gate.md template:

# Verification Gate

**Tests that must pass:**
- Unit: <commands or "n/a">
- Integration: <commands or "n/a">
- E2E: <commands or "n/a">

**qa-engineer triggered?** <yes/no>. If yes, list qa.md trigger patterns and the units they apply to.

**Manual smoke check:** <single paragraph or "none">

**Rollback signal:** <how we know post-merge this needs revert - what alarm, metric, or user signal.
                      This hands off to rollback.md.>

**New regression tests required by findings flywheel?** <yes/no>. If yes, list .agentic/findings.md
                      entry IDs and the test files that will hold the regression.
Split of responsibility: verification-gate.md owns the trigger (the signal that says "something went wrong"). rollback.md owns the procedure (the steps to undo). They are complementary, not overlapping.

Gate semantics

Blocks engineer spawn:

  • Missing required artifact at any tier
  • Brief or Plan has Skeptic findings open (Critical or Major)
  • Open Questions section non-empty (same hard gate as architect plan; a non-empty Deferred defaults section does NOT trigger this gate)
  • Verification gate field set to "cannot specify"

Does NOT block:

  • Risk class = Elevated single-unit (no Brief required - architect plan is the artifact; current behavior preserved)
  • Trivial units in any plan
  • Low-risk work (no Brief at any threshold)

Worker contract additions

Two new optional fields in the execution contract:

- outputs: ...
- budget: ...
- tool_scope: ...
- completion_conditions: ...
- output_paths: ...
- brief_path: docs/planning/<slug>.md        <-- new (Brief tier)
- plan_path:  docs/planning/<slug>/          <-- new (Plan tier)

When populated, the engineer:

  1. Reads the Brief or Plan before starting any implementation.
  2. Treats success criteria and verification gate as authoritative alongside the architect plan.
  3. Returns BLOCKED on Brief-vs-architect-plan conflict (rather than guessing).
brief_path and plan_path are populated by the conductor at spawn time. Workers do not discover or locate these themselves.

Mid-flight retroactive Brief

A task can be promoted upward mid-work. It cannot be demoted.

When escalation fires (e.g., a 3-unit Brief-tier task is re-planned into 8 units):

  • The in-flight engineer is allowed to return.
  • Already-completed units are not retroactively re-reviewed.
  • The retroactive Brief (or Plan) is authored before the next engineer spawn.
  • The retroactive artifact governs all subsequent units.
  • The Skeptic pass on the retroactive artifact runs to completion before the next worker spawns.
  • The ticket's .agentic/loop-state-<LOOP_KEY>.json (legacy: .agentic/loop-state.json) has promotion_tier updated to reflect the new tier.
"Retroactive" means the Brief was not written at the start because the shape wasn't yet known. Not a failure mode - it is the correct protocol for tasks whose scope expands during execution.

3rd-resume auto-promotion

Trigger: the ticket's own .agentic/loop-state-<LOOP_KEY>.json records a third resume of a Brief-tier task.

When it fires, the conductor authors the missing Plan-tier artifacts before the next worker spawn:

  • risk-register.md
  • rollback.md
  • verification-gate.md

The trigger is mechanical - the resume_count field in that ticket's keyed loop-state file, incremented once per accepted resume. It fires regardless of whether the operator notices the session span.

Rationale: anything that has survived three resume cycles is demonstrably multi-session work. The risk register and rollback procedure exist precisely because multi-session tasks have higher blast radius when they go wrong.

Auto-promotion is not a penalty. It is an acknowledgment that the task's actual scope exceeded the initial estimate, and the artifact set should match the real scope.

Plan once. Resume often. Verify always.

github.com/Space-Dinosaurs/DinoStack