olliecrow/prime

Prime

Overview

Prime the conversation before substantial execution so work stays proactive, autonomous, and completion-driven across any project.

Start with a fast familiarization sweep of docs and current repo state, then set a clear session operating contract, activate recurring loops (organise-docs, git-commit, cleanup, verification), and keep enforcing the contract for the rest of the conversation.

Treat organise-docs and git-commit as an always-on cadence throughout the conversation: after each substantial chunk, promote durable knowledge into docs/, and checkpoint with a small commit once verification is green.

Multi-agent collaboration

• Default to using subagents when they are likely to improve speed, quality, confidence, or keep the main context clean.
• Use subagents to widen coverage, dig deeper on one thread, get a fresh second opinion, or keep the main thread clean while side work runs.
• Split work into clear packets with owners, inputs, acceptance checks, and a synthesis step when parallelizing.
• Keep the main agent focused on synthesis, unblockers, and the next critical-path step; let subagents handle bounded side work that can run in parallel.
• Use single-agent execution only when scope is small or coordination overhead outweighs gains.

Proactive autonomy and knowledge compounding

• Be proactive: immediately take the next highest-value in-scope action when it is clear.
• Default to autonomous execution: do not pause for confirmation between normal in-scope steps.
• Request user input only when absolutely necessary: ambiguous requirements, material risk tradeoffs, missing required data/access, or destructive/irreversible actions outside policy.
• If blocked by command/tool/env failures, attempt high-confidence fallbacks autonomously before escalating (for example rg -> find/grep, python -> python3, alternate repo-native scripts).
• When the workflow uses plan/, ensure required plan directories exist before reading/writing them (create when edits are allowed; otherwise use an in-memory fallback and call it out).
• Treat transient external failures (network/SSH/remote APIs/timeouts) as retryable by default: run bounded retries with backoff and capture failure evidence before concluding blocked.
• On repeated invocations for the same objective, resume from prior findings/artifacts and prioritize net-new progress over rerunning identical work unless verification requires reruns.
• Drive work to complete outcomes with verification, not partial handoffs.
• Treat iterative execution as the default for non-trivial work; run adaptive loop passes until completion criteria are met.
• Prefer a repeating mini-cycle throughout the conversation: work -> verify -> organise-docs -> git-commit (if eligible) -> continue.
• Compound knowledge aggressively over time: capture notes/findings continuously, then promote durable learnings/decisions into long-lived docs as soon as confidence is high.
• Run organise-docs frequently during execution to capture durable decisions and learnings, not only at the end.
• Create small checkpoint commits frequently with git-commit when changes are commit-eligible, checks are green, and repo policy permits commits.
• Never squash commits; always use merge commits when integrating branches.
• Prefer simplification over added complexity: aggressively remove bloat, redundancy, and over-engineering while preserving correctness.
• When you touch code, leave the touched area in a better state than you found it: clearer, simpler, tidier, and at least as performant unless the task requires an explicit trade-off.
• Before finishing any non-trivial task or pass, run at least one explicit consolidation pass across the touched code, docs, notes, tests, and configs.
• Use that pass to merge toward one clear source of truth, remove stale or duplicate material, and resolve contradictions before you declare the work complete.
• Do this by default as part of normal completion, even when the user did not explicitly ask for cleanup, consolidation, or contradiction resolution.
• Use simple, plain English in user messages, docs, notes, reports, code comments, and other explanatory writing. Avoid jargon, fancy wording, and complex phrasing. When a technical term is needed for correctness, explain it in simple words the first time. Default to short user-facing responses. Think about what the user most wants to know, and lead with that. Do not dump every detail by default. Always include important changes, blockers, verification gaps, and any important assumptions, nuances, principles, or decisions that shaped the work. Add more detail only when the user asks for it or when uncertainty or risk makes it necessary.
• Compound knowledge continuously: keep docs/ accurate and up to date, and promote durable learnings and decisions from work into docs.

Long-task checkpoint cadence

• For any non-trivial task (including long efforts), run recurring checkpoint cycles instead of waiting for a single end-of-task wrap-up.
• At each meaningful milestone with commit-eligible changes, and at least once per major phase, invoke git-commit to create a small logical checkpoint commit once relevant checks are green and repo policy permits commits.
• At the same cadence, invoke organise-docs whenever durable learnings/decisions appear, and prune stale plan/ scratch artifacts.
• If either checkpoint is blocked (for example failing checks or low-confidence documentation), resolve or record the blocker immediately and retry before expanding scope.

Terminal state contract (must follow)

The skill is complete only when all of the following are true:

• Objective completion: the user-requested outcome is achieved, or explicitly marked blocked with concrete blocker evidence.
• Workflow completion: every required workflow step is resolved as done, blocked, or not-applicable, with brief evidence or rationale.
• Step-level terminal completion: each numbered subtask must have explicit completion evidence (artifact, command output, or written rationale) before advancing.
• Verification completion: required checks/validations for this skill are executed, or any unavailable checks are explicitly called out with impact.
• Findings completion (where applicable): report only evidence-backed findings; if no high-confidence critical findings are present, explicitly state that.
• Loop completion: no actionable in-scope next step remains under the current objective.

Stop only after this terminal contract is satisfied; otherwise continue iterating.

Terminal state examples (adapt to skill)

• done: requested outcome is delivered and required checks are completed (for example expected artifact/report produced and required validation command(s) passed).
• blocked: progress cannot continue after bounded retries because of a concrete dependency or access issue; blocker evidence and exact unblock action are reported.
• not-applicable: an optional step is explicitly skipped with reason (for example no remote configured, so push step is marked not-applicable).

Aggressive knowledge compounding (must follow)

• Keep a running findings log during execution; do not rely on end-of-task memory reconstruction.
• Route notes by durability:
  • short-lived scratch notes, experiments, and command artifacts -> plan/
  • durable principles, decisions, invariants, and high-value lessons -> docs/
• Promote durable knowledge early and repeatedly, not only in final summaries.
• Update existing docs first when possible; avoid fragmentation and duplication, and prefer one canonical home per topic.
• When a non-obvious decision is made, capture Decision, Context, Rationale, Trade-offs, and Enforcement in the most local durable place.
• Prune stale scratch artifacts after promotion so plan/ stays navigable.

Priming outcomes

After priming, the session should have all of the following:

• A clear operating contract for autonomy, escalation boundaries, and completion criteria.
• A concise familiarity snapshot of the project/repo, based on available docs and current git/worktree state.
• A concrete execution loop for the current objective (adapted, not rigid).
• Explicit recurring hygiene loops:
  • documentation compounding loop (organise-docs)
  • checkpoint commit loop (git-commit)
  • cleanup loop (cleanup style passes)
  • verification loop (verify / targeted tests / battletest when risk warrants)
• A startup checklist showing what was confirmed and what assumptions are active.
• A live note-routing setup for this session:
  • ephemeral working notes in plan/current/ (or in-memory fallback when plan writes are unavailable)
  • durable decisions/findings promoted into docs/ during execution

Workflow

1) Run startup preflight

• Confirm working directory/repo root and read project instructions (for example AGENTS.md, relevant docs/decision records).
• Confirm current git state (git status -sb) and identify whether the tree is clean or dirty.
• Confirm available tools and immediate constraints needed for likely work.

2) Run a familiarization sweep

• Discover and read high-signal docs that exist in the repo (for example README*, AGENTS*, CLAUDE*, docs/, architecture/runbook files, and relevant decision records).
• Build a concise project-state snapshot:
  • branch and divergence context when relevant
  • local working tree status and active diffs
  • obvious build/test entrypoints and workflow constraints
• If the project is unfamiliar or complex, run a short familiarize pass using skills/familiarize/SKILL.md before deep execution.

3) Establish session operating contract

• State and apply the default behavior for this session:
  • proactive + autonomous execution
  • ask only when absolutely necessary
  • loop until completion criteria are met
  • keep scope tight and verification explicit
• If user constraints conflict with default contract, adopt user constraints and record the override.

4) Define the active execution loop

• Choose an adapted loop for the current objective. Example patterns:
  • issue-resolution: investigate -> plan -> implement -> verify -> battletest -> organise-docs -> git-commit -> re-review
  • cleanup-heavy: scan -> prioritize -> clean -> verify -> organise-docs -> git-commit -> re-scan
  • docs-heavy: audit -> update -> verify -> organise-docs -> re-audit
• Treat examples as templates, not rigid sequences.

5) Activate recurring hygiene loops

• organise-docs loop:
  • run after substantial findings, non-obvious decisions, or behavior changes.
  • promote durable knowledge from plan/ to docs/ during execution, not only at the end.
  • do not let doc updates pile up; prefer small, frequent promotions over end-of-task dumps.
• git-commit loop:
  • run at commit-eligible milestones and at least once per major phase when checks are green and policy permits.
  • keep commits small, logical, and easy to review.
  • do not let a large uncommitted diff accumulate; checkpoint whenever there is a clean, verifiable unit of work.
• cleanup loop:
  • run regular lightweight cleanup passes to remove redundant or dead additions introduced during work.
  • include explicit consolidation of overlapping docs/notes/helpers/tests/configs and resolution of contradictory guidance so one clear source of truth remains.
  • keep cleanup scoped; avoid speculative refactors unless clearly justified.
• note-taking/knowledge loop:
  • keep a current session note file in plan/current/ for findings, assumptions, experiments, and open questions.
  • periodically consolidate those notes and push durable items into docs via organise-docs.

6) Prime summary handoff

Provide a concise prime summary before deep execution:

• active objective and scope assumptions
• familiarity snapshot (docs reviewed + current repo state)
• operating contract in force
• selected execution loop
• planned cadence for docs/commit/cleanup/verification
• immediate first actions

Then proceed directly into execution.

7) Enforce throughout the session

• Re-apply the prime contract whenever drift appears (for example repeated low-value reruns, avoidable user questions, stale docs, or delayed checkpoint commits).
• Continue from prior artifacts and logs when re-invoked; do not reset progress unless required.
• If the organise-docs or git-commit cadence slips during a long task, pause to run the hygiene cycle before expanding scope further.
• If there is nothing left to do, say so explicitly and stop.

Guardrails

• Do not let priming become overhead; keep startup concise and begin real execution quickly.
• Do not use priming as a reason to avoid verification, docs compounding, or checkpoint commits.
• Do not ask the user to re-confirm defaults that are already clear from policy or context.
• Do not force unnecessary commits or docs edits when there are no meaningful changes.