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), MEMORY.md (stable facts), AGENTS.md (architecture). 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 (MEMORY.md is not a design doc)
• Does not automate irreversible operations at git/infrastructure boundary (human confirms)
• 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. Step 0 validates completeness before any review content is produced; incomplete inputs return BLOCKED. Supplemental reviewers (security-auditor, perf-analyst) receive a lexically distinct Supplemental-context block with no Step-0 enforcement.
• 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

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. Hitting the cap escalates to the human; the conductor does not spawn a fourth pass.
• 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.
• 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 writes all entries (pending → in_progress → done/failed/blocked). 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). 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

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 spawn_complete carries findings_count, diff_lines, signed_off, and iteration inside data. Conductor builds the merged JSON inline; subagents never write to .agentic/.
• 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/agentic-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

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. Engineer, release-orchestrator, learnings-agent, and wrap-ticket write files. 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.