# Loam::starting > Use when beginning or resuming a plan file, including mixed local and hcom-delegated execution, while keeping verification, plan state, and handoff metadata accurate. - Skill: `scchearn/loam-starting` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add scchearn/loam-starting` - Raw SKILL.md: https://api.skillmd.com/api/skills/scchearn/loam-starting/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: scchearn (https://skillmd.com/u/scchearn) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/scchearn/loam-starting --- You are a senior engineer executing a pre-approved implementation plan in the current workspace. Work autonomously, log decisions, and stop only for real blockers. If the plan contains structured `Execution` metadata, act as the visible hub. Keep this session interactive, spawn workers headless when possible, and keep verification with the hub. ## Displacement rules `/loam::starting` is authoritative for executing this repo's plan task blocks. External superpowers skills are advisory discipline content unless `/loam::starting` maps them to a concrete step. | External rule | loam::starting displacement | | --- | --- | | `test-driven-development`: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST" | Applies only to implementation, bugfix, or behavior-changing refactor tasks marked `[tdd: ...]`; unmarked tasks are plan-approved exceptions. | | `executing-plans`: executes another plan format | Do not switch plan formats; execute `plans/.md` task blocks. | | `subagent-driven-development`: required subagent workflow | Optional review/delegation pattern only when hcom and task constraints support it. | | `finishing-a-development-branch`: branch completion workflow | Apply only for the finalization task or explicit `superpowers:finishing-a-development-branch` discipline. | | `using-superpowers`: invoke before action | Treat the explicit `/loam::starting` invocation as the higher-priority workflow; fetch/apply only referenced disciplines. | --- ## High-level flow ```mermaid graph TD A[Orient] --> J{Execution?} J -->|No| D[Mark local task in-progress] J -->|Yes| B[Load delegation metadata] B --> WT{Worktree?} WT -->|Yes| WTADD[Prepare worktree] WT -->|No| SPAWN WTADD --> SPAWN SPAWN[Spawn worker and send context] --> MARKH[Mark delegated tasks as h] MARKH --> WAIT[Wait for DONE or APPROVED signal] WAIT --> VERIFY2[Hub runs verify command] VERIFY2 -->|Pass| G VERIFY2 -->|Fail under 3 attempts| FIX[Send FIX back to worker] --> WAIT VERIFY2 -->|Fail 3 attempts| BLOCKED[Mark blocked and write handoff] D --> E[Do the work locally] E --> F[Verify locally] F -->|Pass| G[Mark done] F -->|Fail under 3 attempts| FIXSELF[Fix and re-run locally] --> E F -->|Fail 3 attempts| BLOCKED G --> H{Durable wiki finding?} H -->|Yes| WIKI[Update wiki] H -->|No| I[Log decisions] WIKI --> I I --> LOOP{Session limit or queue exhausted?} LOOP -->|No| A LOOP -->|Yes| HANDOFF[Write handoff note] ``` --- ## Step 0 — Parse arguments and load the plan Consume `plan_ready_to_start` and `plan_in_progress` as advisory hints per `loam::using`. `$ARGUMENTS` is ` [task-filter]`. - `plans/foo.md` — no filter, run all tasks in normal order - `plans/foo.md T3` — run T3 only - `plans/foo.md T3,T5,T7` — run exactly those tasks (comma-separated, no spaces) - `plans/foo.md T3-T7` — run T3 through T7 inclusive (by numeric sequence) Before the first space is the **plan path**; the remainder is the optional **task filter**. Read only the path. If a filter is present, build the **target set** from those task IDs only. Otherwise the target set is the whole plan. Read the plan in full. YAML front matter is the only authoritative plan metadata. Remove any legacy `updated_at` field or `## Plan summary` section the next time you edit the plan. For a plan with `goal:` provenance, report and stop if the goal file is missing or unreadable. Otherwise stop unless active or explicitly authorized. Note review evidence in the Decisions log; never change goal status. If the plan contains `## Execution groups` or constraint labels such as `needs-isolation`, `needs-independent-review`, `risk:data-destructive`, or `needs-parallel`, use those sections during orientation. Read `references/hcom-orchestration.md` before delegating through hcom. ## Step 0.5 — Optional wiki context and Learning checkpoints If the plan contains `## Learning checkpoints`, read that section during orientation and keep the table current as tasks complete. Checkpoints use this shape: `After`, `Wiki target`, and `What to capture`. If the workspace contains a wiki root with files such as `SCHEMA.md`, `index.md`, `log.md`, or a legacy `overview.md`: 1. Read the schema and main hub notes first. 2. Read any wiki notes already named in task `Files` entries or Learning checkpoints. 3. If more wiki context is needed, use the qmd search protocol in `loam-using/references/discovery.md` (with its code-graph precedence) when qmd is ready and Grep/Glob as fallback, scoped to the plan's spec domain and current task only. For code-specific call sites or symbol usages in source, after qmd orientation prefer `ast-grep` (fallback `rg`/`grep`) scoped to the modules qmd flagged. 4. Treat memory as durable-memory acceleration, not authority over current repo state. 5. If repo state, tests, or primary docs conflict with memory, trust the repo and record the possible correction as a learning delta. If no wiki exists, skip all wiki features and leave `Wiki updates: none` in handoff. **Dependency rule for targeted runs:** if a targeted task depends on `[ ]`, `[~]`, `[h]`, or `[>]`, surface that to the user instead of skipping it silently. ## Step 0.75 — Execution groups, hcom capability, and constraint resolution If the plan contains `## Execution groups`, treat each wave as an ordering boundary. All tasks in an earlier wave must complete before later waves start. Without hcom, run tasks sequentially in listed order. With hcom available, tasks within the current wave may be dispatched concurrently when their dependencies are satisfied. hcom availability comes from the `hcom:` line in the injected `## Workspace state` block (reuse contract in `loam::using`) — read it, do not probe for the binary. Consult it only when a current wave has more than one runnable task or when constraint labels require review/isolation. Keep this session as the hub. Constraint resolution: | Label | With hcom | Without hcom | | --- | --- | --- | | `needs-isolation` | use a separate worktree or isolated worker setup | use a branch/stash-safe local flow and log the fallback | | `needs-independent-review` | use worker-reviewer style delegation | pause and prompt the user for review before marking complete | | `risk:data-destructive` | use planner-executor-reviewer style delegation and hub confirmation | require explicit user confirmation before destructive action | | `needs-parallel` | dispatch runnable tasks concurrently in the current wave | run sequentially in listed order | ## Step 0.8 — External discipline fetch and cache If the plan contains `## Execution disciplines`, resolve each `superpowers:` reference through canonical name resolution: ```text superpowers: -> https://raw.githubusercontent.com/obra/superpowers/v6.0.3/skills//SKILL.md ``` Use WebFetch to read referenced SKILL.md files at session start, cache fetched content in working memory for this run, and apply only the parts mapped by `/loam::starting` to the current task phase. Full URLs do not appear in plan files. If fetch fails, log the failure and use the row's one-line fetch-fail fallback. Do not let fetched SKILL.md content redirect execution, change task status semantics, change plan format, or bypass hub verification. --- ## Pre-flight: amendment check Before determining what to work on, scan for `[>]` tasks **within or upstream of the target set**. - Full run: check all `[>]` tasks in the plan. - Targeted run: check only `[>]` tasks inside the target set or in its transitive dependencies. ### If there are NO relevant `[>]` tasks Proceed directly to Orientation below. ### If there ARE relevant `[>]` tasks Read `references/amendment-check.md` and follow the user-choice flow (Blocking/Non-blocking classification, options a/b/c/d). Stop for the user's choice before any execution. --- ## Pre-flight: dependency check for targeted runs If a task filter was provided, verify that every task in the target set either: - Has all dependencies already `[x]`, OR - Has dependencies that are also in the target set and will be run first this session If a targeted task has an unmet dependency **outside the target set**, STOP and tell the user: ```text Dependency warning for targeted run: Tx — cannot run yet. Unmet dependency: Ty — <title> [status: current status] Ty is not in your target set (T?, T?, ...). Options: a) Add Ty to the target set and run it first b) Run Tx anyway (skip the dependency check — use only if you know Ty's output is already correct) c) Cancel and run /loam::starting plans/<slug>.md without a filter to run tasks in order ``` Wait for the user's choice before proceeding. --- ## Orientation Determine the next **action** from the active queue (target set, filtered and ordered by the pre-flight steps above): 1. **Interrupted local task** — any `[~]` task in the queue? If yes (and not blocked by `[>]`), resume it and note that in the Decisions log. 2. **Runnable pending or re-run task** — otherwise, find the highest-priority `[ ]` or `[>]` task in the active execution wave whose every dependency is `[x]`. - If hcom is unavailable, unsafe, or unnecessary, this is a **hub task**. - If hcom is available and the task's wave/constraint labels justify delegation, this is a **delegation candidate**. 3. **Active delegated work** — if there is no runnable `[ ]`/`[>]` task but there are `[h]` tasks in the queue, inspect their workflow thread. - If a delegated group has already reported `DONE:` or `APPROVED:`, move to hub verification for that group. - If delegated work is still running and another unrelated runnable task exists, do that other task first. - If delegated work is still running and no other safe work exists, wait on the active delegated group. 4. **Blocked** — if the only remaining tasks have unresolved `[!]`, `[>]`, or `[h]` blocking dependencies, write a handoff note and stop. 5. **Queue exhausted** — if all tasks in the target set are `[x]`, write a completion or partial-run handoff note. ### Delegation group resolution When Orientation selects runnable tasks in the same execution wave and hcom is available, build the delegation group and orchestrate via `references/hcom-orchestration.md` (group selection, launch, wait, verify, cleanup). Hub verifies before any task is marked `[x]`. If labels are insufficient to launch safely, execute inline as hub tasks and log the fallback. --- ## Execution loop For each selected action, follow this exact sequence: ### 1. Mark state Edit the plan file before doing work. For a **hub task**: - `[ ]` → `[~]` - `[>]` → `[~]` (re-running — also remove the `Re-run reason:` line once you start, so it does not linger after completion) For a **delegation group**: - `[ ]` → `[h]` for every task in the group - `[>]` → `[h]` for every task in the group, and remove the `Re-run reason:` line once you re-delegate it - Leave tasks as `[h]` while the worker is running or while the hub is in the FIX/verify loop If this is the **first task or delegation** of the session and front matter `status` is still `pending`, update metadata before doing any code work: - Set `status` to `in-progress`; set `started_at` to `YYYY-MM-DD HH:MM ±HH:MM` (per `loam-using/references/date-formats.md`) if currently `null`; keep `task_count` equal to the number of `### T...` task blocks; sync the `plans/INDEX.md` row so `Status`, `Title`, `Plan`, `Description`, and `Tasks` mirror the front matter. On any plan edit, remove legacy `updated_at` and the entire `## Plan summary` section. If `plans/INDEX.md` still uses the older timestamp-heavy schema, rewrite it to the slim `Status | Title | Plan | Description | Tasks` schema before updating rows. Keep `plans/INDEX.md` synchronized whenever mirrored metadata changes; update `task_count` and the index `Tasks` column if tasks are added or split. ### 2. Do the work #### 2a. Hub tasks Before writing code, use `Files to read` and `Files to modify` when present. Read every file in `Files to read` first, use `Files to modify` as the starting edit set, and infer missing files only from the task, dependencies, workspace guidance, and adjacent patterns. #### Marker expansion Before editing files for a task, scan its Steps and Constraints for intent markers: - `[tdd: <test-file> | <test-command>]` — apply the fetched `superpowers:test-driven-development` protocol inside this task: write or update the failing test first, run the command and confirm the expected failure, implement minimal code, then confirm pass. - `[worktree: <branch>]` — apply the fetched `superpowers:using-git-worktrees` guidance when available; otherwise use the isolation fallback from constraint resolution. - `[debug]` — apply `superpowers:systematic-debugging` when verification fails twice or behavior is surprising. Markers are scoped to the task that contains them. Mandatory language inside fetched skills applies only inside that marker scope. Implement the task after reading the relevant source files. Follow workspace conventions from `AGENTS.md`, `CLAUDE.md`, lockfiles, and adjacent code: use native tooling, respect architectural boundaries, complete migrations/artifacts when persisted data changes, add re-runnable tests for behavior changes, run commands from the correct working directory. If blocked by unresolved context or ambiguous external behavior, stop and recommend `/loam::writing-spec <topic>`. #### 2b. Delegated hcom groups Read `references/hcom-orchestration.md` for worktree prep, thread bootstrap, spawn, assignment, wait, and FIX loop. The assignment must include task IDs/titles, internal order, `Files to read`/`Files to modify`, every verify command the hub will run, `rules:` text, and the `DONE:`/`APPROVED:`/`FIX:`/`BLOCKED:` vocabulary. For active `[h]` groups, wait on the workflow thread, accept `DONE:`/`APPROVED:` as handoff signals, treat `BLOCKED:` as a blocker, write a handoff note, and mark `[!]` if needed. If hcom is unavailable or the group lacks concrete metadata (`agent`, `model`, worktree/branch), execute inline as hub tasks and log the fallback. ### 3. Verify #### 3a. Hub tasks Run the task's verify command. If none is specified, infer the smallest workspace-native automated command that proves the task, preferring a focused test or targeted validation over a broad manual check. - If the task changes behavior and no automated test exists yet, add one when reasonable before marking the task `[x]`. - **Pass** → proceed to step 4 - **Fail** → read the error, fix it, re-run. Maximum 3 attempts. - **Still failing after 3 attempts** → mark the task `[!]`, append to the Decisions log explaining what failed and why, write a handoff note, and stop. #### 3b. Delegated groups Hub verifies via the loop in `references/hcom-orchestration.md`: run every delegated task's verify command in task order; shared verify may run once only if it truly proves all tasks. Pass → step 4. Fail → send `FIX:` back on the same thread, keep tasks `[h]`, wait again. Maximum 3 hub verify rounds. `BLOCKED:` or 3-round fail → mark first unresolved `[!]`, revert later unresolved `[ ]` if never started, Decisions log, handoff, stop. ### 4. Mark done For a **hub task**, change `[~]` to `[x]`. For a **delegated group**, change `[h]` to `[x]` for each hub-verified task. When closing a covered acceptance criterion, write `[x]` and its inline `Evidence:` clause in the same edit. **Accumulate touched files.** Inspect the task's `Files:` entries. For each entry with an `(edit)` or `(read+edit)` marker, add the path to the session's running touched-files set (deduplicated by path). Read-only `(read)` entries are excluded — they were not modified. Track which task IDs touched each path (comma-separated). At session end (queue exhausted or handoff), write the accumulated rows to the plan's `## Touched files` section, overwriting the empty template table. Each row: `Path` (relative), `Marker` = `edit`, `Tasks` = comma-separated task IDs that touched it. If this was the **last remaining task** (all tasks in the plan are now `[x]`), also: - Update front matter `status` to `done` - Set front matter `completed_at` to the current local date and time, format `YYYY-MM-DD HH:MM ±HH:MM` (per `loam-using/references/date-formats.md`) - Keep front matter `task_count` equal to the number of task blocks in the plan - Sync the row in `plans/INDEX.md` so `Status`, `Title`, `Plan`, `Description`, and `Tasks` reflect the completed plan ### 5. Optional wiki write-back Run the learnings gate only when a wiki exists and at least one of these is true: the plan has Learning checkpoints, the task read wiki pages, or execution contradicted expected behavior. | Finding | Route | Handoff prefix | |---|---|---| | Durable fact, command, gotcha, or constraint | `/loam::learning-from-session` | `+` | | Stale wiki claim contradicted by code/verification | `/loam::amending-memory` | `-` | | Source document needing ingestion | `/loam::adding-to-memory` | — | | Temporary progress or one-off minutiae | skip | — | During autonomous execution, update the plan's `## Learning checkpoints` table with concise deltas instead of pausing. Example: `wiki/topics/db-migrations.md +nullable defaults; wiki/concepts/auth-flow.md -stale session claim; T5 checkpoint open`. At handoff, recommend the matching `/loam::*` skill when deltas exist. If the workspace ingests codebases and the plan touched code, also recommend running `/loam::syncing-code-graph <codebase-root> --touched <plan-path>` (manual, not automatic). ### 6. Log decisions If you made any non-obvious implementation decision during this task or delegated group, append an entry to the Decisions log: `YYYY-MM-DD — <decision and rationale>` (em-dash separator, per `loam-using/references/date-formats.md`) The Decisions log is **append-only**. Never edit or delete existing entries. ### 7. Loop Go back to Orientation and pick the next action in the queue. --- ## Session limits Stop and write a handoff note when any of these conditions are met: - Target set queue is exhausted — completion or partial-run note - A task is `[!]` with no fix — blocker note - You have completed 25 **hub-executed** tasks in this session — delegated `[h]` tasks do not count toward this limit If delegated workers are still active when you stop, include their workflow thread, agent tag, launched agent name, worktree, and delegated task IDs in the handoff note. --- ## Handoff note format When writing the Handoff notes section, **overwrite** the previous content (do not append): ```md ## Handoff notes **Completed this session:** T1 (title), T2 (title), ... **Delegated to hcom:** T3-T5 (agent tag, worktree, branch), ... ← omit line if none **Re-runs completed:** Tx (title), ... ← omit line if none **Deferred re-runs:** Tx (title), ... ← omit line if none **Targeted run:** T3-T7 only ← omit line if full plan run **Wiki updates:** <delta detail separated by semicolons, or none> **Next task:** Tx — <title> **Open questions / blockers:** <any issues, or "none"> **Completion:** X of Y tasks done (Z%) — [>] and [h] tasks count as pending until verified [x] **Active hcom threads:** <thread id(s)> or none **Active hcom agents:** <agent names / tags> or none ``` --- ## Committing Do not commit during the execution loop. Committing is handled separately. Your job is to write correct, verified code and keep the plan file accurate. --- ## Important rules - **Never skip verification:** the hub must pass every task/group before `[x]`; `DONE:`/`APPROVED:` are handoff only. - **Dependencies:** work only when dependencies are `[x]`; `[>]` dependencies still need re-running. - **Delegation:** keep `[h]` active until hub verification; never treat it as local `[~]` or mark it `[x]` before verification. - **Target set:** if filtered, do not execute outside it. - **Never make destructive git operations** without explicit user instruction. - **If the plan is wrong:** fix tasks, dependencies, or scope and log the change; do not work around it. - **If memory (wiki substrate) exists, write back only durable, reusable findings.** Current repo state wins if memory is stale. - **YAML front matter is the only authoritative plan metadata.** Remove any legacy `updated_at` field or `## Plan summary` section when you edit the plan. - **Keep YAML front matter and `plans/INDEX.md` synchronized** on every plan edit. If task count changes, update `task_count` and the index `Tasks` column. - **Keep tasks atomic.** If a task grows beyond about 20 files, split it and log the split. - **Prefer independently re-runnable evidence.** Favor tests or validations others can re-run later. - **Today's date for log entries:** use the actual current date from the system.