ingest

---

name: ingest description: "Entry point for new or resumed work. Researches and scopes new tasks; validates and resumes handoff/checkpoint manifests. Triggers: start, begin, do, implement, build, fix, create, resume, continue." user-invocable: true allowed-tools: Read, Bash, Grep, Glob, Task, WebSearch, WebFetch kernel: kind: workflow version: 1 side_effects: writes_repo confirmation: none consumes: - kernel.handoff/v1 - kernel.checkpoint/v1

Authority order (highest wins) — a manifest is a map, not the territory:

1. live verified repository state
2. explicit current user instruction
3. handoff or checkpoint manifest
4. chronicle
5. inferred conversation history

<skill_load> always: skills/debug/SKILL.md on_classify: bug: skills/debug/SKILL.md feature: skills/build/SKILL.md, skills/architecture/SKILL.md refactor: skills/architecture/SKILL.md review: skills/review/SKILL.md on_domain: frontend: skills/frontend/SKILL.md app: skills/app-dev/SKILL.md on_tier: 2+: skills/orchestration/SKILL.md reference: skills/build/reference/build-research.md </skill_load>

<on_start>

agentdb read-start
ls _meta/research/  # check prior work

Load /kernel:quality, /kernel:testing, /kernel:git immediately. After classify: load task-specific skills above. Do NOT proceed without loading them. After scope: if tier 2+, load /kernel:orchestration. If any domain detected (API, auth, frontend, backend): load domain skills. </on_start>

Search before asking: Glob, Grep, common paths.

<ask_user> Use AskUserQuestion when: classification is ambiguous (could be bug or feature, refactor or rewrite) Ask: "This looks like {type_A} but could be {type_B}. Which framing fits your intent?" Options: type_A, type_B, or clarify </ask_user>

After classify: load matching workflow from workflows/{type}.md if it exists. Workflow steps guide the phase sequence. Human confirms at each step (ingest mode).

1. Discover: explicit path if the user gave one, else:

   "$KM" latest        # newest across _meta/checkpoints/ + _meta/handoffs/
   

   Legacy markdown handoffs (_meta/handoffs/*.md) remain readable this release: parse goal/decisions/next-steps from prose, note "legacy handoff (deprecated, no validation/divergence/budget)" and suggest regenerating as JSON. Removal path: docs/MIGRATION-8.md.

2. Validate — a manifest that does not validate is not resumed:

   "$KM" validate <manifest>     # exit 2 (no parser) on a sealed manifest = STOP
   

3. Divergence — live state wins over manifest claims:

   "$KM" divergence <manifest> --json
   

   Typed divergence events apply workflow.invalidation_rules[].when and return recalculated phase statuses. Never trust an inherited phase whose inputs changed.

4. Preflight: run "$KM" preflight <manifest>. Canonical state permits only typed current-branch, path-exists, and allowlisted argv checks; raw shell is invalid.

5. Compile bounded context — read the bundle, not the raw tree:

   "$KM" compile <manifest> --bundle-out /tmp/resume-bundle.md --receipt-out _meta/reports/receipt-{date}.json
   

   The receipt (kernel.context-receipt/v1) reports estimated tokens per layer and status: within_budget → proceed · target_exceeded → drop optional selectors, proceed with a note · maximum_exceeded (exit 3) → STOP, report the receipt, ask before loading anything.

6. Activate the policy (arms the guard-context hook for sealed/bounded):

   "$KM" activate <manifest>
   

   sealed: forbidden globs are hook-BLOCKED; do not fight the hook — amend the manifest if access is genuinely needed. bounded: extra loads are allowed but ledgered; justify each in the receipt's loads_beyond_manifest.

7. Resume at the declared position:

   "$KM" resume <manifest>    # entry_phase / entrypoint / next_operation
   

   Skip inherited phases (already verified by divergence), execute required ones. Honor execution.stop_conditions and emit checkpoints at execution.checkpoints.

8. Complete: when outputs.required are verified,

   "$KM" deactivate --receipt _meta/reports/receipt-{date}.json
   

   Deactivate projects the receipt into AgentDB's observational context graph (shadow telemetry). Then outputs.completion (usually agentdb write-end), which records session outcome on that graph row when did/blocked are present.

Optional advisory (never auto-loads): bash agentdb graph-suggest {task_type}

Output: "Resuming {manifest}: {goal}. Entry: {entry_phase}. Receipt: {total_estimated_tokens} tokens ({status})."

tier 2+: spawn kernel:researcher

<ask_user> Use AskUserQuestion when: research reveals multiple viable approaches or unknown risks Ask: "Research found {N} approaches. Proceed with {recommended}, or explore alternatives?" Options: proceed, explore alternatives, skip research </ask_user>

<ask_user> Use AskUserQuestion when: tier classification is borderline (e.g., 2-3 files but complex coupling) Ask: "Scoped to {N} files — tier {X}. Confirm tier, or should I treat as tier {X+1}?" Options: confirm tier {X}, bump to tier {X+1}

When the request itself is underspecified (any GOAL/CONSTRAINTS/INPUTS/OUTPUTS/DONE-WHEN field unknowable), run the structured interview from skills/build/SKILL.md "The interview" BEFORE scoping: batched AskUserQuestion rounds over intent, implementation forks, veto-risk UX, edge behavior, and tradeoffs. Bounded choices only; open-ended direction stays prose. Answers are quoted into the spec/commission so each decision carries its authority. </ask_user>

done_when:

• observable outcome 1
• edge case handled

evals: code_grader: PASS/FAIL command regression: existing tests pass

Specification prompts with exact code achieve 100% success across all scopes (modelmind H002/H003, 0.95 confidence). Contract framing ("achieve X under constraint Y") leaves interpretation gaps that agents fill incorrectly.

Before handing to surgeon (tier 2+) or starting execution (tier 1), the spec must answer:

• Exact file paths: every file that will change, by absolute path
• Exact symbols: every function/class/type to add/modify/remove, by name
• Exact code snippets for non-trivial logic (not pseudocode, not "implement X")
• Exact configs/SQL/schemas: if the change touches them, paste the literal block
• Exact verification commands: how a fresh agent confirms success without asking

Litmus test: could a fresh agent in a new session execute this spec with zero follow-up questions? If no, the spec is incomplete. Return to step 3 (scope) or step 4 (tests) and fill the gap before proceeding.

Anti-pattern: shipping a contract that says "the surgeon will figure out X." The surgeon will figure out X by guessing, and the guess will be wrong.

<ask_user> Use AskUserQuestion when: the spec has a known gap and you need the user to decide which exact path to take (rather than letting the surgeon guess). Ask: "Spec gap at {location}: option A = {exact}, option B = {exact}. Which?" Options: option A, option B, other </ask_user>

<tier_2_plus> rule: you do NOT write code

1. /kernel:tearitapart — review plan before implementation
2. agentdb contract '{"goal":"X","files":["Y"],"tier":N}' 2b. If non-local profile: _gh_create_issue with contract goal + tier label
3. git checkout -b {type}/{name}
4. Spawn surgeon
5. Wait for checkpoint
6. (tier 3) spawn adversary
7. /kernel:validate → verify evals
8. /kernel:review — self-review before PR </tier_2_plus>

agentdb learn pattern "{what worked}" "{evidence}" agentdb learn failure "{what broke}" "{evidence}" Update _meta/research/ if new findings. Suggest /kernel:retrospective if 5+ learnings accumulated since last synthesis. Long task still running? Emit /kernel:checkpoint at natural boundaries instead of letting context accumulate (EXP-L21).

<output_format> task: one sentence | type: bug|feature|refactor | tier: 1|2|3 | status: researching|scoping|testing|executing|complete </output_format>

<hard_stops> ask_file_location→search | code_without_research→step2 | code_without_tests→step4 | code_tier2+→surgeon | skip_agentdb→go_back </hard_stops>