model

Model — Capture, Refine, Promote

The model skill is the main entry point for the user's stream of ideas. Every thought — from a one-line bug to a cross-context architectural shift — enters the system here and ends up as a task file in a bounded context.

The three actions

Decide which action applies based on what the user said and the current state of .agentheim/:

Action	When	What it does
CAPTURE	User is describing something new	Turns the idea into one or more task files. Places them in backlog/ if under-refined, or todo/ if the idea is already concrete enough to work on.
REFINE	User wants to work through an existing backlog item, OR the user invoked model with no new idea and backlog items exist	Picks a backlog task, deepens it via the orchestrator, splits it if needed, updates acceptance criteria and dependencies. May move to todo/ if it becomes ready.
PROMOTE	User explicitly wants a task ready for work	Moves a task from backlog/ to todo/, verifying it has enough detail to be picked up by a worker.

Disambiguating intent

• If the user gives a concrete idea ("add dark mode") → CAPTURE
• If the user says "let's model" / "what's in the backlog?" with nothing new → offer REFINE or CAPTURE-something-new
• If the user says "promote X" / "X is ready" → PROMOTE
• If ambiguous, ask once. Don't guess wrong and then have to undo.

Identifying which task the user means (REFINE / PROMOTE)

When the user references an existing task, support all of these:

• Exact id — books-007 → that exact task
• Numeric only — 007 → find task with that number across all BCs; if multiple BCs have the same number, list them and ask
• Keyword / fuzzy — password or reading session → match substring (case-insensitive) against task title and filename across backlog/ and todo/ of all BCs
• No argument — list all backlog (and todo, for PROMOTE context) tasks grouped by BC and let the user pick

When there are multiple matches, show a compact summary (id, title, status, BC) and ask which one — don't silently pick the first.

Before acting

Read the current state:

1. .agentheim/vision.md (for context — if missing, offer to run brainstorm first)
2. .agentheim/context-map.md (if exists)
3. .agentheim/contexts/*/README.md (to know what BCs exist and their language)
4. .agentheim/knowledge/index.md (top-level catalog — current BCs, recent ADRs, global state) — if missing, the project hasn't been indexed; surface this and continue
5. .agentheim/knowledge/protocol.md — read the first ~100 lines (newest entries are on top, so this gives recent activity). Skip if it doesn't exist yet.
6. .agentheim/contexts/*/backlog/*.md (to understand what's pending)
7. For CAPTURE only: once you've identified the candidate BC, scan .agentheim/contexts/<bc>/done/ for prior art on keywords/tags from the user's idea. See the "Prior art lookup" section.

If no bounded contexts exist yet, and the idea is non-trivial, propose running brainstorm first. Small ideas (bug fixes, copy changes) in a greenfield project can get a default contexts/main/ until real structure emerges.

Conversational modes

This skill adopts one of six modes during the conversational portions of CAPTURE and REFINE. The defaults differ by action:

• CAPTURE defaults to Facilitator — when the user (or a room) is volunteering a new idea, the scribe stance lets the human(s) drive while you capture and structure. Resist the urge to question or suggest until the idea has been articulated; CAPTURE is fundamentally about not getting in the way of incoming thought.
• REFINE defaults to Interrogator — refinement is where ambiguity gets cornered, so naive/critical questions are the right starting stance. The questioning patterns in the REFINE flow below are written for it.

The user can override the default at invocation ("capture this in challenger mode", "refine auth-003 as the storyteller") or switch mid-action ("switch to suggestor", "synthesize what we have"). Acknowledge a switch in one short line — e.g. → Suggestor. — and continue.

If the user says "change mode" / "switch mode" / "show me the modes" without naming a target, present an arrow-key picker via AskUserQuestion. The picker contract lives in references/modes.md under "Picker" — four modes in the menu (Interrogator, Suggestor, Challenger, Storyteller); Facilitator and Synthesizer are typed via the auto-"Other" option.

Full mode definitions and switching protocol live in references/modes.md. The full set:

• Interrogator — naive/critical questions one at a time. REFINE default.
• Suggestor — make smart assumptions and proposals; user accepts/rejects/refines. Useful for tiny captures or stuck refinement.
• Challenger — adversarial skeptic, presses on weak acceptance criteria or shaky scope. Use sparingly.
• Storyteller — narrate concrete scenarios with named characters to surface acceptance criteria from lived behavior.
• Facilitator — scribe stance; minimal interjection, captures and structures what the room says. CAPTURE default.
• Synthesizer — reflect back tensions and emergent themes across the backlog or a refinement thread. Best as a periodic switch-into.

PROMOTE is mostly mechanical (readiness check + file move) and runs the same regardless of mode. Task file format, ID conventions, the styleguide gate, protocol logging, and orchestrator handoffs are all mode-agnostic.

CAPTURE flow

1. Understand the idea. If the user gave one sentence, ask follow-ups to get: the why, the acceptance criteria, anything that constrains the solution. Don't ask more than 3-4 questions. For tiny things ("change button color"), one question may be enough, or none.

2. Route to the right bounded context. Match the idea's language to a BC's ubiquitous language. If it spans multiple BCs, say so and create a task in each (or a parent+child structure — see below). If it doesn't fit any BC and isn't trivial, that's a signal the context map needs revisiting — surface it.

   Infrastructure-flavored captures (anything about runtime, hosting, persistence configuration, secrets, observability, CI/CD, deployment, shared transport, base library choice) get a sharper routing rule:

   • Globally true — the concern applies across every BC, or stands on its own independent of any single BC. Examples: "switch from npm to pnpm", "add OpenTelemetry tracing", "rotate the production database password", "upgrade the base container image". → Capture in contexts/infrastructure/.
   • BC-local — the concern is only true for one BC. Examples: "the Library BC needs full-text search via Postgres tsvector", "Transcription should retry failed jobs in its own queue", "Auth's session store should move to Redis (no other BC uses Redis)". → Capture in the originating BC.

   The test: "if this BC didn't exist, would the change still need to happen?" — if yes, it's globally true and lands in infrastructure/; if no, it's BC-local and stays in the originating BC. When in genuine doubt (the change might go cross-cutting later but starts BC-local), prefer the originating BC — moving a task up to infrastructure/ later is cheaper than retroactively scoping out a global decision that turned out not to apply.

   Do not spawn new infra-flavored BCs. Captures that feel like they want their own monitoring/, secrets/, deploy/ BC are global infra concerns — they go in contexts/infrastructure/, not a new BC. If a genuinely new BC seems warranted from an infra capture, surface it for a brainstorm extension session rather than letting model spawn it. The exception is design-system/ — already a first-class BC for frontend infrastructure, and model may add tasks to it but does not create competing UI-infra BCs.

   If contexts/infrastructure/ doesn't exist (e.g., brainstorm was skipped), surface that — offer to run brainstorm in extension mode to add the infrastructure BC, or create the BC explicitly with a minimal README before capturing the task.

3. Prior-art lookup. Run the matcher described in "Backlink lookup" below against the target BC's INDEX.md (ADRs, research, done tasks) and the top-level index (global ADRs, cross-BC research). Surface every match score ≥ 2 to the user before writing the task file. For each prior-art hit (done task), give the user three outcomes: "yes related", "not relevant", or "this is the same task — exit CAPTURE, REFINE that one instead". Skip this step for trivial captures (single-line copy changes, obvious bug fixes).

4. Decide refinement level.

   • Under-refined → backlog/: The idea needs more thought, research, or breaking down before anyone could work on it.
   • Ready → todo/: The idea is small, well-understood, or already deeply discussed. A worker could pick it up and execute without ambiguity.

5. Delegate deep modeling if needed. For complex ideas (new feature, domain change, architectural impact), spawn the orchestrator agent with the idea and current state. It will route to tactical-modeler, strategic-modeler, architect, or researcher as appropriate, and come back with a refined task (or task set) plus any ADRs. For infrastructure-flavored captures, the orchestrator will typically route to architect first.

6. Write the task file(s). Include the user-confirmed related_adrs, related_research, prior_art from step 3 in the frontmatter. See task format below.

REFINE flow

1. If no specific backlog item was named, list the backlog across all contexts and ask which to refine. Prefer oldest-first or user-priority if flagged.

2. Read the task, its BC's README, and any related tasks (dependencies, siblings).

3. Interrogate the task. Questions typically needed:

   • Is the goal still correct?
   • What are the acceptance criteria?
   • What does this depend on? What depends on it?
   • Does this split into smaller tasks?
   • Does this reveal a decision that should become an ADR?

4. Delegate to the orchestrator for depth. Give it the task and the BC context. It will route to specialists.

5. Update the task file with refined content. If it splits, create child tasks and update depends_on. If a decision was made, write an ADR to .agentheim/knowledge/decisions/.

6. Promote if ready. If refinement made the task ready, move it to todo/.

PROMOTE flow

1. Find the task (user may name it by id or title, or describe it).

2. Check readiness:

   • Has an acceptance criteria section with at least one concrete criterion
   • Has a clear scope (not "improve the UX")
   • Dependencies are known and either met or tracked

3. If ready, move the file from backlog/ to todo/. Update its frontmatter status field.

4. If not ready, tell the user what's missing and offer to switch to the REFINE action on this task.

Task file format

Files live as contexts/<bc>/<status>/<id>-<slug>.md. Example: contexts/auth/backlog/auth-003-password-reset-flow.md.

---
id: auth-003
title: Password reset flow
status: backlog              # backlog | todo | doing | done
type: feature                # feature | bug | refactor | chore | spike | decision
context: auth
created: 2026-04-24
completed:                   # set by worker when done
commit:                      # git SHA set by worker when done
depends_on: []               # list of task ids
blocks: []                   # populated automatically by worker / refine
tags: []
related_adrs: []             # ADR ids (e.g., [0007]) — auto-populated by model at capture/refine; orchestrator appends ADRs it writes
related_research: []         # research slugs (e.g., [auth-tokens-2026-04-24]) — auto-populated by model from research-index
prior_art: []                # done task ids from same BC matching keyword/tags — auto-populated by model at capture
---

## Why
Why this exists. The user problem or domain pressure behind it.

## What
What the change is, in domain language.

## Acceptance criteria
- [ ] Concrete, testable outcomes.
- [ ] One bullet per criterion.

## Notes
Open questions, links to ADRs, references to research reports,
rough sketches — anything a worker or refiner would want.

ID convention

<bc-short>-<zero-padded-number>, e.g., auth-003, billing-017. Look at existing task files in the BC to determine the next number. Keep IDs stable — never renumber, even after deletions.

Decisions as tasks

When modeling surfaces a genuine architectural or domain decision that deserves its own treatment (rather than being an implementation detail of a feature), create a task with type: decision. Its output when worked is an ADR in .agentheim/knowledge/decisions/, not code. This lets decisions flow through the same backlog discipline as features.

Frontend tasks: styleguide gate

If the project has a contexts/design-system/ BC with a styleguide task (set up by brainstorm's architecture foundation step), every captured frontend / UI task in any BC must include the styleguide task in its depends_on. Read the BC's README before capturing — frontend-bearing BCs carry a note that points at the styleguide task id.

If you're capturing the project's first frontend task and no styleguide task exists, stop and surface that. Offer either:

• Running brainstorm in extension mode to add the foundation step, or
• Capturing a design-system-001-styleguide task explicitly, with this captured task depending on it.

Never promote a frontend task to todo/ ahead of the styleguide. The styleguide is reviewed with the user before any BC implements its UI — that's the gate.

Delegating to the orchestrator

The model skill itself does not do deep modeling — it routes. For anything non-trivial, hand off to the orchestrator agent with:

• The idea or task being refined
• The target BC's README (ubiquitous language)
• The vision.md
• The context map
• A clear question: "refine this task" or "decompose this idea into tasks" or "tell me what BCs this touches"

The orchestrator picks specialists. Respect its output and integrate it into the task files.

Research is fair game mid-model

If the user or the orchestrator hits an "we don't know enough about X" wall, kick off the research skill in parallel. Continue modeling what you can while research runs; fold its report into the task's Notes section when ready.

Backlink lookup (auto-populate task frontmatter)

The point is to stop workers arriving in isolation. Whenever a task is being written or updated, pre-compute its backlinks so the worker doesn't have to re-derive them.

When

• CAPTURE — after the BC is decided, before writing the task file.
• REFINE — after the orchestrator's specialist round, before writing the updated task file. Re-run from scratch each time (cheap; catches new ADRs/research that arrived since last refinement).

Inputs

• The candidate task's title, tags, What body, and target BC.
• The target BC's INDEX.md (already loaded in "Before acting") — has the per-BC ADR list, research list, done-task list.
• The top-level .agentheim/knowledge/index.md — has the global ADR list and cross-BC research list.

Matcher (cheap-first)

For each candidate artifact in the indexes:

1. Slug overlap — split the artifact's slug on - and the task's title on whitespace. Count words present in both (case-insensitive, ignore stopwords: the / a / an / of / for / and / to / in / on). Score = matches.
2. Tag overlap — if the artifact's source file has any of the task's tags in its frontmatter, +2 per shared tag.
3. Threshold — score ≥ 2 qualifies. Below that, do not auto-link.

Cap each list at 5 entries. If you have more than 5 candidates above threshold, take the highest-scored.

What to populate

• related_adrs: ADR ids from (BC-scoped ADRs + global ADRs) that scored ≥ 2.
• related_research: research slugs from (BC-scoped + cross-BC research) that scored ≥ 2.
• prior_art: done task ids in the same BC that scored ≥ 2. (CAPTURE only — REFINE may already have human-curated prior_art; only add new entries, never remove.)

Surface to user

For CAPTURE: before writing the task, show the user a one-line block per matched item ("Found prior art: auth-002 (Login session pinning, completed 2026-03-14). Read it?"). Three short outcomes the user can pick:

• "Yes, related" → keep in prior_art / related_*.
• "No, not relevant" → drop from the list.
• "This is the same — don't capture, update auth-002 instead" → exit CAPTURE, switch to REFINE on the prior task.

For tiny captures (single-line copy changes, trivial bug fixes), skip the matcher entirely. Don't burn context on lookups for change button color.

Bidirectional link maintenance

When the orchestrator writes an ADR scoped to this task during REFINE:

1. Add the ADR id to related_adrs in the task frontmatter.
2. Add the task id to related_tasks in the ADR frontmatter.

When work records ADRS_WRITTEN for a SUCCESS task, do the same — append the ADR id to that task's related_adrs and update the ADR's related_tasks. (See work/SKILL.md "Index updates" — the bidirectional ADR↔task link maintenance lives in the same step.)

Updating indexes

After writing or moving a task file, update the BC's INDEX.md so other skills (and you, on the next invocation) can find it without scanning directories. The template lives at references/index-template.md.

Where to update:

• CAPTURE writing to backlog/: insert under <!-- backlog-list:start --> in contexts/<bc>/INDEX.md. Increment Backlog count under <!-- task-counts:start -->.
• CAPTURE writing directly to todo/: insert under <!-- todo-list:start -->. Increment Todo count.
• PROMOTE (backlog → todo): remove the line from the backlog list, insert at the top of the todo list. Decrement Backlog, increment Todo.
• REFINE that splits a task: remove the parent line, insert child task lines. Update counts.

If the BC's INDEX.md doesn't exist yet, create it from references/index-template.md with the BC name filled in. Do not invent sections — only the templated markers are append targets.

What not to do:

• Do not edit the index across multiple BCs in one skill invocation unless a single capture genuinely lands in multiple BCs.
• Do not auto-rewrite the entire file — only insert/remove at the markers. Preserve any human-added prose elsewhere.
• Do not append duplicate entries — if the line is already present (same task-id), skip.

If a brand-new BC is being created during CAPTURE (rare — model normally does not create BCs; that's brainstorm's job), also insert under <!-- bc-list:start --> in .agentheim/knowledge/index.md.

Protocol logging

After each action — CAPTURE, REFINE, or PROMOTE — prepend an entry to .agentheim/knowledge/protocol.md. If protocol.md doesn't exist, create it with:

# Protocol

Chronological log of everything that happens in this project.
Newest entries on top.

---

Then prepend the appropriate entry right after the --- on line 4:

## YYYY-MM-DD HH:MM -- Model / Captured: <task-id> - [title]

**Type:** Model / Capture
**BC:** <bc-name>
**Filed to:** backlog | todo
**Summary:** [1-2 sentences on what the idea is]

---

## YYYY-MM-DD HH:MM -- Model / Refined: <task-id> - [title]

**Type:** Model / Refine
**BC:** <bc-name>
**Status after:** backlog | todo
**Summary:** [what was clarified, added, or split]
**Split into:** [list of new task ids, if split]
**ADRs written:** [list of ADR ids, if any]

---

## YYYY-MM-DD HH:MM -- Model / Promoted: <task-id> - [title]

**Type:** Model / Promote
**BC:** <bc-name>
**From → To:** backlog → todo

---

If the action is non-trivial (multiple tasks created from one capture, refinement that produced ADRs, batch promotion), one entry per "thing the user asked for" is enough — don't prepend five entries for a single conversation turn.