rmds

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# ReadMe Desired State

Run this workflow only when the user explicitly invokes `$rmds`.

Treat the user's desired behavior and the current public README as product intent. The finished
README must read like current documentation from a world where the requested work is complete. It
is the document that ReadMe Driven Development can later reconcile with the implementation.

## Choose the mode

### Normal mode

Use normal mode for `$rmds` and every explicit invocation that does not say `clarify`.

- Never enumerate, search, or read any part of `.rmdd/`.
- Treat prior RMDD or RMDV reports in conversation as non-authoritative implementation context.
- Incorporate an earlier report only when the user explicitly adopts its substance as desired
  behavior.

### Clarify mode

Use clarify mode only when the user explicitly invokes `$rmds clarify`.

1. Find the project root. Use the Git work-tree root when available; otherwise use the nearest
   ancestor containing `README.md`.
2. Read the complete current root README.
3. Select exactly one review source. When the user names an older review, resolve that reference
   directly and do not read `.rmdd/rmdv/latest`. Otherwise, read `.rmdd/rmdv/latest`. Treat the
   selected `<run-id>/<review-number>.md` value as relative to `.rmdd/rmdv/`, canonically resolve it
   strictly within that directory, and reject absolute paths, project-root-relative prefixes,
   traversal, symlink, or junction escapes.
4. Never enumerate, search, or read `.rmdd/rmdd/`.
5. Treat the RMDV review as advice about clarity, not as product intent or implementation
   authority.
6. Apply only advice that still fits the current README and the user's original desired outcome.

When no readable review exists, report that clarify mode has no RMDV advice to use and leave the
README unchanged. When the review refers to an older README, inspect the current wording and apply
only advice that remains relevant.

Clarify product behavior, defaults, boundaries, examples, or limitations where readers need them.
Do not rewrite the desired future to excuse unfinished code. If RMDV found implementation work and
no documentation ambiguity, leave the README unchanged and say that RMDD should continue the
implementation.

## Understand the request and project

1. Find the project root and read its agent instructions.
2. Read the complete root README.
3. In normal mode, inspect current Git changes when Git is available. Outside Git, work from the
   current document without requiring history.
4. Read nearby project files or linked local documentation only when they help preserve established
   names, commands, behavior, or context.
5. Build an internal requirements inventory from the user's request. Preserve every behavior,
   constraint, exception, example, uncertainty, and protected literal that belongs in public
   documentation.
6. Identify current README statements that the desired state changes or makes obsolete.

When no README exists, normal mode may create one that fits the project. Clarify mode requires an
existing README and review.

## Write the desired state

Edit the README directly. Keep the work documentation-only unless the user explicitly asks for
another artifact.

- Describe requested behavior as available now. Prefer present tense.
- Avoid roadmap language such as "will," "planned," "proposed," "TODO," or "once implemented."
- Do not mention RMDS, RMDD, RMDV, the prompt, run status, or implementation progress in the
  README.
- Preserve useful structure, voice, examples, badges, links, and terminology.
- Make the smallest coherent change that lets the document read naturally as a whole.
- Replace or remove claims that contradict the desired state. Leave unrelated content alone.
- Include concrete commands, examples, configuration, and limitations when readers need them.
- Do not invent unsupported guarantees, measurements, compatibility claims, or internal details.
- Prefer revising an existing passage over adding a new section solely to hold clarification.

The result must look like a real public README, not a specification or progress report. Do not add
requirement IDs, acceptance checklists, implementation plans, status markers, or custom syntax.

## Place features naturally

Work behavior into the sections where a finished project would explain it: overview, features,
quick start, usage, configuration, examples, or limitations. Explain enough observable behavior
for a reader to understand and use it. Keep internal architecture and task breakdowns out unless
they already serve the README's public purpose.

## Describe bug fixes as resolved

Update the README's main behavior descriptions so corrected behavior is the current truth. Use a
changelog entry only when the README already has that convention or the resolution deserves public
history. Keep user-visible outcomes and omit debugging history.

## Review the complete README

Before finishing:

1. Re-read the complete README as a new visitor.
2. Confirm the requested product state is clear, usable, and consistent.
3. Compare the result with the requirements inventory or the still-relevant clarify advice.
4. Confirm the edit introduced no unsupported claims and no accidental code changes.
5. Inspect the final documentation diff when Git is available; otherwise compare the final README
   with the starting content.

Report the README created or changed, summarize how desired state was expressed, and identify any
ambiguity that could not be represented accurately. Keep implementation progress out of the
README.

From Mattie/mattie_skills, MIT.

More from Mattie/mattie_skills