repo

core

Spec → shipped code. Supervised.

18 skills2 human gates25–45 min/session

Install this pack Read the reference

From scoped work to a reviewed merge

The contract

Use it when: You're implementing a feature, fixing a bug, or changing an existing repo.
You type: Start work on adding export retention controls.
You provide: The task and its important constraints.
You receive: An agreed plan, a checked implementation, review findings, and a merge decision.

Where you decide

The agent pauses at these points. You choose whether to continue, redirect, or stop.

Approve the planDecision 1 of 2 Merge the reviewed changeDecision 2 of 2

What changes when you install this

After installing core, work-intake becomes the neutral front door for raw or ambiguous start, remember, status, refresh, and intake-safety requests. Direct artifact requests go to their owner: intake-intent admits repository intents, author-delivery-brief creates or continues coordination briefs, and new-spec owns one independently shippable feature. Before construction, those callers may use shaping-reviewer to test contract scope and observability; it is separate from the later adversarial, security, and quality code-review lenses. Approved specs then move through work-loop: plan → execute → verify → independently grounded review. Stable brief/spec/plan authoring gates may capture reusable supporting practice through project-knowledge, while Draft work, reviewer scratch, findings, and normative artifact content remain untouched. After delivery, close-work verifies durable context and previews disposition without automatic deletion. The loop cannot self-certify: it surfaces plan, merge, freshness, and exact mutation decisions to you.

The journey

Say this	What happens
`work-intake`	Route a start, remember, status, or refresh request into durable state
`workspace-status`	Orient — what’s ready, blocked, and done
`work-loop`	Plan → execute → gates → bounded evidence-assisted review → merge
`close-work`	Pause or close delivery work after verifying lasting context and exact authority
`bug-fix`	Diagnose and fix a specific bug
`intake-intent`	Create or admit a repository intent
`author-delivery-brief create\|continue`	Create a coordination brief or continue one into confirmed spec slices
`new-spec`	Author a spec directly, without the brief layer
`project-knowledge`	Capture, distill, and explicitly enquire over committed project lessons

1. Orient — every session

Type workspace-status to see what’s ready to start, what’s blocked, and what shipped last session.

● sprint-8/data-export     ready    spec approved · 3 tasks
⚠ sprint-8/auth-refresh    blocked  needs spec/api-contract
✓ sprint-7/payment-ui      done     shipped 2026-07-25

Output: queue state — ready items, blocked items with reason, recent completions.
State: read-only

2. Route the work

Describe the work to work-intake. The agent selects one artifact route from the content, writes the artifact, then registers its lifecycle state. A multi-feature outcome becomes a Draft brief; one independently shippable change continues to new-spec; an opportunity can remain a non-dispatchable intent.

If the request includes a validated shaping handoff, work-intake first admits the bounded context and resolves its semantic destination. A delivery contract continues through new-spec; a delivery brief continues through author-delivery-brief continue. External locators remain opaque, and every existing approval gate remains in place. Without the optional handoff, this stage is unchanged.

  artifact    docs/product/briefs/data-export.md
  membership  draft · non-dispatchable
  processor   author-delivery-brief create

Output: docs/product/briefs/data-export.md — review the brief before it enters the work loop.
State: draft

Optional compatibility path — migrate one legacy entry

When status reports legacy_entry, review its exact source slice and candidate routes. A person authors the closed selection; repair-plan remains read-only. Apply or rollback only with the repository migration policy and one fresh, single-use confirmation bound to the exact operation.

You decide: the target artifact, lifecycle membership, provenance, and whether to apply or roll back.
Output: a canonical workspace entry or the restored exact legacy slice, plus the durable .workspace-migrations.json recovery record.
State: confirmed-write

Optional return path — refresh tracked work

For an existing tracker-origin artifact, ask work-intake to compare the registered source revision. You receive a field-level delta before anything changes. Approve each local decision; if you later request a tracker comment, trace link, pull-request link, display-status change, or closure, confirm that one remote mutation separately.

You decide: each local field outcome, then each exact remote mutation.
Output: updated local authority and revision mirror, plus a pending, failed, or succeeded receipt for any confirmed remote action.
State: confirmed-write

3. Make one slice ready

Run author-delivery-brief continue docs/product/briefs/data-export.md. After the brief passes its Ready gate, choose one independently shippable slice. new-spec writes its Approved spec and sibling plan; the brief itself never enters work-loop.

brief: Ready
slice: streaming-csv-export
  spec  docs/specs/data-export/spec.md
  plan  docs/specs/data-export/plan.md

  Problem  Streaming export crashes above 50k rows.
  User     Engineer shipping the bulk-export feature.
  Success  1M rows under 2 GB peak RSS.

  Assumption: streaming CSV is acceptable; XLSX is deferred.

approved: spec and plan

You decide: approve the brief, slice, spec, and plan before implementation.
Output: docs/specs/data-export/spec.md + plan.md — the executable contract and plan.
State: confirmed-write

4. Execute

Type work-loop docs/specs/data-export/spec.md. The agent implements, runs lint / typecheck / tests after each logical change, and hands the diff to adversarial-reviewer in a fresh session.

  ● Lint          ok
  ● Typecheck     ok
  ● Tests  246/246 ok
  ● Review        1 blocker → fixed → clean

Output: code and tests across multiple files — too many to enumerate individually. Review the PR diff.
State: draft

5. Merge

The agent opens the PR. Read the description before the diff — it tells you what the agent decided when it had choices, and what was deferred.

You decide: merge, redirect, or defer.
Output: a merged change.
State: confirmed-write

6. Preserve reusable lessons

At semantic gates, the workflow may hand its semantic judgment to the project-knowledge producer profile. That journal event is durable and pending, but it is not a query source. Later --distill runs reconcile pending observations into reviewed topic proposals, route them to stronger artifacts, or record bounded terminal dispositions.

Use project-knowledge --enquire only when you need a declared competency question answered from committed active topics. Enquiry reads one committed Git snapshot, verifies freshness sources for consequential use, and returns bounded evidence with a receipt. It does not read scratch, pending journals, legacy rows, or working-tree-only topics, and retrieved text cannot approve changes, select tools, widen scope, or become evidence by writing itself back.

Scratch before capture can be lost if the workflow or worktree disappears. Retention and compaction are intentionally deferred to a future whole-partition policy; this slice has no per-event deletion path.

Output: committed topic evidence and receipts for explicit competency questions.
State: read-only

7. Close or pause delivery work

Use close-work after delivery, abandonment, or supersession. It consumes the bounded work-loop evidence handoff, verifies that lasting facts reached their established owners, and asks you to confirm that affected human-readable surfaces remain coherent as wholes. Tests stay capability proof; they do not become the sole owner of intent, rationale, user promises, ownership, or operations.

For resumable work, pause writes only a reference overlay to an existing writable coordination surface and keeps Ready or Implementing status. For closeout, the workflow shows blockers and one of six disposition intents. It does not delete, rewrite Git history, start the 30-day clock, or hide cooling records.

You decide: freshness, disposition intent, and each exact persisted effect.
Output: bounded closeout evidence, owned next actions, and no mutation unless a fresh authority-bound confirmation is accepted.
State: confirmed-write

Autonomous dispatch

For control-harness use — sessions driven programmatically without a human watching each turn — the two human touches collapse to gate responses via ACP. The harness calls workspace_status() to read the queue, dispatches an item, then waits for an elicitation/create request that arrives when the work-loop reaches a gate — routes the gate question to a human channel, and responds to the pending ACP elicitation request with the human’s answer to unblock the gate.

The work-loop runs the same gates; the harness is what answers them instead of a person at a keyboard.

→ Run a headless session with workspace-mcp

What good output looks like

YouStart work on adding export filters without changing the existing API route.
AgentI routed this to the approved spec. The plan changes the query contract, handler, and emitted API tests. It adds no dependency or migration.
YouApprove the plan.
AgentImplemented. Focused tests, type checking, lint, and the full suite pass. The emitted contract exposes filters and preserves existing defaults.
Independent reviewerClean — ready to commit.
AgentThe reviewed change is ready for your merge decision.

Human gates

For each gate, everything you need to make a confident decision.

Approve the plan
Trigger
Before work-loop begins execution — after the agent writes the trio and risk-trigger assessment
Time
5–10 minutes
What to check, good, bad, consequence
What to check
Is the Trio complete? (problem, user, success criteria — each in one sentence)
Do the stated risk triggers match the actual change? (a one-file auth change is full-mode; a familiar two-file change can be light)
Is the plan scoped to what was asked — nothing more?
Are the assumption surfacings plausible, not defensive?
What good looks like
A bounded plan with a clear trio, no scope creep, correct risk-trigger assessment, and plausible assumptions.
What bad looks like
A plan that extends the scope of the request, missing risk triggers that should have fired, or a trio that doesn't name a specific user.
Consequence of skipping
If you approve a bad plan, the agent executes it faithfully. The cost of a bad plan is the cost of a full loop iteration — plan approval is the cheapest gate.
Merge the reviewed change
Trigger
After all mechanical gates pass and adversarial review is clean
Time
10–20 minutes
What to check, good, bad, consequence
What to check
Is adversarial review marked clean? (Re-run if in doubt — it's fast.)
Does the implementation match the spec? If not, did the spec update?
Are the tests testing behavior, not implementation details?
Is there anything in the diff that wasn't in the plan?
What good looks like
Green gates, clean adversarial review, spec and implementation aligned, no unexplained diff.
What bad looks like
Adversarial reviewer flagged a Blocker and you merged anyway. Or the spec drifted from the implementation without an update.
Consequence of skipping
This is the last line of defense before the build loop output goes to release. A bad merge is harder to undo than a bad plan.

Typical session

Agent turns: 8–12
Human gates: 2
Wall-clock time: 25–45 min

Install

agentbundle install --pack core

Skills in this pack

work-intake
Routes start, remember, status, and refresh requests into canonical artifacts and workspace lifecycle state before dispatch.
work-loop2 gates
The build loop. Plans, executes, verifies, and reviews; spec-approved and plan-locked may capture reusable supporting practice.
close-work1 gate
Pauses or closes delivery work, verifies durable semantic owners and whole-surface freshness, and recommends disposition without granting automatic mutation.
new-spec1 gate
Authors a Draft spec and Drafting plan before the build loop starts. These are explicit project-knowledge non-gates.
bug-fix1 gate
Diagnoses and fixes a bug with a targeted root-cause analysis before writing a line of code.
contract-acquisition
Grounds agent code against an unfamiliar API or library contract before implementation — prevents guessed signatures.
intake-intent1 gate
Creates or admits the minimum repository intent without requiring Product Engineering fields.
init-project1 gate
Initializes a new project with the full agent-ready-repo structure, conventions, and AGENTS.md.
adapt-to-project1 gate
Adapts the agent-ready-repo conventions to an existing project's idioms and structure — the on-ramp for brownfield repos.
author-delivery-brief1 gate
Creates a Draft coordination brief from raw input or continues an existing brief through readiness and confirmed spec slices.
author-brief
Deprecated compatibility alias for author-delivery-brief create.
receive-brief
Deprecated compatibility alias for author-delivery-brief continue.
capture-work
Compatibility alias that forwards equivalent requests to work-intake; new guidance uses work-intake directly.
workspace-status
Reads workspace.toml, surfaces canonical and legacy findings, and provides the explicit plan/apply/rollback repair surface for reviewed migrations.
project-knowledge
Captures, distills, and enquires over committed project knowledge through one progressive skill. Capture writes observations; distill proposes topic changes; enquire reads active committed topics.
operational-safety
Provides failure-mode-keyed operational safety checklists for the work-loop's quality-engineer reviewer. Loaded selectively for infra and destructive work — not invoked directly.
security-checklists
Provides boundary-keyed security checklists for the security-reviewer. The work-loop loads only the boundary-matching modules — not invoked directly.
security-checklists-reference
Provides a read-only reference view of the security checklist library. Normal security reviews use security-checklists.