Skip to content
Back to search

forward-implementation-first

Stop your coding agent from stalling real work on self-invented bookkeeping - receipts, hashes, locks, certification rituals. Ship first, then verify. Skill for Claude Code, Codex, and other agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vuk97--forward-implementation-first/badge.svg)](/listings/vuk97--forward-implementation-first)

HTML

<a href="/listings/vuk97--forward-implementation-first"><img src="/api/listings/vuk97--forward-implementation-first/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The skill is a single Markdown file with YAML frontmatter, following the [Agent Skills](https://agentskills.io) convention. Copy it wherever your agent looks for skills:

git clone https://github.com/Vuk97/forward-implementation-first
cd forward-implementation-first
./install.sh

`install.sh` copies `SKILL.md` into every agent skill directory it finds:

| Agent | Path | | --- | --- | | Claude Code | `~/.claude/skills/forward-implementation-first/` | | Codex | `~/.codex/skills/forward-implementation-first/` | | Shared convention | `~/.agents/skills/forward-implementation-first/` |

For a project-scoped install, copy the directory to `.claude/skills/` or `.agents/skills/` in the repo instead. Restart the agent afterward. Running sessions do not reload skills.

A skill is a suggestion. The model decides whether to load it. If your agent supports always-on rules or hooks, put the decision rule there too, because this particular failure mode is one the model walks into confidently.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 159 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: forward-implementation-first
  3. description: >
  4. Keeps an agent building and validating real output instead of servicing its
  5. own bookkeeping. Use for multi-stage pipelines, capability roadmaps,
  6. long-running implementation loops, migrations, staged data or build runs, and
  7. any run where administrative hashes, locks, receipts, dashboards,
  8. certification markers, or progress metadata can block correct work. Use when
  9. an agent refuses to advance, rewinds finished stages, or reruns unchanged
  10. work because a marker is missing or stale.
  11. ---
  12. # Forward implementation first
  13. Build working capability and correct output before administrative bookkeeping.
  14. Apply this contract both while building a system and while running it.
  15. ## Scope
  16. This skill applies to:
  17. - infrastructure and roadmap implementation;
  18. - input intake and intermediate artifact production;
  19. - transformation, derivation, and analysis stages;
  20. - test construction, runtime verification, and measurement;
  21. - publication of final output and closeout;
  22. - manual invocation of any authorized pipeline stage.
  23. It applies whether the action runs through a full orchestrator, a focused
  24. command, or a manual stage invocation.
  25. ## Decision rule
  26. Before each action, classify it as one of:
  27. 1. **Semantic implementation**: builds or connects a producer, consumer,
  28. adapter, runtime path, schema, fixture, or final output.
  29. 2. **Focused validation**: tests the changed dependency cone through behavior,
  30. schema, counts, samples, conservation, consistency, nontruncation, or
  31. measured resources.
  32. 3. **Administrative bookkeeping**: generates or repairs hashes, locks,
  33. receipts, dashboards, certification markers, progress metadata, or
  34. presence-only records.
  35. Choose categories 1 and 2. Skip category 3 unless the user asks for it or the
  36. artifact is itself part of the product. When administrative work blocks a path
  37. without protecting correctness, remove that dependency from the path.
  38. ## Hard constraints
  39. - Build the producer and consumer before polishing status or certification
  40. surfaces.
  41. - Do not generate, repair, compare, or propagate administrative hashes.
  42. - Do not create or wait on filesystem locks.
  43. - Do not rerun an unchanged stage to regenerate a receipt or marker.
  44. - Never invalidate valid output because an administrative receipt, hash,
  45. certification marker, dashboard row, or progress record is missing, stale, or
  46. incompatible.
  47. - Never move the forward cursor backward for an administrative metadata change.
  48. - Never invalidate a wide stage range when only one producer or consumer
  49. changed. Replay only that producer's dependency cone.
  50. - Do not treat certification, receipts, dashboards, progress metadata, or
  51. artifact presence as the product.
  52. - Remove hash-only, lock-only, receipt-only, and presence-only credit or gates
  53. from execution paths.
  54. - Do not claim a capability works because its file exists. Run the smallest
  55. changed dependency cone and inspect the output.
  56. - Publish valid output after focused validation. Do not add an extra review
  57. cycle when no defect remains.
  58. ## Forward cursor and manual execution
  59. A stage may move backward or be replayed only when at least one real condition
  60. holds:
  61. - its input meaning changed;
  62. - its target or pinned revision changed;
  63. - its output is malformed, truncated, nonconserving, internally inconsistent,
  64. or incompatible with the consumer;
  65. - an observed run disproves the earlier static result;
  66. - the changed producer's declared dependency cone requires replay.
  67. Missing or stale administrative metadata is not one of those conditions.
  68. When the orchestrator refuses to run a stage only because of a receipt,
  69. certification marker, progress record, administrative hash, or lock:
  70. 1. Run the exact stage manually.
  71. 2. Validate its output with the focused checks below.
  72. 3. Publish the valid output atomically.
  73. 4. Continue from the forward cursor.
  74. 5. Remove or downgrade the administrative-only gate in the execution path.
  75. Do not refuse an authorized manual run because the full pipeline cannot issue a
  76. receipt. Do not push the user toward another agent or tool to get around your
  77. own bookkeeping.
  78. ## Required validation
  79. Use the checks that match the change:
  80. - runtime behavior and exit status;
  81. - schema and type validity;
  82. - exact input, output, accepted, rejected, and unknown counts;
  83. - deterministic first, middle, and last samples;
  84. - identity and partition conservation;
  85. - join consistency and flag polarity;
  86. - nontruncation and bounded diagnostic output;
  87. - wall-clock time and peak memory for material stages.
  88. Hashes may identify inputs or revisions, but they never grant correctness,
  89. execution, or roadmap credit.
  90. ## Exceptions that stay substantive
  91. Bookkeeping is cheap to skip. Evidence is not. Keep these:
  92. - Integrity that belongs to the product itself. A checksum your users verify, a
  93. signature your format requires, a hash that is part of the output contract.
  94. Those are features, not paperwork.
  95. - Input and revision identity when it decides which version of the thing you
  96. are operating on. Getting that wrong means correct work on the wrong target.
  97. - Real measurement: tests that assert results, benchmarks, reproductions,
  98. end-to-end runs, and whatever your domain treats as proof.
  99. - The difference between coverage and consequence. A run that exercises a path
  100. is not a check that the path produced the right answer.
  101. - An execution record is substantive when it carries the command, the input,
  102. the result, and the expectation it was checked against. Its absence blocks
  103. that specific claim. It does not invalidate unrelated earlier stages.
  104. ## Parallel work invariants
  105. These are behavior contracts, not a scheduler. Your runtime owns scheduling,
  106. concurrency, resource contention, and worker topology, and this skill carries
  107. no policy about them. Keep these invariants under any scheduler:
  108. - Exactly one writer owns publication, cursor movement, acceptance, and
  109. conclusions. Parallel workers prepare, implement, inspect, and test
  110. nonoverlapping support work. They never become competing truth.
  111. - Verify a worker's output locally before consuming it. A worker's report
  112. states intent, not result.
  113. - Forward progress does not wait for every worker to finish. Consume completed
  114. output when the dependency that needs it is reached.
  115. - Do not manufacture busywork to occupy idle workers. An idle slot is cheaper
  116. than fake work.
  117. - If a run exposes a defect in a stage, fix that stage before rerunning its
  118. dependency cone.
  119. - If the next proposed action is bookkeeping-only, select the next unresolved
  120. producer, consumer, adapter, or output instead.
  121. If no system owns scheduling in your setup, write a small profile for it
  122. yourself; [examples/execution-profile.md](examples/execution-profile.md) is a
  123. starting point. The skill never loads it on its own.
  124. ## Status reporting
  125. Report implemented behavior and measured output first. List blockers literally.
  126. Keep infrastructure progress separate from evidence about the output. Do not
  127. turn administrative completion into a substitute for working capability.
README.md · README · 193 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Forward implementation first
  2. An agent skill that stops a coding agent from getting stuck servicing its own
  3. paperwork.
  4. Long-running agent pipelines grow bookkeeping: content hashes, lock files,
  5. "receipts" that prove a stage ran, certification markers, dashboard rows,
  6. progress metadata. None of that is the product. All of it is easy for a model
  7. to mistake for the product. Once that happens the agent stops shipping and
  8. starts curating, and you pay full price for an agent that produces nothing you
  9. asked for.
  10. This skill gives the agent one classification to make before every action, and
  11. a short list of things it is never allowed to do. It is about 150 lines of
  12. Markdown. It is model-agnostic, tool-agnostic, and domain-agnostic.
  13. ## The failure mode
  14. You have a pipeline with ordered stages. Stage 40 produces a file that stage 41
  15. consumes. Somewhere along the way the orchestrator also writes a small JSON
  16. record saying stage 40 completed, with a hash of its inputs.
  17. Then you change one producer. The hash no longer matches. Here is what an agent
  18. does without this skill:
  19. - It notices the mismatch and treats it as a correctness failure, because a
  20. mismatch looks like one.
  21. - It invalidates stages 12 through 40, because it cannot prove which of them
  22. the change touched, and invalidating more feels safer.
  23. - It refuses to run stage 41 by hand, because the pipeline "cannot issue a
  24. receipt" for a manual run.
  25. - It spends the next several hours regenerating markers for stages whose output
  26. never changed and was never wrong.
  27. - It reports progress in terms of receipts repaired, which reads like work.
  28. Nothing in that sequence is stupid in isolation. Each step is a defensible
  29. local decision. Together they cost days, and the output at the end is identical
  30. to the output you already had. The pathology is that administrative metadata is
  31. being used as a proxy for correctness, and the proxy is both cheaper to check
  32. and completely uninformative.
  33. The second half of the failure mode is worse: the agent tells you it cannot
  34. proceed. You then go run the stage yourself, or open a second agent to do it,
  35. and the first agent sits there guarding a hash.
  36. ## What the skill does
  37. Before each action, the agent classifies it as one of three things:
  38. 1. **Semantic implementation.** Builds or connects a producer, consumer,
  39. adapter, runtime path, schema, fixture, or final output.
  40. 2. **Focused validation.** Tests the changed dependency cone through behavior,
  41. schema, counts, ordered samples, conservation, consistency, nontruncation,
  42. and measured time and memory.
  43. 3. **Administrative bookkeeping.** Generates or repairs hashes, locks,
  44. receipts, dashboards, certification markers, progress metadata, or
  45. presence-only records.
  46. Do 1 and 2. Skip 3 unless the user asks for it, or the artifact is part of the
  47. product. When category 3 blocks a path without protecting correctness, delete
  48. the dependency.
  49. That is the whole idea. The rest of [SKILL.md](SKILL.md) makes it hard to
  50. weasel out of, because a model that wants to do bookkeeping will find a reason.
  51. ## What it does not relax
  52. This is the part that makes the skill safe to install, and the part most
  53. "just move faster" prompts get wrong. Bookkeeping is cheap to skip. Evidence is
  54. not. The skill explicitly preserves:
  55. - integrity that belongs to the product itself. A checksum your users verify, a
  56. signature your format requires, a hash that is part of the output contract.
  57. Those are features, not paperwork;
  58. - input and revision identity, when it decides which version of the thing you
  59. are operating on. Getting that wrong means correct work on the wrong target;
  60. - tests that assert results, benchmarks, reproductions, and end-to-end runs;
  61. - the difference between coverage and consequence. A run that exercises a path
  62. is not a check that the path produced the right answer.
  63. An execution record that carries the command, the input, the result, and the
  64. expectation it was checked against is real evidence. Its absence blocks the
  65. claim it supports. It does not retroactively invalidate an unrelated stage
  66. twenty steps back. That distinction is the whole difference between rigor and
  67. superstition, and it is the line the skill draws.
  68. ## The forward cursor rule
  69. A pipeline stage may be replayed or rolled back only for a real reason:
  70. - its input meaning changed;
  71. - its target or pinned revision changed;
  72. - its output is malformed, truncated, nonconserving, inconsistent, or
  73. incompatible with its consumer;
  74. - an observed run disproves the earlier static result;
  75. - the changed producer's declared dependency cone requires it.
  76. Missing or stale metadata is not on that list. When a stage is blocked only by
  77. a marker, the agent runs it manually, validates the output, publishes it,
  78. continues from the cursor, and then removes the administrative-only gate so the
  79. same block cannot happen again. Replay the smallest affected cone, not the
  80. whole history.
  81. ## Parallel work: invariants, not a scheduler
  82. The skill also covers parallelism, because the two problems show up together.
  83. An agent that is busy with bookkeeping usually also serializes everything.
  84. Early feedback drew one boundary the first version got wrong: a skill must not
  85. act as an orchestrator. Scheduling, resource contention, and worker topology
  86. belong to your runtime, and a few lines of Markdown that claim them will fight
  87. any real scheduler. So the section is split in two.
  88. Invariants, kept as first-class rules because they hold under any scheduler:
  89. - Exactly one writer owns publication, cursor movement, and conclusions.
  90. Parallel workers prepare and inspect. They never become a second source of
  91. truth.
  92. - Verify a worker's output before consuming it. A report states intent, not
  93. result.
  94. - Forward progress does not wait for every worker. Consume output when the
  95. dependency that needs it is reached.
  96. - Never invent busywork to fill an idle slot.
  97. Scheduling policy itself, worker counts, wave sizes, what counts as a heavy
  98. process, is not in the skill at all. Your runtime already owns it, and a skill
  99. that carries its own policy would fight it. If nothing owns scheduling in your
  100. setup, [examples/execution-profile.md](examples/execution-profile.md) is a
  101. starting profile to copy and edit. The skill never loads it on its own.
  102. The invariants matter more than the speedup. Cheap parallel workers are useful
  103. precisely because they are not trusted, and the value disappears the moment
  104. their output is merged without a check.
  105. ## Install
  106. The skill is a single Markdown file with YAML frontmatter, following the
  107. [Agent Skills](https://agentskills.io) convention. Copy it wherever your agent
  108. looks for skills:
  109. ```bash
  110. git clone https://github.com/Vuk97/forward-implementation-first
  111. cd forward-implementation-first
  112. ./install.sh
  113. ```
  114. `install.sh` copies `SKILL.md` into every agent skill directory it finds:
  115. | Agent | Path |
  116. | --- | --- |
  117. | Claude Code | `~/.claude/skills/forward-implementation-first/` |
  118. | Codex | `~/.codex/skills/forward-implementation-first/` |
  119. | Shared convention | `~/.agents/skills/forward-implementation-first/` |
  120. For a project-scoped install, copy the directory to `.claude/skills/` or
  121. `.agents/skills/` in the repo instead. Restart the agent afterward. Running
  122. sessions do not reload skills.
  123. A skill is a suggestion. The model decides whether to load it. If your agent
  124. supports always-on rules or hooks, put the decision rule there too, because
  125. this particular failure mode is one the model walks into confidently.
  126. ## When to use it
  127. Install it if any of these describe your setup:
  128. - a pipeline with ordered stages and a persisted cursor;
  129. - generated artifacts that later stages depend on;
  130. - any manifest, lockfile, or receipt written by the orchestrator rather than by
  131. the work itself;
  132. - runs long enough that you are not watching every step;
  133. - multiple agents or sessions touching one repository.
  134. Common shapes: staged data and ETL runs, large code migrations, build and
  135. release pipelines, documentation generation over many inputs, batch analysis
  136. jobs, and any roadmap an agent works through over days.
  137. Skip it for single-shot tasks, short interactive sessions, and any workflow
  138. where the audit trail is the deliverable. If someone is going to read your
  139. receipts, they are not bookkeeping.
  140. ## Where this came from
  141. This started as a prompt pasted at the top of every session in a long-running
  142. staged pipeline, where the agent had repeatedly invalidated dozens of completed
  143. stages over metadata drift and then declined to run stages by hand. Pasting it
  144. every time worked. Forgetting to paste it cost days.
  145. Turning it into a skill made the behavior default instead of remembered.
  146. ## License
  147. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.