agentleFS
KlerithKlerith/fernando-skills/skills/engineering/spec-impl/SKILL.md

spec-impl

Skill394 starsChanged 6 months agoMITView on GitHub

Implements an approved spec. Validates that the state means "Approved" (in any language), creates a git branch named after the spec, switches to it, and starts the implementation step by step with pauses to review diffs.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. ByteLab-dev-ar/skills-proyectos★ 0same name
    2. xsyubin/clue-lens★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

29 rules. About 0 are common, 16 are distinctive, and 13 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈16

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 13

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow these four phases in strict order.

    line 29
  2. Very specific:

    If $ARGUMENTS is empty:

    line 37
  3. Distinctive:

    Ask the user to specify the exact name of the spec.

    line 40
  4. Distinctive:

    Stop and wait for an answer.

    line 41
  5. Very specific:

    If $ARGUMENTS has a value:

    line 43
  6. Very specific:

    Look for the file in specs/.

    line 45
  7. Distinctive:

    If you do not find the file, show the available specs and ask the user to correct the name.

    line 46
  8. Distinctive:

    If you do find it, continue to Phase 2.

    line 47
  9. Very specific:

    Read the spec file you located in Phase 1 using the Read tool or cat.

    line 53
  10. Distinctive:

    Treat any of the following (and their equivalents in other languages) as the Approved state and continue:

    line 59
  11. Distinctive:

    If you are unsure whether a value means "approved", do not assume.

    line 80
  12. Distinctive:

    Do not offer alternatives, do not suggest "I can still start if you want".

    line 98
  13. Distinctive:

    Check the working tree first: Look at the git status --short output in the session context above.

    line 106
  14. Distinctive:

    Wait for the answer. Do not stash or commit on the user's behalf unless they explicitly ask for it.

    line 115
  15. Very specific:

    Read the AutoCreateBranch flag from the Workflow config shown in the session context above.

    line 122
  16. Very specific:

    If the config file does not exist, the value is missing, or the value is unrecognized → treat it as true (the default).

    line 124
  17. Very specific:

    Only an explicit false (in any capitalization) disables automatic branch creation.

    line 125
  18. Distinctive:

    If the branch does not exist: create it with git checkout -b spec-NN-slug.

    line 129
  19. Very specific:

    If AutoCreateBranch is false: ask before touching git. Show:

    line 133
  20. Very specific:

    If the user answers yes: create/switch to the branch exactly as in the true case above.

    line 140
  21. Distinctive:

    After showing the spec summary, tell the user:

    line 165
  22. Distinctive:

    Wait for explicit confirmation ("yes", "go ahead", "go", or equivalent).

    line 175
  23. Very specific:

    Commit with the message spec-NN-step-MM and nothing else (no description, no body).

    line 184
  24. Very specific:

    If the user asks for adjustments to the step while reviewing it, apply them and fold them into the same commit (git add -- <files> + git …

    line 185
  25. Very specific:

    If the commit fails (e.g. a pre-commit hook rejects it), stop and show the error.

    line 186
  26. Very specific:

    If AutoCommitSteps is true, commit the step as described above.

    line 194
  27. Distinctive:

    Wait for confirmation before continuing.

    line 197
  28. Distinctive:

    Wait for the user's decision.

    line 204
  29. Distinctive:

    Do not implement it on this branch.

    line 211

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/spec-impl — Implementer of approved specs

Session context

Current repository state: !git status --short

Current branch: !git branch --show-current

Specs available in this folder: !ls specs/ 2>/dev/null || echo "The specs/ folder does not exist"

Workflow config: !cat specs/.spec-config.yml 2>/dev/null || echo "No config file — defaults apply: AutoCreateBranch: true, AutoCommitSteps: false"


Instructions

Follow these four phases in strict order. Do not advance to the next phase if the previous one did not complete correctly.


Phase 1 — Identify the spec

The received argument is: $ARGUMENTS

If $ARGUMENTS is empty:

  • List the files available in specs/ (you already have them above).
  • Ask the user to specify the exact name of the spec.
  • Stop and wait for an answer. Do not continue.

If $ARGUMENTS has a value:

  • Look for the file in specs/. The user may have written the full name (01-mvp-arkanoid), only the number (01), or only the slug (mvp-arkanoid). Try to find the correct file in any of those cases.
  • If you do not find the file, show the available specs and ask the user to correct the name.
  • If you do find it, continue to Phase 2.

Phase 2 — Validate the spec's state

Read the spec file you located in Phase 1 using the Read tool or cat.

In the file's contents, look for the line that contains the spec's state. The header label is typically **Status:** (English) or **Estado:** (Spanish), but it may use any language. Match by position (status line near the top of the spec) and by the surrounding state machine, not by the exact label.

Absolute rule: You can only continue if the state means "Approved" — regardless of the language used.

Treat any of the following (and their equivalents in other languages) as the Approved state and continue:

  • English: Approved
  • Spanish: Aprobado
  • Portuguese: Aprovado
  • French: Approuvé
  • German: Genehmigt
  • Italian: Approvato
  • …or any other language's word that clearly means "approved"

Anything else (Draft / Borrador, In review / En revisión, Implemented / Implementado, Obsolete / Obsoleto, or any unrecognized value) means stop and show the error message below.

State categoryExamples (any language)Action
ApprovedApproved, Aprobado, Aprovado, Approuvé, …Continue to Phase 3.
DraftDraft, Borrador, …Stop. Show the error message below.
In reviewIn review, En revisión, …Stop. Show the error message below.
ImplementedImplemented, Implementado, …Stop. Show the error message below.
ObsoleteObsolete, Obsoleto, …Stop. Show the error message below.
State line not found / unrecognized value—Stop. The file does not follow the expected format. Tell this to the user.

If you are unsure whether a value means "approved", do not assume. Stop and ask the user to clarify or to update the spec to the canonical wording.

Standard error message when the state does not mean Approved:

❌ I cannot implement this spec.

Current state: [STATE FOUND]
I only work with specs whose state means "Approved" (e.g. `Approved`, `Aprobado`,
or the equivalent in another language).

To continue you have two options:
  1. If the spec is ready to be implemented, open it and change the state
     to "Approved" (or the equivalent term your team uses) manually.
     That change is made by the human, not the agent.
  2. If the spec still needs work, use /spec [name] to resume it.

Do not offer alternatives, do not suggest "I can still start if you want". The block is intentional.


Phase 3 — Create the git branch and switch to it

Once you have confirmed the state means Approved:

  1. Check the working tree first. Look at the git status --short output in the session context above. If it is not empty, stop and show the pending changes, then ask:

    ⚠️ There are uncommitted changes in the working tree.
    Switching branches would carry them over. What do you want to do?
      1. Commit or stash them yourself, then re-run this command  (recommended)
      2. Continue anyway — the changes travel to the new branch

    Wait for the answer. Do not stash or commit on the user's behalf unless they explicitly ask for it. If the working tree is clean, skip straight to step 1 without mentioning it.

  2. Derive the branch name from the spec file's full name, without the extension. Format: spec-NN-slug. Examples:

    • 01-mvp-arkanoid.md → branch spec-01-mvp-arkanoid
    • 02-powerups.md → branch spec-02-powerups
  3. Read the AutoCreateBranch flag from the Workflow config shown in the session context above.

    • If the config file does not exist, the value is missing, or the value is unrecognized → treat it as true (the default).
    • Only an explicit false (in any capitalization) disables automatic branch creation.

    If AutoCreateBranch is true (default): proceed without asking.

    • If the branch does not exist: create it with git checkout -b spec-NN-slug.
    • If it already exists: this means previous work is being resumed. Switch to it, read git log --oneline on the branch, and tell the user which steps of the plan already look done and which step you propose to resume from. Commits named spec-NN-step-MM (created when AutoCommitSteps is true) mark exactly which steps are finished. Wait for confirmation on the resume point before implementing anything.
    • In both cases: switch to the branch with git checkout spec-NN-slug and confirm the change was successful before continuing.

    If AutoCreateBranch is false: ask before touching git. Show:

    AutoCreateBranch is set to false.
    Create and switch to the branch spec-NN-slug? [y/N]
    • If the user answers yes: create/switch to the branch exactly as in the true case above.
    • If the user answers no or leaves it empty: do not create any branch. Tell the user you will implement on the current branch (the one shown in the session context above) and ask for explicit confirmation to continue there. Do not improvise — wait for the answer.
  4. Visually confirm to the user the spec is ready and which branch is active:

    ✅ Ready to implement.
    
    Spec:   specs/NN-slug.md
    Branch: spec-NN-slug  (active)   (← or the current branch, if no new branch was created)
    State:  Approved   (← echo back the actual value found in the spec)
  5. Do not start implementing yet. First show the spec summary to the user so they have it fresh. Extract and show:
    • The objective (the line after **Objective:** / **Objetivo:** / equivalent label).
    • The scope (the ## Scope / ## Alcance / equivalent section).
    • The implementation plan (the section with the numbered steps — ## Implementation plan / ## Plan de implementación / equivalent).
    • The acceptance criteria (the checklist — ## Acceptance criteria / ## Criterios de aceptación / equivalent).

Match section headings by meaning, not by exact wording — the spec may be authored in any language.


Phase 4 — Implement step by step

After showing the spec summary, tell the user:

I am going to implement the spec following the implementation plan exactly.
I will pause after each step so you can review the diff.
Each step will be committed as spec-NN-step-MM.   (← only if AutoCommitSteps is true)

Shall we start with Step 1?

Wait for explicit confirmation ("yes", "go ahead", "go", or equivalent). Do not start without it.

Once confirmed, follow these rules during the entire implementation:

Committing is controlled by the AutoCommitSteps flag in the Workflow config shown in the session context above. If the config file does not exist, the value is missing, or the value is unrecognized → treat it as false (the default). Only an explicit true (in any capitalization) enables per-step commits.

  • AutoCommitSteps: false (default) — never commit automatically. Not per step, not at the end. You write the code and show the diff; committing is the user's decision and the user's command. Only commit if they explicitly ask you to.
  • AutoCommitSteps: true — commit each step as soon as it is finished, before pausing for review:
    • Stage only the files you created, modified or deleted in this step: git add -- <file> <file> …. Never use git add -A or git add . — they could sweep in changes that do not belong to the step.
    • Commit with the message spec-NN-step-MM and nothing else (no description, no body). NN is the spec number and MM is the step number from the implementation plan, both zero-padded to two digits. Example: step 3 of 01-mvp-arkanoid.md → spec-01-step-03.
    • If the user asks for adjustments to the step while reviewing it, apply them and fold them into the same commit (git add -- <files> + git commit --amend --no-edit), so each step stays a single commit. Only ever amend the commit of the step currently under review, never an earlier one.
    • If the commit fails (e.g. a pre-commit hook rejects it), stop and show the error. Never bypass hooks with --no-verify.
    • Never push.

One rule above all: implement what the spec says. If something in the spec looks suboptimal to you, mention it as an observation but implement what was agreed. Changes to the spec go into the spec, not into the code by surprise.

Work rhythm:

  • Implement one step of the plan.
  • If AutoCommitSteps is true, commit the step as described above.
  • Show a summary of which files you touched and what you did. If you committed, add the commit line: Committed as spec-NN-step-MM (<short hash>) — the user can review it with git show HEAD.
  • Say: Step N completed. Could you review the diff and let me know if I continue with Step N+1?
  • Wait for confirmation before continuing.

If during the implementation you find an ambiguity the spec does not resolve:

  • Stop.
  • Describe the ambiguity exactly.
  • Present two or three concrete options.
  • Wait for the user's decision.
  • Do not improvise.

If the user asks for something that is out of the spec's scope:

  • Remind them that it is out of this spec's scope.
  • Suggest noting it down for the next spec.
  • Do not implement it on this branch.

When finishing the last step:

✅ All steps of the plan are implemented.

Next step: verify the spec's acceptance criteria one by one.
If they all pass, update the spec's state to "Implemented" (or the equivalent
in your repo's language) and make the final commit before merging this branch.

Summary of expected behavior

/spec-impl 01-mvp-arkanoid

  Phase 1  →  Finds specs/01-mvp-arkanoid.md
  Phase 2  →  Reads the state → "Approved" (or "Aprobado", etc.) → ✅ continues
  Phase 3  →  git checkout -b spec-01-mvp-arkanoid → git checkout spec-01-mvp-arkanoid
              Shows objective, scope, plan and criteria
  Phase 4  →  Implements step by step with pauses
              Ends by reminding to verify the acceptance criteria

/spec-impl 02-powerups  (state: Draft / Borrador)

  Phase 1  →  Finds specs/02-powerups.md
  Phase 2  →  Reads the state → "Draft" → ❌ stops
              Shows the standard error message
              Does not create branch, does not touch code

Branch creation is controlled by the AutoCreateBranch flag in specs/.spec-config.yml. It defaults to true (create the branch automatically, as shown above). Set it to false to make Phase 3 ask [y/N] before creating the branch.

Per-step commits are controlled by the AutoCommitSteps flag in the same file. It defaults to false (never commit). Set it to true to make Phase 4 commit each finished step as spec-NN-step-MM.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.