agentleFS
govctl-orggovctl-org/govctl/.claude/skills/wi-writer/SKILL.md

wi-writer

Skill276 starsChanged 38 days agoMITView on GitHub

Write durable work items with scoped descriptions, testable categorized acceptance criteria, governing references, and risk-matched guards

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 7 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

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

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

    Use govctl <resource> --help for current syntax.

    line 25
  2. Very specific:

    Never put progress, commands run, validation output, review status, temporary blockers, hypotheses, or next actions in description or notes.

    line 32
  3. Distinctive:

    Do not split one outcome into items for mechanical substeps.

    line 34
  4. Distinctive:

    Do not delete a Work Item without explicit user authorization.

    line 35
  5. Distinctive:

    Stop when no governing authority exists to define the acceptance criteria.

    line 37
  6. Very specific:

    Only closure-worthy constraints, durable implementation facts, or reasons an approach should not be retried.

    line 69
  7. Distinctive:

    Create a separate item only for an independently reviewable outcome.

    line 80
  8. Distinctive:

    Prefer the narrowest guard that proves the behavior.

    line 90
  9. Distinctive:

    Run one-off diagnostics directly instead of turning them into guards.

    line 92
  10. Very specific:

    Do not add a criterion that just repeats an effective guard's command success.

    line 93
  11. Very specific:

    Use guard-writer when a reusable check is missing.

    line 97
  12. Distinctive:

    Every criterion is categorized and testable.

    line 103

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

Work Item Writer

A Work Item records one durable execution outcome and how to tell it is done. It is not a specification, a design decision, or a progress journal. This helper owns field quality; the invoking workflow owns code, lifecycle transitions, loops, and VCS operations.

Discovery

govctl work list active
govctl work list queue
govctl work show <WI-ID>
govctl guard list
govctl loop list open

Use govctl <resource> --help for current syntax.

Hard Stops

  • RFCs own obligations, ADRs own design rationale, and Work Items own execution scope. New behavior, validation, storage, compatibility, or lifecycle rules need an RFC; a design choice needs an ADR, not an explanation in the item.
  • Never put progress, commands run, validation output, review status, temporary blockers, hypotheses, or next actions in description or notes.
  • Do not split one outcome into items for mechanical substeps.
  • Do not delete a Work Item without explicit user authorization; hand deletion to the invoking workflow.
  • Stop when no governing authority exists to define the acceptance criteria.

Fields

Description

One concise paragraph: what the task accomplishes, why, and its scope. Do not restate contract language or track progress.

Describe what exists today by its role. Do not name types, functions, fields, or files that do not exist yet: a reader cannot resolve a forward reference, and the implementing agent owns those names. Introduce a planned concept by its role ("a per-clone coordination registry"), not its planned identifier.

Acceptance Criteria

Each criterion is independently testable, describes an observable outcome, and carries a changelog category: add, fix, change, remove, deprecate, security, or chore. Use chore for internal outcomes that stay out of the release changelog. Do not prescribe incidental private structure or planned symbol names.

To correct a criterion, use govctl work edit <ID> "acceptance_criteria[N]" --set <value>. A recognized category prefix updates text and category; other input updates only text; checklist status is kept. Use the .text child path to keep a recognized prefix as literal text, and --tick to change status. Quote every path with brackets. Use --stdin for text containing backticks, $(), or other shell syntax.

Notes

Only closure-worthy constraints, durable implementation facts, or reasons an approach should not be retried. A cancelled item records its reason here. Notes cannot override an RFC or accepted ADR. Transient state belongs in loop rounds or the final response; progress belongs in criterion status.

References And Dependencies

Reference the RFCs that authorize behavior and the ADRs that constrain the approach. Use depends_on only for hard execution order; informational links go in refs.

Create a separate item only for an independently reviewable outcome. Helper extraction, fixtures, file moves, and formatting stay inside the parent. Use a multi-item loop only when the batch has several durable outcomes.

Guards

  • Project default_guards are the intersection of checks every Work Item needs.
  • Work Item required_guards add reusable checks for this item's risk domains, chosen from the changed surface, references, and criteria.
  • Prefer the narrowest guard that proves the behavior; use full suites only for cross-cutting changes.
  • Run one-off diagnostics directly instead of turning them into guards.
  • Do not add a criterion that just repeats an effective guard's command success. A short chore criterion may summarize validation not covered by guards.

Use guard-writer when a reusable check is missing.

Checklist

  • The title is short and action-oriented; the item is one durable outcome.
  • The description is scope, not contract, rationale, or progress.
  • Every criterion is categorized and testable; tick it only when its outcome exists.
  • References give authority for user-visible behavior; dependencies are real ordering.
  • Guards match the item's risk without inflating defaults.
  • govctl check passes after substantive edits.

The invoking workflow moves the item to done once criteria are complete; govctl work move <WI-ID> done runs the effective guards, so do not rerun them just before.

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.