Index of every page on this site: llms.txt
All skills
scode avatar

/scode-build-blueprint

@03a9f7f
Run it yourself

Build a repository-grounded implementation blueprint for a separate workhorse session, or execute an existing blueprint that explicitly requires this skill. The planner designs; the executor implements with bounded workers and state-of-the-art consultations and reviews. Discussing or editing the skill does not start either phase.

  • 9 files
  • 87.4 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/scode/dotfiles/scode-build-blueprint

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

records.md

≈2.7k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Execution evidence

The executor is the sole writer of the manifest and immutable events. The watchdog alone writes its separate mutable heartbeat/status artifact as watchdog.md specifies. Record observable choices and outcomes, not private reasoning traces or claims about hypothetical savings. This record is independent of Galaxy Brain and does not load it. Planning metadata in the blueprint and executor metadata here allow later joining when harness identities are exposed.

Private, durable state

On a fresh execution, resolve ${XDG_STATE_HOME:-$HOME/.local/state}/scode-build-blueprint/executions/; a relative XDG_STATE_HOME falls back to $HOME/.local/state. Generate a UUID with an available UUID generator. Create the UUID directory exclusively with mode 0700, and verify its mode before writing evidence. A collision or pre-existing symlink means choose another UUID, never adopt it. Do not change permissions on the user's existing state root. Files must be private too (0600); use the agent's dedicated editing tools and check resulting permissions.

Create execution.json, events/, and artifacts/ inside it. Record its UUID and absolute path in the working log. The UUID identifies this execution of the blueprint across executor sessions and resumes, not one model call. Recover only the exact recorded directory and verify its manifest on resume. If lost, create a new UUID and a gap event linked to any known prior execution; never guess the most recent directory. Do not reset milestone budgets or forget existing work because recording identity was lost. If those cannot be recovered, block affected launches.

execution.json has schema_version: 1, execution_id, created_at (UTC RFC 3339), blueprint_path, blueprint_hash, repo_path, baseline_revision, policy_revision, and planning_session_id. Unknown fields are null. Keep the initial manifest immutable; session events record later executors, blueprint changes, and resumes.

Shellout writes run-ID-named prompts, transcripts, stderr, and results to private scratch per its own rules. Before launch, retain a private copy of the exact prompt and task inputs referenced by it under artifacts/<run-id>/; for large versioned inputs retain revision/path references rather than a whole repository copy. Retain every follow-up prompt before sending it. After each turn, retain result and review artifacts plus structured usage source records before scratch cleanup, recording their durable paths. Preserve ephemeral task specifications rather than just their paths. This permits reconstruction of explicit instructions, not a promise to reproduce the harness's entire hidden context. Keep credentials out of prompts and never copy credential/configuration files into evidence. Sensitive task content may still be present; keep records local and private.

Whole harness transcripts are not required for this initial recorder. Preserve the usage records with original field names, source identity and event position, plus exact delegate prompts and deliverables. Retain an existing raw transcript path when available and state whether it is temporary; never imply it will survive scratch cleanup.

Do not automatically upload, prune, price, or analyze records. If recording fails, report the gap immediately and in the final summary; continue only otherwise-authorized work whose permission/budget state is still known. Restore recording when possible, without inventing the missing interval. Telemetry failure is not permission to drop checkpoint gates.

Events and identity

The existing working log is the compact recovery view, not a second event store. Keep open finding identifiers and their source review, repair attempts and verification results, pending gates, exact session/process handles, and next actions there with links to retained artifacts. Update it when these change and reconcile it after compaction/resume and before completion. Never infer resolution from an attempted repair or an omitted item in a later summary. Retain closed dispositions and their evidence so the next session can distinguish fixed, expert-rejected, and open findings without replaying every event. Keep watchdog status and ownership in the same handoff; old healthy samples are not proof of current coverage.

Write one complete immutable JSON object per events/<event-uuid>.json; never append to a shared file or overwrite an event. Common fields are schema_version: 1, event_id, execution_id, at (UTC RFC 3339), type, unit_id, attempt_id, and data. Nonapplicable IDs are null. A unit is a stable piece of work, including work kept local. A new launch gets a new attempt/run UUID; resumptions of that same agent retain it and get distinct turn IDs. Retries link previous_attempt_id; changing IDs never resets explicitly approved budgets. Budget fields are null when no cap applies, not zero or a made-up allowance. Role, trigger, calls, follow-ups, outcomes, and measured usage are recorded regardless of caps, so uncapped expert use remains auditable. Use these event types:

  • session: phase (start, resume, blocked, complete), actual executor harness/model/effort and harness session ID when exposed, blueprint/policy hashes, outstanding units and budget consumption. Requested identity is separate from reported identity; unknown actual identity stays null.
  • decision: decision UUID, milestone, role (local, worker, consultation, review), task label, action (local, delegate, blocked), short reason, trigger, profile, requested model/effort, routing answer, effective mechanism, allowlist entry or expert gate authorizing it, expected duration, hard deadline, budget ID and counting unit, budget before launch, and previous attempt ID. Log substantive local units too, not each command. Include supersedes_decision_id, null unless replacing an unlaunched decision on the same unit. Replacement closes only that decision, not the unit.
  • launch: decision ID, status (started, failed), run ID, prompt artifact path, working tree identity, process handle, harness session ID, reported model/effort, start time, and failure reason if any.
  • continuation: decision ID, turn ID, harness session ID, retained follow-up path, trigger, budget ID and charge in its declared unit, launch status, and start time. Record every consultation/review follow-up, not just first launches.
  • outcome: decision/turn ID, status (accepted, failed, blocked, cancelled, inconclusive), artifact paths, judged-by identity/role, findings, executor repairs, verification evidence and tree identity, next action, elapsed wall milliseconds, budget ID and consumed amount in its declared unit, and usage coverage (reported, partial, unavailable) with reason. The outcome reports the charge already made, not an additional debit for that turn.
  • usage: the source-backed measurement below. May arrive after an outcome; do not fabricate zero usage on failure.
  • watchdog: phase (start, alert, recovery, failure, restart, stop), monitor handle/identity, status path, measured values and thresholds, affected paths, and executor response. A model watchdog also receives normal decision/launch/outcome/usage events with role and usage actor watchdog; a process monitor has no model token usage.
  • gap: missing evidence, affected IDs, known time bounds (null if unknown), and reason.

Local work receives outcomes too. A decision without a launch/outcome/superseding decision is unresolved, not failed. An attempt interrupted without a terminal record is likewise unresolved. Human-readable times aid inspection; IDs and explicit links establish lineage. Log expert advice and how the executor acted on it, including rejected findings and the expert's adjudication. Reviewer acceptance is distinct from executor integration and final goal completion.

Write decisions before acting and launch/continuation records as those operations happen, not as a batch at shutdown. Generate IDs with the UUID generator and timestamps from the clock; do not invent sequential UUID-shaped IDs or rounded historical times. When reconstructing a missed event, use the current recording time, label it retrospective, and cite the source for any recovered occurrence time (unknown stays null). Preserve each failed launch and interrupted turn, even when a later resume succeeds. Before the final session event, account for each decision and turn with an outcome, superseding decision, or explicit unresolved gap; local work needs an outcome too. Check required fields and ID links against this schema. Missing records mean partial coverage, not a clean execution history.

Token accounting

Use the harness sidecar's structured-output mode on every launch and resume, even when no continuation is planned. For Codex this includes --json alongside the final-message file. Retain stdout events and stderr separately. For other harnesses read their verified usage source/procedure; if unavailable, record that gap instead of inventing flags or switching to native agents. Shellout is selected for observability but does not guarantee model identity or counters.

Each usage event includes actor (executor, worker, consultation, review), reported model/effort or null, meter_id, source_record_id, durable source path and exact event/field, scope (turn, session, subtree, unknown), counter_kind (delta, cumulative, unknown), includes_children (boolean or null), raw_counters, counter_semantics, and reported_cost (null or amount/currency/source). Preserve requested model aliases in decisions; they are not proof of what ran. Retain usage from failed, cancelled, and resumed runs whenever exposed.

Never emit the same source measurement twice. Sum distinct per-turn deltas once; cumulative counters need a baseline and final sample on the same meter across resumes, not addition of repeated totals. Only a known fresh meter has a zero baseline. Do not add cached-input or reasoning subsets into totals that already include them. Unknown scope, overlapping parent/child counts, or mixed-model attribution exclude a measurement from attributed totals until resolved. Unexpected child activity is both a policy violation and an accounting gap, not permission to count overlapping meters.

Top-level executor and planning usage may be unavailable. Capture exposed counters without searching unrelated harness history, asking models to estimate tokens, or allocating whole-session counts to individual units. Record measured elapsed time separately from token counts. Record reported monetary costs only; no remembered prices or subscription estimates. Later comparisons must include planning, executor, worker, consultation, review, and repair costs with coverage gaps, rather than comparing only successful worker calls.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 03a9f7f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago

README badge

README badge for scode/dotfiles/scode-build-blueprint