A set of skills for maintaining developer documentation (README.md and docs/) as AS IS documentation — describing the actual implementation, not future plans — plus a skill for hardening OpenSpec proposals against ambiguity before implementation.
Works standalone or alongside OpenSpec, Superpowers and spec-kit.
Purpose: Create or fully rebuild README.md and docs/ from scratch.
When to use:
- No README.md exists
- Documentation is severely outdated
- Full architectural resync is needed
- You need to document system architecture for the first time
What it does:
- Scans the codebase to understand structure, entry points, core logic
- Generates README.md (50–200 lines) with: overview, architecture, key decisions, module map, interaction flow, getting started
- Creates
docs/folder for large projects with detailed architecture, per-module docs, ADRs, and interaction flows
Example invocation:
"Create developer documentation"
"We need a README from scratch"
"Document the system architecture"
Purpose: Incrementally update README.md and docs/ after code changes.
When to use:
- A commit or PR is complete
- README has grown beyond 200 lines and needs restructuring
- OpenSpec changes were applied and need to be reflected in docs
- You need to keep docs in sync with the actual code
What it does:
- Detects changes (uncommitted changes, last commit, or user-specified range)
- Updates only affected sections (new modules, API changes, dependencies, architectural changes)
- Splits README into docs/ if it exceeds 200 lines
- Creates ADRs for new architectural decisions
Example invocation:
"Update README after the last commit"
"Sync docs with recent changes"
"README is too large, split it"
"Actualize docs after OpenSpec changes"
Purpose: Deepen a specific section of existing documentation through code analysis.
When to use:
- A documentation section is too brief, vague, or incomplete
- User wants to expand/elaborate/flesh out a specific part of docs
- A module doc needs more detail about internal mechanics, data flow, or rationale
Required input: User must specify which section to enhance.
What it does:
- Analyzes relevant source code to identify patterns, data flows, design decisions
- Detects gaps between current docs and actual implementation
- Expands the section with concrete details grounded in code
- Preserves existing doc structure — only deepens the target section
Example invocation:
"Expand the architecture section in README"
"The authentication module docs are too brief, elaborate"
"Enhance docs/modules/payments.md — focus on the webhook flow"
Purpose: Review OpenSpec proposal artifacts (created via /opsx-propose) to find ambiguities, vague wording, and gaps that leave a model "room for creativity" — then resolve every finding with the user before implementation.
When to use:
- A change in
openspec/changes/<name>/has generated artifacts (proposal.md, design.md, tasks.md, specs/) - Before running
/opsx-apply— to harden the spec - You need deterministic implementation: any model implementing the spec should produce roughly the same code
What it does:
- Scans all artifacts against a 12-category ambiguity taxonomy (vague qualifiers, missing contracts, implicit decisions, open options, unstated edge cases, etc.)
- Cross-checks artifacts for contradictions and scope drift
- Groups findings by severity (blocker / major / minor) and asks clarifying questions with concrete interpretation options
- Writes the user's answers back into the artifacts and re-scans until no statement has two reasonable interpretations leading to different code
Example invocation:
"Check the proposal for ambiguities"
"Review openspec/changes/add-user-auth before apply"
"I want any model to write the same code from this spec"
Type: skill, universal — checks against the RULES defined in the environment (global rules files, project AGENTS.md/README.md), not hardcoded ones.
Purpose: Verify compliance with environment-defined RULES in uncommitted changes — or across the whole project on request. Also detects typical LLM mistakes.
When to use:
- Before committing — check the current diff against the rules
- After an LLM-generated implementation — catch overengineering and dead abstractions
- You need a full-project rules audit
What it does:
- Determines scope:
git diffby default;/rules-check --allor explicit paths for a wider audit - Reads
README.mdand rules sources to detect project type/stack and applies only relevant rules - Checks compliance with the RULES defined in the environment — no hardcoded rules
- Detects typical LLM mistakes:
- Overengineering — "could the same code be shorter and clearer?"
- Orphan functions — functions used once and only a few lines long; for each function it answers "why was this extracted?" and evaluates whether the extraction is justified
- Missing "why" docs — modules and functions without a purpose description
- Reports a scorecard and prioritized findings (CRITICAL / WARNING / SUGGESTION) with
file:linereferences and concrete fixes
Example invocation:
/rules-check
/rules-check --all
/rules-check src/app