agentleFS
Sign inStart free
MageByte-ZeroMageByte-Zero/spec-superflow/skills/spec-writer/SKILL.md

spec-writer

Skill875 starsChanged 4 months agoMITView on GitHub

Create or refine spec-superflow planning artifacts. Invoke when the change is understood well enough to write proposal.md, specs/, design.md, and tasks.md.

25 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use security-reviewer and learn.

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.
  • JeffallanSkill

    security-reviewer

    Identifies security vulnerabilities, generates structured audit reports with severity ratings, and provides actionable remediation guidance. Use when conducting security audits, reviewing code for vulnerabilities, or analyzing infrastructure security. Invoke for SAST scans, penetration testing, DevSecOps practices, cloud security reviews, dependency audits, secrets scanning, or compliance checks. Produces vulnerability reports, prioritized recommendations, and compliance checklists.

    Also in 3 projects that use this

  • genomewalkerSkill

    learn

    Learn from web sources, generate SKILL.md, and store key patterns in soul memory. Trigger keywords: learn, skill-gen, web-learn, documentation, tutorial.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 21 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before executing a CLI line below, replace its leading SSF with node "<plugin-root>/scripts/spec-superflow.mjs".

    line 10
  2. Distinctive:

    Create or refine planning artifacts when the change has moved beyond exploration.

    line 16
  3. Very specific:

    Add specs/ for durable behavior scenarios: each requirement uses SHALL/MUST and a #### Scenario: with WHEN/THEN, grouped under the …

    line 28
  4. Distinctive:

    Add design.md for real technical decisions: choice, rationale, alternatives, consequences and risks.

    line 29

“Common” is measured: kept by at least 6 in 10 of the 21 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

Spec Writer

Bundled runtime

Before executing a CLI line below, replace its leading SSF with node "<plugin-root>/scripts/spec-superflow.mjs"; <plugin-root> is the absolute directory two levels above this file. Never run SSF literally or call an ssf from PATH.

Workflow routing

A new request follows this file without loading legacy instructions. For an existing change, inspect the recorded state and receipt/plan (available through SSF workflow show <change-dir> --json and SSF execution show <dir> --json when needed). Current paths are workflow_variant: direct with a valid workflow-selection receipt schema_version: 3, or workflow_variant: planned with an execution plan schema_version: 2. Older receipts (schema 1/2), legacy plans and other recorded variants use the matching section of SSF runtime asset read docs/legacy-workflow.md; follow that section for this change. A direct variant alone is insufficient: legacy Quick/Hotfix/Lightweight can also record it. The internal workflow: full value alone is not a legacy signal. Missing or corrupt state, receipt or a required plan is a recovery problem; preserve evidence rather than reinitialize or downgrade the change.

Create or refine planning artifacts when the change has moved beyond exploration.

New planned changes

For a new request, an expanding direct change, or workflow_variant planned, write proposal.md and tasks.md together without pausing between individual artifacts. Proposal holds the goal, in/out scope, acceptance and risks; tasks holds ordered deliverables and proof commands. Add specs only for behavior needing durable scenarios and design only for unresolved architectural decisions. Do not create execution-contract.md or duplicate the task list in another plan.

Check shared interfaces against the real source once, then self-check the problem, scope, dependencies and proof. Present one approval request only if this concrete plan lacks approval. After approval run SSF workflow start <dir> --path planned --confirm --reason "<user decision>" and continue implementation. No intermediate planning/bridging transitions or independent reader agent. A semantic revision uses the same command after approval; a nonsemantic correction uses execution resync and retains failed-review history.

Artifact checks

  • proposal.md records the problem, in/out scope, acceptance, impact and risks.
  • tasks.md is the only task list: unique numbered checkboxes, dependency order, affected paths or bounded areas, observable outcomes and proof commands. Keep test-cycle details in execution notes rather than repeating the plan.
  • Add specs/ for durable behavior scenarios: each requirement uses SHALL/MUST and a #### Scenario: with WHEN/THEN, grouped under the applicable delta headers.
  • Add design.md for real technical decisions: choice, rationale, alternatives, consequences and risks. Reference existing architecture instead of copying it.

Self-check five questions once: problem, command boundary, invalidation boundary, continuation boundary and document flow. Fix contradictions and missing acceptance evidence before presenting the one concrete plan for approval. Keep existing approval when it still covers that exact plan. After workflow-start records approval, continue to build-executor.

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.

Check your setup, free