The core pack as a system

Understand how the core pack combines planning, verification, review, and stateful iteration into a reliable delivery loop.

The other packs in this catalogue are accessories — workflows, doc shapes, credentialed primitives. core is the pack you’d lose sleep about losing. It ships the discipline that turns “the agent wrote some code” into “the agent shipped code that survived a cold adversarial read.” This page explains the parts, how they fit together, and why the result is more productive than vibe-coding or the closest competing approaches (GitHub’s Spec Kit and Kiro IDE’s spec-driven mode).

Why loop engineering

The leverage in agent coding has moved off the prompt. A single sharp prompt buys you one good turn; the work that actually ships features lives in the loop around it — the thing that plans, makes the change, verifies it, reviews it, and decides what comes next. You stop hand-driving every turn and start designing the loop that drives them.

  design the loop, then let it run:

        ┌────────────────────────── fix ◄─────────────────────┐
        │                                                      │
        ▼                                                      │
      PLAN ───► EXECUTE ───► GATES ───► REVIEW ───► DECIDE ────┘──► ship
      surface   smallest     lint       fresh eyes,  fix or
      assump-   coherent     types      a cold read  finish
      tions     change       tests      of the diff
        │
        └──► spec · plan · state.json · captured learnings
             (on disk — the loop's memory survives the next run)

A loop running on its own is also a loop making mistakes on its own, at machine speed — so it has to check its own work harder than you would by hand. Three forces make that non-negotiable, and core answers each:

The model grades its own homework too kindly. The agent that just wrote the code is the worst judge of whether it’s right. core splits the maker from the checker: adversarial-reviewer reads the diff cold in a separate context, with no memory of why the code looks the way it does and no sunk cost to defend.
The model forgets everything between runs. Nothing in the agent’s head carries to the next session, so the memory lives on disk — the spec, the plan, state.json, AGENTS.md, CONVENTIONS.md, and the learnings captured at the end of every loop. The next run reads the repo, not a transcript.
Your attention is the bottleneck, not the tool. You can spawn more agents than you can meaningfully review, and the gap between what ships and what you actually understand widens every time you wave a change through. core keeps you in the judgment seat on purpose: it surfaces assumptions and stops before building on them, gates on checks you can trust, and refuses to self-certify past a red gate or a repeated finding.

A loop will happily make you faster on work you understand — or let you skip understanding it at all. The loop can’t tell those apart. You can. core is built for the first kind of engineer: the one who designs the loop and stays the engineer, not just the person who presses go.

Razor: cut before adding

Core’s Razor product principle keeps the loop from turning every request into more machinery. Once the touched code is understood, the agent stops at the first sufficient solution: omit work that is not needed, reuse what the repository already owns, prefer built-in capabilities, and write new code only when those choices do not satisfy the outcome. “Minimum” means the smallest obvious, maintainable change in the right owner—not code golf.

The discovery check is intentionally bounded, but verification is not. Razor never removes trust-boundary validation, data-loss protection, security or privacy controls, accessibility, accepted requirements, required delivery work, human approval, or non-waivable policy. It also trims communication: state the outcome, omit routine tool narration, ground necessary repository claims, and close with what changed, how it was verified, and what remains.

Razor is an engineering-economy principle inside Core. It is not a fifth admission principle for catalogue packs under the Charter, and it is unrelated to the visual and interaction design principles used by the tech-site pack.

The parts

The core pack ships seven tightly-coupled artifacts plus the documents they all read:

AGENTS.md — the project’s agent context, loaded first by every skill, every subagent, every reviewer. It carries the non-negotiables (“touch only what you’re asked to touch”), the source-of-truth table, the check-before-acting rules. If a subagent skips it, the review is wrong.
docs/CONVENTIONS.md — the why behind AGENTS.md. The verification-mode taxonomy (TDD / goal-based / visual-manual), the loop-iteration cap, the model-selection table, the rationale for every rule. AGENTS.md cites it for anything that needs a paragraph.
The new-spec skill — drafts docs/specs/<feature>/spec.md + plan.md. Mandates assumption-surfacing before any spec body is written, mandates a Boundaries section with at least one structural Never do, mandates per-task Tests: before Approach:. The spec is the contract; the plan is the strategy.
The work-loop skill — the plan → execute → gates → review → fix loop. Tracks state in state.json (gitignored, session-scratch), enforces an iteration cap, detects stasis (same findings twice = stop and surface), and gates EXECUTE on plan-approval after a pre-EXECUTE adversarial review.
Shaping review — new-spec uses the internal shaping-reviewer before construction begins to test the contract’s scope and observability. It is distinct from the later code-review lenses, which now own disjoint concerns: adversarial checks delivery drift and contract conformance, security owns every threat finding, and quality owns test strength and maintenance cost. A reviewer that spots another lens’s concern says so in its own lens rather than emitting that lens’s finding.
The reviewer subagents —
- adversarial-reviewer (Opus): reads spec/plan or diff cold, against AGENTS.md + CONVENTIONS.md + the spec. Returns severity-labeled findings (Blockers / Concerns / Nits). Cannot be skipped.
- finding-adjudicator (Opus): independently tests each completed reviewer report that reaches it against current evidence and governing authority before a finding can trigger repair. A report the loop classifies clean by structure is accepted mechanically without an adjudicator call; one carrying security-reviewer’s coverage-disclosure footer always takes the adjudicator path, because that footer is prose. A malformed report stops the loop rather than routing anywhere. The adjudicator owns reachability and preserves refuted or indeterminate results for audit.
- security-reviewer (Opus): OWASP + STRIDE lens. Conditional — runs when the diff crosses a security boundary.
- quality-engineer (Opus): testability, observability, reliability, maintainability. Conditional. It exclusively owns test strength — whether a test can actually fail — and the inferred edge cases the spec never named; adversarial owns whether the promised artifact exists at all.
- implementer (Sonnet): single-task executor for supervisor mode. Not a reviewer.

The reviewers are diff-source-agnostic — the work loop points them at your own working tree, but you can point them at any diff, including a teammate’s branch or open PR. See Review a branch or PR you didn’t write.

The session-start.py + pre-pr.py hooks — wire the loop into the editor lifecycle. session-start.py reads the install-marker and nudges into adapt-to-project on first session.

Plus a sibling skill that runs alongside the seven: bug-fix ships in core too and runs a parallel discipline (reproduce → red test → root vs. symptom → minimum fix → regression test stays) without entering the spec / loop pipeline. It composes with work-loop when the fix grows past one file. See how to fix a bug.

Another sibling handles reusable repository lessons: project-knowledge is the explicit capture, distillation, and enquiry surface. Workflows keep scratch locally until a semantic gate decides whether one lesson is worth preserving. Its work-loop producer profile turns that semantic judgment into the strict capture request and fixed review enquiry; the full raw-request path remains available. Capture writes a strict pending observation journal event; distillation reconciles pending observations into reviewed topic proposals or bounded terminal dispositions; enquiry reads active topics from one committed Git snapshot and returns a bounded evidence envelope with a receipt.

That boundary is deliberate. Scratch can disappear before capture if the workflow or worktree disappears. Journals are durable handoff records, not a query source. Retention and compaction are deferred to a future whole-partition policy, so the first slice has no per-event deletion path. Retrieved topic text is evidence only: it cannot grant permission, choose tools, approve mutations, widen scope, override runtime instructions, or write itself back as evidence.

And a depth skill the loop reaches for by surface: frontend-engineering is loaded inline by work-loop whenever a task’s primary output is HTML, CSS, or JS. It carries the design pre-flight (a named aesthetic reference, a seed token block, the six-state matrix), the codified craft rules that govern EXECUTE, and the GATES verification commands (html-validate, pa11y/axe, stylelint) — and it upgrades the design-intent pass from a recommendation to mandatory for that surface. It has no user-prompt activation surface of its own; the loop pulls it in, the way it pulls in security-checklists and operational-safety for the reviewers.

How they tie together

A feature lifecycle, end to end, with the parts named:

User asks for X. “Add webhook retries with exponential backoff.”
new-spec runs. The agent scaffolds docs/specs/webhook-retries/ and stops to surface assumptions — technical, product, process — before filling in any spec body. The user signs off (or revises). Bodies fill in: Objective, Boundaries (including a structural Never do), Testing Strategy with a verification mode per user-visible outcome, Acceptance Criteria. The plan follows with tasks, each with Tests: before Approach: and an explicit Depends on:. For TDD tasks, the exact code in that Tests: section is a planning proof: PLAN compiles and exercises it from disposable scratch without adding a repository test file.
shaping-reviewer reads the draft contract cold before plan approval; then adversarial-reviewer reads the complete spec + plan for construction risk. A structurally clean spec-review report closes review mechanically; every other completed spec-review report — one carrying findings, or a coverage-disclosure footer — passes through finding-adjudicator before it can change the spec or plan. Only sustained findings drive repair; each is marked as originating in the draft or a prior review repair, and any green gate used as evidence is bounded by what it proves and a relevant blind spot. Two passes is normal; three means a structural problem and the agent surfaces.
work-loop initializes state.json via its bundled tool, then gates EXECUTE on plan_review_status = approved.
EXECUTE. After the engine enters CODE-IMPLEMENTATION, the agent materializes each approved TDD block unchanged at its real test path, verifies byte identity, and then runs red, green, refactor. For goal-based work: code, then run the one-liner from Done when:. The Boundaries section + the PLAN-step’s declined-pattern register keep new abstractions from sneaking in.
GATES. Lint, typecheck, tests. Mechanical termination. Don’t edit the gate to make it pass.
REVIEW. adversarial-reviewer reads the diff cold against AGENTS.md + CONVENTIONS.md + spec.md. Each report is persisted, then classified: a structurally clean report is recorded directly, a report carrying findings or a coverage-disclosure footer goes to finding-adjudicator, and a malformed one stops the loop. The adjudicator independently sustains, refutes, or stops on each reported finding before the loop acts. loop-cohort review record fingerprints the sustained set, and the loop iterates. Given --operation-id, a repeated recording of the same round is recognised as a completed write instead of counted twice.
Specialist reviewers (if warranted). security-reviewer when the diff changes a security boundary, data flow, or guarding control, including agent authority, untrusted-input, tool, permission, sandbox, or data-handling behavior. Unchanged existing I/O and ordinary prompt wording do not fire it. quality-engineer covers the maintenance lens. Nits from any reviewer do not block readiness: they are recorded with their citation and deferred, and are only acted on — after promotion, if the repair is larger than a Nit — when the thread means to change the code because of one.
Stasis detection. If the next iteration’s findings fingerprint the same as the previous round’s, the loop stops and surfaces. No silent third pass.
Capture learnings. A loop that finished without writing something to a skill, ADR, or pattern note wasted what it learned. The work-loop names where each kind of learning belongs.

The pieces are tightly coupled by design. adversarial-reviewer loads AGENTS.md first because skipping it makes the review wrong. new-spec writes Boundaries because the reviewer measures plans against Boundaries before falling back to the declined-pattern register. The work-loop’s prose gates EXECUTE on plan_review_status = approved, and that field is set by the reviewer-pass step rather than by the implementing agent — so the discipline holds when the loop is followed and only when it is.

Why this beats vibe-coding

Vibe-coding is the null alternative: the agent reads the prompt, writes code, declares done. It works for one-line edits and falls over everywhere else. The failure modes are well-known:

Vibe-coding failure	What core pack does instead
Agent declares victory when it feels done.	Mechanical gates (lint, typecheck, tests) plus a separate-process adversarial reviewer. “Feel” is not a termination criterion.
Scope creeps mid-implementation — new abstraction here, defensive wrapper there.	Spec Boundaries + the PLAN-step’s declined-pattern register. The reviewer flags any addition not named in either as drift.
Edge cases live outside the prompt.	Spec Objective is precise enough to derive tests from; Testing Strategy pairs each user-visible outcome with a verification mode.
Agent retries the same broken approach.	Fingerprint-based stasis detection. Same findings twice = stop, surface to a human.
Convention drift across PRs.	`AGENTS.md` + `CONVENTIONS.md` loaded first by every subagent. Repo rules can’t be forgotten.
No second opinion.	Adversarial reviewer reads the diff cold in a separate context, no memory of the implementation rationale, can’t be talked out of findings.

The cost is the overhead of plan-before-code, of surfacing assumptions before bodies fill in, of an extra reviewer pass. The benefit is fewer broken PRs, shorter review cycles, and code that survives next quarter’s refactor. For non-trivial work the math is decisive; for one-line edits, skip the loop.

How it differs from Spec Kit and Kiro IDE

Two well-known spec-driven workflows exist; the core pack overlaps with both but goes further in different directions.

vs. GitHub’s Spec Kit

Spec Kit ships spec templates (constitution.md, spec.md, plan.md, tasks.md) plus slash commands that drive a /specify → /plan → /tasks → /implement flow (and additional commands like /clarify and /analyze for hardening intermediate artifacts). It’s a strong workflow scaffold and the closest thing to a peer; the comparison below holds as of the catalogue’s last sync with Spec Kit’s README — re-check the source if you’re choosing today.

Capability	Spec Kit	Core pack
Spec template with sections	✓	✓ (plus mandatory assumption-surfacing before bodies, structural `Never do` enforced)
User-driven flow with explicit commands	✓ (slash commands)	✓ (skills auto-invoked by the agent; not literal slash commands today)
Adversarial reviewer reading the diff cold	—	✓ (`adversarial-reviewer`, separate-process, separate model context)
State-machine discipline with iteration cap and stasis detection	—	✓ (`state.json` + `loop-cohort` tool)
Specialist review lenses (security, quality)	—	✓
Supervisor-mode parallelism for independent tasks	—	✓
Cross-harness reach	partial (multiple agent harnesses supported)	✓ (direct adapters for Claude Code, Codex, Copilot, Cursor, Gemini, and Kiro — plus APM’s `HookIntegrator` for the targets it covers)

Spec Kit’s spec-driven loop terminates at /implement — there’s no state-machine loop around it that re-fires until an adversarial reviewer returns clean. The core pack treats /implement as step 5 of 10. The extra five steps — gates, adversarial review, fingerprint stasis, specialist reviewers, learning capture — are the ones that catch the failures spec-shape alone can’t.

vs. Kiro IDE’s spec-driven mode

Kiro IDE generates a requirements.md, design.md, and tasks.md from the user prompt in a planning panel, then iterates by re-prompting in “do” mode.

Capability	Kiro spec-driven	Core pack
Spec generated from prompt	✓	✓ (but assumptions are surfaced before spec bodies, then user signs off)
Test design before code	partial	✓ mandated (Testing Strategy in spec; `Tests:` per plan task)
Adversarial review of the diff against the spec	—	✓
Iteration cap and stasis detection	—	✓
Works outside Kiro	— (IDE-coupled)	✓ (every supported harness)
Boundaries-driven scope control	—	✓ (structural `Never do` + declined-pattern register)
Hook into editor lifecycle events	✓ (native to Kiro)	represented as `kiro-ide-hook`; the primitive isn’t declared in `adapter.toml` v0.5 yet

Kiro’s “do” mode is one-shot per task: if the generated code is wrong, the user re-prompts. The core pack’s loop iterates within the task — failing gates send you back to FIX, reviewer findings send you back to FIX, fingerprint stasis sends you to a human. The user isn’t the retry loop; the tool is.

Kiro is also IDE-coupled — the spec-driven mode only fires inside Kiro’s planning panel. The core pack ships through the adapter contract today (direct adapters for Claude Code, Codex, Copilot, Cursor, Gemini, and Kiro, the last in both its IDE and CLI forms) plus APM’s HookIntegrator for other targets that consume the APM compile target; install it once and the same loop runs wherever the install route reaches.

When the overhead isn’t worth it

The loop has cost. It pays back on non-trivial work and is friction on:

One-line edits, typo fixes, config tweaks.
Throwaway exploration and spikes (the work-loop skill explicitly excludes these).
Genuine one-off scripts that won’t be maintained.

For everything else — features, multi-file bug fixes, refactors, migrations, schema changes — the math is decisive. The work-loop skill itself enumerates its scope of application; the discipline applies forward-looking, not retroactively.

Where to read next

The pack catalogue — why core is the load-bearing pack and how the other packs compose against it.
Install routes — the four ways to install core and the install→adapt chain that closes on first session.
docs/CONVENTIONS.md § How we do non-trivial work — the contributor-side rationale, deeper than this page.
The token economy of the loop — what the loop wastes, what it spends on purpose, and why the cold reviewer is worth its cost.
The work-loop skill itself — the authoritative procedure. Loaded by the agent when a non-trivial task starts.