agentleFS
devexpert-iodevexpert-io/harness-starter/.agents/skills/feature-spec/SKILL.md

feature-spec

Skill4 starsChanged 51 days agoMITView on GitHub

Create an implementation-ready specification for one feature from feature_list.json. Use when the user asks to plan a feature, create a feature spec, apply lightweight SDD/spec-driven development, prepare work for another implementation agent, or generate specs/tasks/technical plan from the feature list. If no feature id is provided, select the first dependency-ready feature in feature_list.json order that is neither passing nor accepted.

22 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use changelog and code-review.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • HashiCorpSkill

    changelog

    Add a `.changelog/<PR_NUMBER>.txt` entry for a GitHub Pull Request, commit, and push.

    Also in 4 projects that use this

  • GoogleSkill

    code-review

    Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 9 are distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 20 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    All paths in this skill are relative to the repository root.

    line 10
  2. Distinctive:

    Do not implement code.

    line 15
  3. Distinctive:

    Do not modify application source files.

    line 16
  4. Distinctive:

    Do not generate specs for every feature unless the user explicitly asks after this skill finishes.

    line 17
  5. Very specific:

    Create or update only docs/specs/<feature-id>.md by default.

    line 18
  6. Very specific:

    If the feature id is not provided, select the first feature in feature_list.json order whose status is neither passing nor accepted and …

    line 19
  7. Very specific:

    If a feature is too broad to plan cleanly, stop and recommend splitting it in feature_list.json instead of producing a vague spec.

    line 20
  8. Distinctive:

    Treat the spec as a contract between agents: planner -> implementer -> validator.

    line 21
  9. Distinctive:

    Prefer concrete repository findings over assumptions.

    line 22
  10. Very specific:

    If feature_list.json is missing, stop and tell the user to run the harness-starter skill first.

    line 42
  11. Very specific:

    Use a user-provided feature id when present.

    line 48
  12. Very specific:

    Before planning, verify the feature has enough scope information: id, title, user_visible_behavior, depends_on, and verification.

    line 52
  13. Very specific:

    Create or update docs/specs/<feature-id>.md using references/spec-template.md.

    line 71
  14. Distinctive:

    Keep the spec concise but operational.

    line 90
  15. Distinctive:

    If a persistent E2E command exists and the feature changes user-visible behavior, authentication, authorization, routing, or API flows, the …

    line 101
  16. Distinctive:

    If the spec fails this gate, revise it before reporting completion.

    line 107

“Common” is measured: kept by at least 6 in 10 of the 20 edited versions of this file we could read. “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

Feature Spec

Use this skill to turn one harness feature into an implementation-ready contract for another agent. The output is not a PRD and not implementation code. It is a planning artifact that lets a future implementation session execute with minimal rediscovery, and lets a later validation session judge the result.

All paths in this skill are relative to the repository root.

Hard Rules

  • Plan exactly one feature per run.
  • Do not implement code.
  • Do not modify application source files.
  • Do not generate specs for every feature unless the user explicitly asks after this skill finishes.
  • Create or update only docs/specs/<feature-id>.md by default.
  • If the feature id is not provided, select the first feature in feature_list.json order whose status is neither passing nor accepted and whose depends_on prerequisites are satisfied.
  • If a feature is too broad to plan cleanly, stop and recommend splitting it in feature_list.json instead of producing a vague spec. Rough signal: it needs more than one data model plus one user flow, or the spec would clearly exceed the 100-250 line target.
  • Treat the spec as a contract between agents: planner -> implementer -> validator.
  • Prefer concrete repository findings over assumptions. If something was not inspected, say so.

Inputs To Read First

  1. AGENTS.md
  2. PROGRESS.md
  3. feature_list.json
  4. Existing feature spec if present: docs/specs/<feature-id>.md
  5. Product/discovery docs as needed:
    • CONTEXT.md
    • docs/build-brief.md
    • docs/domain-model.md
    • docs/user-and-access-model.md
    • docs/technical-discovery.md
    • docs/mvp-scope.md
    • DESIGN.md when the selected feature has UI or visual behavior
    • docs/risks-and-open-questions.md
    • docs/adr/*.md
  6. Existing application files relevant to the selected feature. Inspect enough of the repo to identify expected file changes, patterns, commands, and risks.

If feature_list.json is missing, stop and tell the user to run the harness-starter skill first.

Workflow

1. Select The Feature

Use a user-provided feature id when present. Otherwise, choose the first feature in feature_list.json order with status other than passing or accepted whose depends_on prerequisites are satisfied. Prefer an in_progress feature over a not_started feature if one exists.

A dependency is satisfied when the referenced feature id exists and has status accepted. For legacy feature lists, a dependency with status passing may be treated as satisfied only when durable evidence shows independent validator acceptance. If depends_on is absent in an older feature list, treat it as [] for backward compatibility. If the first unfinished features are blocked by dependencies, skip them only when looking for a later dependency-ready feature; report the skipped blockers in the summary.

Before planning, verify the feature has enough scope information: id, title, user_visible_behavior, depends_on, and verification. If not, improve the feature entry only if the user explicitly asked for feature-list maintenance; otherwise stop and report the missing fields.

2. Research The Repository

Investigate how to implement the selected feature in this specific repo:

  • current app/framework state,
  • existing routes, components, modules, tests, scripts, or conventions,
  • relevant data models and migrations,
  • relevant API boundaries,
  • relevant auth/permission patterns,
  • verification commands available today,
  • persistent E2E commands available today, such as pnpm test:e2e, when the feature has user-facing or API-flow behavior,
  • gaps caused by pre-bootstrap or missing infrastructure.

Record inspected files in the spec. Do not pretend to have inspected files that do not exist.

3. Write The Feature Implementation Spec

Create or update docs/specs/<feature-id>.md using references/spec-template.md. If the repo already has accepted specs under docs/specs/, use one as a reference for the right level of detail.

The spec must include:

  • source feature metadata,
  • goal and non-goals,
  • job story or user story,
  • acceptance scenarios in Given/When/Then style,
  • repository research,
  • technical approach,
  • expected file changes,
  • visual design impact when UI is involved,
  • durable documentation impact,
  • implementation plan,
  • implementation tasks,
  • verification plan,
  • evidence to capture,
  • validator checklist.

Keep the spec concise but operational. A good default target is 100-250 lines. If it grows far beyond that, the feature may need splitting.

4. Quality Gate

Before finishing, check:

  • A future implementer can identify exactly what to build without reading this chat.
  • A future validator can decide whether the implementation satisfies the spec.
  • The plan names concrete files or directories where possible.
  • The tasks are ordered and executable.
  • Verification includes commands or manual checks available in the repo's current state.
  • If a persistent E2E command exists and the feature changes user-visible behavior, authentication, authorization, routing, or API flows, the verification plan should include adding/updating focused E2E coverage or explicitly justify why unit/integration coverage is enough.
  • For shell scripts such as init.sh, the spec states whether the script must execute checks, print guidance, start services, or provide modes. The default harness rule is: init.sh executes non-blocking startup/verification checks and must not start long-running dev servers.
  • Durable documentation impact is explicit: ARCHITECTURE.md, CONSTRAINTS.md, AGENTS.md, and other durable docs are each marked create/update/not needed with a reason.
  • Non-goals prevent scope creep.
  • Unknowns are explicit and do not hide blocking ambiguity.

If the spec fails this gate, revise it before reporting completion.

Output Summary

Report:

  • selected feature id,
  • spec path,
  • whether the feature looked correctly sized,
  • key implementation risks,
  • next suggested action: usually hand the spec to an implementation agent.

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.