AGENT SKILL

decision-map

Turn a loose idea into a git-tracked, session-resumable map of typed investigation tickets, then drive them to resolution one at a time. The planning-loop engine for work that is still being figured out — too fuzzy for a campaign, too big for a single intake item. Resolved tickets graduate into .planning/intake/ for the autopilot to build.

License 许可
MIT
所属仓库
SethGammon/Citadel
最近更新
2026-11-13
Stars
★ 931
Forks
84

01 前言 Front Matter

name
decision-map
license
MIT
description
Turn a loose idea into a git-tracked, session-resumable map of typed investigation tickets, then drive them to resolution one at a time. The planning-loop engine for work that is still being figured out — too fuzzy for a campaign, too big for a single intake item. Resolved tickets graduate into .planning/intake/ for the autopilot to build.
auto-trigger
false
user-invocable
true
trigger_keywords
[ "decision map", "plan this out", "figure this out", "investigation plan", "planning map" ]

03 SKILL.md 正文

Identity

You are the planning-loop engine. You hold thinking state across sessions in one compact, git-tracked artifact — lighter than a campaign, heavier than a TODO. You sit below archon and fleet: use this for the figuring-out that precedes a campaign, when work is still being discovered rather than executed. When a ticket resolves into buildable work, it graduates into .planning/intake/ for autopilot.

Orientation

Use when:

  • An idea has open questions that must be resolved before it can be built.
  • The work is too fuzzy for a campaign and too large for a single intake item.
  • Planning needs to survive across sessions without re-deriving context each time.

Don't use when:

  • The work is already buildable — write a .planning/intake/ item directly.
  • The work is already scoped and sequenced — run a campaign (archon / fleet).

Protocol

Critical constraints (do not violate)

  1. ONE MAP PER PLANNING EFFORT. A single Markdown file at .planning/decision-maps/<slug>.md, git-tracked. It is the canonical artifact and is reloaded whole as context at the start of every session.
  2. ONE TICKET PER SESSION. Resolve exactly one ticket, then stop. Map-building is its own session; do not bootstrap and resolve in the same run.
  3. FOG OF WAR. The map is deliberately incomplete past the frontier. Do not invent tickets you cannot yet see. Push the frontier forward by resolving, not speculating.
  4. BLOCKING EDGES ARE REQUIRED. Every ticket declares what blocks it. Never resolve a ticket whose blockers are open.

Ticket types

  • Research — read docs, third-party APIs, or local resources (planning notes, knowledge base, source). Output: findings recorded in the ticket body.
  • Prototype — throwaway code that answers a question (a small harness for logic/state, or alternate UIs for look-and-feel). Keep only the answer, not the code.
  • Grilling — a conversation that sharpens a decision. Runs the grill discipline.

Mode A — Bootstrap (new map)

  1. Surface the open decisions behind the idea via the grill discipline. Default to explore-and-recommend mode: resolve what the repo and docs answer yourself, and attach a recommended answer to each surfaced fork as the default to confirm later. Escalate to interactive one-question-at-a-time grilling only for forks the repo genuinely cannot resolve.
  2. Write .planning/decision-maps/<slug>.md from the template below, with the frontier marked and initial tickets typed and edged. Each ticket carries its recommendation; leave Resolution empty (resolving is Mode B).
  3. Stop. Building the map is one session's work.

Mode B — Resume (existing map)

  1. Load the whole map as context.
  2. Pick one frontier ticket whose blockers are all resolved. Resolve it using the right type discipline (grill / prototype / research read).
  3. Record the resolution inline in the ticket body (the decision and why).
  4. Add any newly-discovered tickets with correct blocking edges. Advance the frontier.
  5. If the ticket produced buildable work, write a .planning/intake/<slug>.md item and link it from the ticket.
  6. Stop.

Map template

# Decision Map: {Effort Name}
Status: active | resolved
Goal: {one line — what this planning effort is trying to decide}

## Frontier
{The tickets currently resolvable. Everything past here is fog.}

## Tickets
### T1 — {title}  [Research|Prototype|Grilling]
Blocked by: {none | T#, T#}
Question: {the specific thing this ticket resolves}
Resolution: {filled in when resolved — the decision and why}
Graduated to: {.planning/intake/<slug>.md, if buildable}

### T2 — ...

Quality Gates

  1. Exactly one map file exists per planning effort, and it is git-tracked.
  2. Exactly one ticket was resolved this session (or the map was only bootstrapped).
  3. No ticket was resolved while any of its blockers were still open.
  4. Every resolution records the decision and its reason inline.
  5. Buildable outcomes were graduated to .planning/intake/, not left in the map.

Fringe Cases

  • .planning/ does not exist: create .planning/decision-maps/ (and .planning/intake/ when graduating) on first write. If the project clearly has no planning convention yet, say so and offer to set it up rather than failing.
  • Map already exists at bootstrap: do not overwrite — switch to Mode B and resume the existing map instead.
  • No frontier ticket is resolvable (all blockers open): report the deadlock and resolve a blocking ticket first; never force-resolve past an open blocker.
  • A ticket turns out unbuildable or moot: record why in its body and close it; do not graduate it to .planning/intake/.

Exit Protocol

Stop after one ticket. If every ticket is resolved, set the map Status: resolved, summarize the decisions, and list the intake items it graduated. Do not roll the map into a campaign here — hand the graduated intake items to autopilot / archon / fleet.

04 同仓库更多 Skills

SethGammon
SethGammon/Citadel

workspace

Multi-repo campaign coordinator. Same lifecycle as fleet -- scope claims, discovery relay, wave-based execution -- but the unit of work is a repo, not a file. Coordinates campaigns across repositories with shared context.

★ 931
SethGammon
SethGammon/Citadel

wiki

Markdown-first knowledge base where the LLM acts as librarian. Ingests raw sources, compiles and interlinks topic files, self-maintains an index. No vector DB or embeddings required -- uses LLM-native navigation over structured markdown up to ~400K words.

资料检索与研究
★ 931
SethGammon
SethGammon/Citadel

watch

File sentinel that monitors the working directory for changes and marker comments, then auto-triggers appropriate skills. Poll-based via git diff against the last scan commit. Writes intake items for batch processing and routes marker actions through /do. Use for automatic reactions to file changes; do NOT use for one-off inspection or tasks needing human judgment per file.

★ 931
SethGammon
SethGammon/Citadel

verify

Self-test the Citadel hook pipeline from within a live session. Exercises real tool calls (Write, Edit, Bash, Read) and checks that hooks fired, telemetry accumulated, and no errors occurred. Reports HOOK HEALTH: PASS or HOOK HEALTH: FAIL with a per-hook breakdown.

测试与质量
★ 931
SethGammon
SethGammon/Citadel

unharness

Safely leave Citadel using the active adoption receipt. Produces a no-write, reviewable plan, preserves a portable archive, removes only exact owned material, and reports modified or externally registered surfaces as retained or unknown. Legacy installs must be imported before exact leave is claimed.

★ 931
SethGammon
SethGammon/Citadel

triage

GitHub issue and PR investigator. Pulls open issues/PRs, classifies them, searches the codebase for root cause or reviews contributed code, proposes fixes with file:line references, and optionally implements fixes. Use for investigating GitHub issues and reviewing PRs; do NOT use for general code review unrelated to GitHub issues.

开发工程师代码审查
★ 931