DinoStack

The Four Goals

• Goal 1 - Responsiveness. Conductor stays free to respond. All work backgrounds. Spawn threshold is intentionally low. Never implement inline.
• Goal 2 - Adversarial accuracy. LLMs are systematically overconfident about their own outputs. Fresh Skeptic counters anchoring bias. Brief passed verbatim. No self-review path for Elevated work.
• Goal 3 - Cross-session continuity. Three tiers: context.md (ephemeral), decisions.md (decision log), AGENTS.md (architecture) - operationalized project-side by the AGENTS.md/CLAUDE.md/MEMORY.md triad (MEMORY.md holds stable facts). Stop hook auto-writes. /ds-wrap enriches. No ceremony required from user.
• Goal 4 - Context window efficiency. Always-loaded files must be minimal. Trigger-pointer pattern: risk signals inline (chicken-and-egg), protocol details deferred until triggered.

Explicit Non-Goals

• No persistent memory of personal facts or preferences (project-affecting info only)
• Does not replace proper documentation (decisions.md is not a design doc)
• Does not skip verification at the git boundary - the shipped ds-implement-ticket workflow commits and pushes, and auto-merges on green CI when auto_merge_on_ci_green is enabled (default false, which leaves the PR for human merge); the tier's own required check (a fresh Skeptic sign-off for Elevated, a brief inline self-check for Low, the engineer's own quality gates for Trivial) is never bypassed, and failed CI or an unresolved Critical/Major finding is a hard stop. Methodology-owned repo-hygiene operations named in Standing authorizations (branch cleanup on a satisfied merge signal, worktree removal, session-start prune) are likewise durably pre-authorized, never an operator choice
• Does not guarantee correctness (defense in depth, not proof)
• Does not eliminate need for human judgment (escalation paths exist for ambiguity)
• Does not manage infrastructure or secrets

The Core Loop (Sections 1-5)

• Worker implements → fresh Skeptic critiques → findings routed back → repeat until clean sign-off
• Fresh Skeptic every round - never continued from prior round. Independence requires clean context (no anchoring to Worker's justifications)
• Global-context input set (Section 4.5) - every Skeptic spawn prompt includes: architect plan, Brief/Plan artifact, qa_criteria block, per-consumer impact table, related files, diff under review, and conductor spawn brief (claim-bearing text only, or n/a). Step 0 validates completeness before any review content is produced; incomplete inputs return BLOCKED. The enumerated n/a rationale set is canonical preferred wording, not an exhaustive whitelist, and falsity discovered after Step 0 is raised as a finding rather than a retroactive BLOCK. Supplemental reviewers (security-auditor, perf-analyst) receive a lexically distinct Supplemental-context block with no Step-0 enforcement. A set-shaped claim in any field (a file list, a per-consumer impact table, a count of instances or call sites) is navigational context, not verified evidence - the Skeptic independently re-derives it with Grep/Glob/Bash before relying on it.
• The provenance test (Section 4, Risk Classification) - every claim-bearing sentence the conductor writes into a spawn prompt carries one of three tags: [verified: file:line] (confirmed against origin/$BASE_BRANCH this session), [per <agent>, unverified] (sourced from a subagent's return), or [verified-local: <path> - untracked-by-design|branch-new] (for paths where an origin/$BASE_BRANCH check is structurally wrong - docs/planning/**, evals/**, root MEMORY.md, and .agentic/** are illustrative instances, not an exhaustive list; the tag applies to ANY gitignored or untracked path). Before citing such a path, the conductor confirms it is genuinely absent from the worktree via its absence from git -C <repo-root> ls-tree origin/$BASE_BRANCH <path> - run with an explicit -C <repo-root> so the answer cannot change with the conductor's own cwd - absence means empty stdout, not exit status (the property that actually governs worktree visibility, including the force-added-yet-gitignored edge case), since the command exits 0 whether or not the path exists (a nonzero exit means the check did not run, not that the path is absent), then states that reason. An untagged directive-shaped claim is a protocol violation; the Skeptic enforces it via Global-context field 7 (step 3.7, Major finding per untagged claim).
• Resolved Issues Preflight prevents re-raising fixed items, but Skeptic can contest insufficient resolutions
• Same finding contested 2+ re-routes → escalate to human (prevents infinite loops)
• Simple/targeted changes: capped at 1 Skeptic round. Standard Elevated: 2-re-route limit
• Prose-scoped re-check - when every unresolved finding is prose-only (stale module manifest, doc-sync attestation, comment/count wording) with no code/test/behavior change in the fix diff, the next round is narrowed to those prose lines plus a full end-to-end read of the enclosing manifest/section instead of a full fresh adversarial pass; the reviewer (not the engineer) establishes the trigger by diffing the fix commit(s), the conductor names the mode and supplies the sha1..sha2 fix range at spawn, and sign-off carries a mandatory Scope: line; any code/test/behavior finding found during it still escalates normally, and severity tiers are unchanged

Findings Classification (Section 6)

• Critical - blocks sign-off. Security vulns, correctness failures, data loss paths
• Major - blocks sign-off unless Worker provides compelling documented reason to defer. Missing error handling, edge cases, design issues
• Minor - never blocks sign-off. Applied by a separate Worker after sign-off, no follow-up Skeptic needed
• Unclassified findings default to Major

Persistence Loop (inside /ds-implement-ticket)

• Loop-aware, not one-shot - /ds-implement-ticket runs Engineer → Skeptic → QA as a bounded loop, not a single pass. Re-routes are a named primitive, not ad-hoc conductor judgment.
• Max 3 fix passes per phase - Skeptic loop (Phase 6) and QA loop (Phase 6b) each have an independent 3-pass cap; the conductor does not spawn a fourth pass. At the cap, the conductor ships (recording every unresolved non-Critical finding as accepted debt) or escalates to the human - never silent continuation. An unresolved Critical always escalates; the cap never ships a Critical. The round-count cap is mechanically enforced for Skeptic spawns by hooks/enforce-skeptic-round-cap.py, regardless of caller (ad-hoc or Phase 6), whenever the spawn prompt's "Diff under review" line is present and unambiguous - when it is not, the hook fails open with no state written rather than blocking; a known accepted residual is that two different units both expressed as a bare git diff <same-base>..<head> SHA range share one counter; a second, separate accepted residual is that a stable-key value whose first pipe-separated path lacks a file-extension-shaped suffix (e.g. LICENSE | a.py) still passes the shape gate and becomes a wrong-but-stable key shared across units. The Critical-never-ships rule inside it is conductor-attested, not independently verified from any Skeptic finding. Inside Phase 6 specifically, the ship branch's own step text is a conductor override requiring operator approval, not yet an automatic path.
• Findings accumulate - the findings_log carries forward across iterations. A finding closed in iteration 1 cannot be silently re-raised as new in iteration 2; the Skeptic must explicitly contest the claimed fix using a [PREV: id] tag.
• Convergence failure - one re-raise of a Critical finding after a claimed fix triggers immediate escalation (does not consume remaining iteration budget). Signals a design-level conflict requiring human arbitration.
• Explicit escalation contract - the loop exits with a structured stall report (cap_reached, convergence_failure, or blocked) listing open findings and recommended actions.
• Durable state - loop state is written per ticket to .agentic/loop-state-<LOOP_KEY>.json at every phase transition (atomic write), superseding the single legacy .agentic/loop-state.json, which is still read and adopted when present. Keying per ticket means two sessions working two different tickets in one checkout each keep their own bookkeeping instead of contending for one file. Long-running loops survive rate limits and session exits: on the next /ds-implement-ticket invocation the conductor detects the interrupted state for that ticket's own key, applies a rate-limit wait if needed, and resumes from the last committed phase boundary. Schema includes brief_path, plan_path, and promotion_tier fields that record the planning artifact tier for the active task (used for mid-flight promotion and auto-promotion at the 3rd resume). No work is lost.
• Learning extraction - at Phase 6 clean exit (Skeptic sign-off), the learning-extractor agent reads the resolved findings_log and writes structured fix-pattern entries to .agentic/learnings.md (append-only, dedup, cap 5/run). Each entry has ID LRN-YYYYMMDD-XXX, severity, domain tag, pattern description, fix guidance, and source reference. These entries feed into wrap-ticket at Phase 11b for richer MEMORY.md/decisions.md appends. Soft-fail only; never blocks the loop. During active sessions, the learnings-agent captures learning events in real-time (error→fix cycles, resolved Skeptic findings, discovered workarounds) and writes them immediately to .agentic/learnings.md, reducing reliance on manual /ds-wrap.
• Knowledge commit on the PR (Phase 11e) - after the PR is open, /ds-implement-ticket first drains this session's in-flight learning shards (ds-learning-shard rollup, soft-fail), classifies each entry through the guardrail-first capture gate, and forwards the Capture: MUST ones to learnings-agent - then commits any changed MEMORY.md, decisions.md, .agentic/learnings.md, AGENTS.md, and .agentic/tracking.md onto the PR branch itself, so a ticket's durable knowledge ships with the work that produced it instead of stranding in the operator's local checkout. Checkout-free and worktree-free (temporary index plus commit-tree, pushed straight to the branch ref); soft-fail throughout; gitignored files are skipped with a visible diagnostic, and a file whose negation is present but defeated by git's own oracle is skipped with a louder ERROR naming the path (ds-migrate verify-commit-path, the exact-path counterpart to ds-migrate check/apply's manifest-wide sweep). Disable with knowledge_commit_on_pr: false in .agentic/config.json.
• North Star alignment in the PR body (Phase 9) - both gh pr create body branches (behavior-visible-with-QA-evidence, and all else) emit a ## North Star alignment section at create time, filled from the architect plan's own vision-alignment content - the pillars it named as cutting against the change, not only the supporting ones - or a stated N/A, which is what a repo carrying no docs/overview/vision.md emits. --body-file bypasses .github/PULL_REQUEST_TEMPLATE.md entirely (the template only populates web-UI PRs), so without this every conductor-composed PR touching a methodology-shaping path opened with a red required check-vision-alignment on this repo. A Pillar 7 left-shift: the mechanical check moves to the producing step while the reviewing check keeps running, now also on edited so a body-only fix clears the red without a fresh push. The reviewer additionally discounts template scaffolding - HTML comments (including the PR template's own multi-line instruction block, which a line-based strip left intact), bullet labels, and the unfilled [pillar]/[trade-off] placeholders - before testing the section for emptiness, so emitting the section cannot turn a red into a vacuous green; the emitted section is kept last in the body for the same reason, since the check reads to the next heading.
• Task coordination surface - multi-unit orchestration plans use .agentic/tasks.jsonl as a durable task coordination surface; the conductor tracks task status, dependencies, and loop state across the plan lifecycle. Applies to plans with 2+ tasks; single-unit spawns use in-context state only.
• Context-size preflight - at the top of /ds-implement-ticket, before any Phase 1 work, a two-level guard checks session load: if the turn count is at or above the soft limit (15–20 conductor turns) with substantive tool-call results in context, or a prior subagent result block of substantive size is visible from this session, it prints a warning with the recommended /ds-wrap → new session → re-invoke pattern and waits for operator confirmation; above the hard limit, it refuses further implementation and subagent spawns unconditionally. Silent on clean sessions.
• Phase 12b: Operator Runbook - after all tickets in a session complete, the conductor prints a structured handoff: what PRs landed (✓ PR #N → url), the next copy-pasteable /ds-implement-ticket command (extracted from the most recent triage artifact's Kickoff prompts), and any blockers or deferred items. Soft-fail throughout; skipped when no PR was opened, when Phase 12a already printed a pause summary, or when Phase 12a’s goal-met short-circuit already printed a terminal summary.

Parallel Fan-out slides

• N engineers in one message - when orchestration-planner returns 2+ independent units, /ds-implement-ticket Phase 5 fans out: one worktree-isolated engineer per unit, all spawned in a single message (parallel). N=1 falls through to the standard path.
• Per-unit P0 loops - each unit runs its own Engineer → Skeptic persistence loop inside its worktree. "Done" means Skeptic signed off, not first commit. The conductor joins only after every unit reaches a terminal state.
• Skeptic strategy driven by planner - skeptic_strategy: per-unit: independent units each get their own Skeptic (can run in parallel). skeptic_strategy: integration: interdependent units share one Skeptic reviewing the combined diff - replaces Phase 6, not layers on top. skeptic_strategy: multi-dimensional: for high-stakes Elevated units (auth, payments, migrations, crypto) - fans out correctness-Skeptic, security-auditor, and perf-analyst in a single message on the same diff; all three must clear before sign-off.
• Join conditions - all-done (merge in merge_order), partial success (merge green units, retry failed once at depth=1), total failure (escalate), blocked (escalate immediately).
• Sequential --no-ff merge - unit branches merged in planner-specified merge_order. Conflict at any step: abort, stop remaining merges, spawn single engineer for sequential re-implementation. Post-merge integration quality check catches cross-unit failures.
• Task state in .agentic/tasks.jsonl - conductor appends all entries across agents (pending → in_progress → done/failed/blocked); never a rewrite, and a task-state fold reconciles records across concurrent conductor sessions. Workers return summaries only. Crash recovery: in_progress entries on resume treated as failed, re-spawned with original brief from inputs field.

Cost-Aware Tier Routing

• Conductors declare Tier 1/2/3 at spawn time - routes lightweight tasks to faster models and critical reviews to max-capability models
• Tier 1 - cheap/fast (Haiku). Declare explicitly for shallow reads, existence checks, format-only tasks, and mechanical transformations
• Tier 2 - implementation default (Sonnet). Most spawns land here: engineer, investigator, qa-engineer, and other implementation roles
• Tier 3 - review default (Opus or above - opus/fable). Skeptic and security-auditor default to Tier 3 via frontmatter; upgrade architect/engineer to Tier 3 for novel architecture or high-blast-radius units; on Plan+ADR-tier units (cross-track / architecture-constraining), the authoring architect/adr-generator/product-discovery must also be Tier 3, conductor-declared via explicit model: opus and backstopped by enforce-tier.py
• Tier is a required field - every Elevated spawn carries a Tier: line below Risk:. Each agent's frontmatter model: sets the model when the spawn-call param is omitted; the param overrides for upgrades or budget-mode downgrades (never for mandated-Tier-3 Skeptics). Declaration without the tool-call param produces frontmatter-default behavior, not Tier 2
• Codex/Gemini resolve tiers from ~/.agentic/tier-map.yml - Claude Code uses a built-in enum (haiku/sonnet/opus); no tier-map lookup needed for Claude
• Pi/oh-my-pi can resolve roles from ~/.agentic/role-models.yml - opt-in per-role model strings plus antagonist reviewer diversity for skeptic and security-auditor; if absent, Pi uses session defaults

Adversarial Brief Requirement (Section 7)

• Brief is passed to Worker and Skeptic verbatim - never softened, summarized, or editorialized
• Brief extension is additive only - domain-specific concerns may be added, existing language never removed or softened
• Neutrality requirement - every field, in every form, tagged or untagged, carries no conductor-composed hypothesis, suspicion, or attention-steer; completeness and neutrality are independent axes; no carve-out for an "operator-attributed" steer
• Mechanically enforced (hooks/enforce-skeptic-neutrality.py, DS-187) - a PreToolUse hook denies a Skeptic spawn whose field 7 contains an untagged claim-bearing sentence (a structural conformance check, not a phrase scan), or whose adversarial brief matches a narrow conductor-composed-steer phrase (categories B/C only)
• The ban applies to every field, every form, tagged or untagged - not just the two bounded surfaces the hook checks; the reviewing Skeptic's Step 3.9 Neutrality check is the control for every other steer shape

Domain Adversarial Briefs (Section 8)

• Smart contracts: reentrancy, access control, signature replay, fee bypass
• Auth/sessions: session fixation, token replay, privilege escalation
• API endpoints: malformed inputs, race conditions, missing validation
• Crypto: weak randomness, domain separation, algorithm confusion
• DB/migrations: idempotency, partial failure, rollback paths
• Data pipelines: double-processing, silent failures, state divergence
• Doc synthesis: internal consistency, assumptions, completeness gaps
• General code: logic errors, edge cases, incorrect assumptions

Elevated + Cleanup Path (Section 12)

• Worker → Skeptic sign-off → /simplify → narrow-scope Skeptic
• For substantial implementations where code hygiene matters
• Second Skeptic reviews only the /simplify diff (behavioral preservation check)

New Skeptic Obligations

• Module manifest check - tiered enforcement on non-trivial modules (exports a public symbol, ~50+ LOC, or side-effecting): missing manifests are Minor (comprehension hygiene, non-blocking); stale manifests (no longer reflect purpose, public API, dependencies, or failure modes) are Major (blocks sign-off absent a compelling documented reason to defer); stale manifests whose inaccuracy could mislead a caller on a correctness or security path are Critical. The result is now output-required via a fixed Manifest check: sign-off line.
• New-test-CI-wiring check - for each new test file in the diff, verifies a matching reference exists in a CI workflow (an exact file reference, a covering glob, or an auto-discovering runner). A new test file wired into no CI workflow is a Major finding - a test that never runs provides no regression protection. The result is output-required via a fixed Test-CI-wiring check: sign-off line.
• Regression test verification - before granting sign-off when a Critical/Major finding was fixed, verifies a regression test was added (or a documented exception given). Missing test without explanation is a Major finding. The same verification applies to QA-fix iterations: a fix engineer addressing a qa-engineer FAIL must add a regression test or append a documented exception to .agentic/qa-regressions.md (see qa-regression-obligation.md).

Cognitive Surrender Check

• A Skeptic that agrees with the Worker on every point with zero findings across two iterations is a possible rubber-stamp - the failure mode of treating the LLM as System 3 and outsourcing judgment rather than offloading mechanics.
• Cure: an audit-note Minor finding attesting that the Skeptic re-read the diff end-to-end with independent attention. The note documents what was checked, not what was wrong.
• Audit-note Minors are exempt from the /ds-implement-ticket Phase 6 re-raise and convergence-failure detection - they are bookkeeping, not contested findings, and must not stall the loop.

Calibration Layer (Section 13)

• The audit-note Minor is the per-spawn rubber-stamp defense. The calibration layer is the long-horizon backstop - aggregate drift detection without enlarging the per-spawn review surface.
• Findings counters in events.jsonl - every Skeptic conductor-emitted spawn_complete carries findings_count, diff_lines, signed_off, and iteration inside data. Conductor builds the merged JSON inline; subagents never write to .agentic/. (A separate, deterministic hook-emitted spawn_complete variant also exists as of DS-160 - as of DS-178 it ALSO best-effort resolves these same calibration fields, plus agent_source/unit_key/model, directly from the completed subagent's own transcript and round-cap state - see the Events Log reference.)
• 5% sampled meta-Skeptic - deterministic hash(task_id+iteration) % 100 < 5. Background fire-and-forget; conductor declares the unit complete without waiting. Meta-Skeptic returns text only; conductor parses and emits meta_review_complete.
• Surfacing - Critical/Major divergence on a sampled spawn surfaces as one inline META-DIVERGENCE: line at the next turn boundary. Original sign-off remains binding; the notice is advisory. Dual triggers: in-session (Phase 6 boundaries) and session-start sweep (catches async returns from prior sessions). The sweep paginates via .meta-divergence-last-sweep timestamp tracker — reads only events newer than the last sweep, capped to 100 lines on first run.
• bin/ds-calibrate - density (findings per 100 diff-lines, excludes zero-diff rows) and divergence (meta-Skeptic rubber-stamp rate). Warming-up line shown until 10 qualifying spawns observed.
• Threat model: drift detection in a non-adversarial conductor relationship. Not cheating-prevention - a compromised conductor can mis-emit counts. Target is operator self-deception over time, not adversarial spoofing.

The Seven Rules

• Rule 1 - Always background. Most critical rule. Foreground blocks the conductor entirely. All delegated work runs in background.
• Rule 2 - Parallel by default. Independent tasks spawn simultaneously. "Can I start B before A finishes?"
• Rule 3 - Spawn threshold. Elevated risk → spawn. Low risk → direct action. When in doubt, Elevated.
• Rule 4 - Agent type discipline: spawn an agent type that exists. No subagent can spawn subagents (a platform property of every subagent). Low-risk shell/git is conductor-direct - there is no shell-only agent type.
• Rule 5 - Skeptic Protocol orchestrated by main agent. Architect plans must receive Skeptic review before acting on them.
• Rule 6 - Check in, don't disappear. Status updates immediately after spawning. Proactive reporting when tasks complete.
• Rule 7 - Direct actions permitted. Reads, git status, screenshots, memory answers, synthesizing returned results.

Composition Pattern (Section 6)

• Decompose into atomic units (one agent, one task, one prompt)
• Classify risk per unit independently
• Spawn in parallel for independent units
• Review scope: independent units get per-unit Skeptics; interdependent units get one integration Skeptic (sees combined diff)
• Mid-task re-decomposition if Worker discovers scope is too broad

Worktree Isolation (Section 7)

• Parallel agents writing to same repo MUST use isolation: "worktree"
• Without it: concurrent git checkout silently corrupts both agents' work
• Not needed for: single agents, separate repos, read-only agents

Anti-Patterns (Section 8)

• Foreground blocking (most critical violation)
• Sequential when parallel is possible
• Treating risky shell/git as conductor-direct to dodge review
• Main agent doing implementation work
• "Looks simple" rationalization
• Softening adversarial briefs
• Priming adversarial briefs with conductor hypotheses

Sections 9-13

• 9. Relationship to the Skeptic Protocol - the two protocols are complementary: this one governs delegation decisions, the Skeptic Protocol governs the inner review loop.
• 10. Input Contract - the execution contract block (outputs, tool_scope, completion_conditions) an engineer Worker spawn must include on Elevated-risk tasks.
• 11. Output Expectations - what a Worker returns (final output, round summary, memory update requests), the re-route limit, and side-effect disclosure rules.
• 12. Sync with Related Documents - this document is canonical; ~/.claude/CLAUDE.md and skeptic-protocol.md must be checked for drift when it changes.
• 13. Conductor context budget - soft limit (~15-20 turns, warn and recommend /ds-wrap) and hard limit (~25-30 turns) for long-running conductor sessions.

The Team

18 named agents (investigator, debugger, security-auditor, architect, orchestration-planner, engineer, skeptic, qa-engineer, adr-generator, adr-drift-detector, perf-analyst, product-discovery, release-orchestrator, dependency-auditor, learning-extractor, goal-condition-evaluator, wrap-ticket, learnings-agent). Most agents are read-only - 11 of 18 write files: adr-generator, engineer, learning-extractor, learnings-agent, product-discovery, release-orchestrator, wrap-ticket, and (Bash-heredoc only, no Write/Edit grant, scoped to their own .agentic/audit-reports/ report file or, for qa-engineer, /tmp/qa-reports/ - deliberately /tmp/, not .agentic/, since qa-engineer always runs isolation: "worktree") adr-drift-detector, dependency-auditor, perf-analyst, and qa-engineer. Full descriptions in the Agent Layer section below.

Decision Rules

• orchestration-planner when task is complex, agents/sequencing unclear, multiple phases
• architect when meaningful design decisions, unfamiliar codebase, multi-subsystem feature
• security-auditor when touching auth, sessions, tokens, secrets, privilege boundaries
• debugger when root cause not obvious, stack trace needs diagnosis
• Skip architect for well-understood changes → straight to engineer
• Skip debugger for already-understood bugs → straight to engineer

Spawn Requirements

• engineer: architect's plan + file paths + acceptance criteria + session context
• skeptic (plan review): adversarial brief verbatim + architect's complete plan + architectural constraints
• skeptic (code review): adversarial brief + engineer output + resolved issues preflight
• security-auditor: files changed + domain description + known mitigations
• All agents spawn in background. Main session is the sole orchestrator.