try-works/role-model / .agents/skills/recursive-mode/skills/recursive-spec
recursive-spec
VerifiedApproval-gated, repo-aware requirements/spec authoring for new recursive-mode runs. Use when the user wants help creating a plan, spec, scope, or requirements for work that does not yet have a run, especially prompts like "create a plan", "help me plan", "create a spec", "write requirements", or similar derivatives.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
| agents/openai.yaml | config | 229 B |
| references/patterns.md | markdown | 3.8 KB |
SKILL.md
View on GitHub---
name: recursive-spec
description: 'Approval-gated, repo-aware requirements/spec authoring for new recursive-mode runs. Use when the user wants help creating a plan, spec, scope, or requirements for work that does not yet have a run, especially prompts like "create a plan", "help me plan", "create a spec", "write requirements", or similar derivatives.'
---
# recursive-spec
Use this skill to co-author a repo-aware `00-requirements.md` for a new recursive-mode run.
This skill is for **requirements/spec authoring before implementation starts**. It does not replace `/.recursive/RECURSIVE.md`, and it should not skip ahead to Phase 2 planning or Phase 3 implementation.
## Primary Use Case
Use `recursive-spec` when the user wants help shaping work before a run exists, especially with prompts like:
- `create a plan`
- `help me plan`
- `create a spec`
- `write requirements`
- `spec this out`
- `scope this`
The important signal is **plan/spec language for a new run**, not implementation of an existing run.
## Conversation Contract
When the trigger is detected:
1. First ask whether the user wants help creating a spec for a recursive run.
2. If the user replies positively, ask: `What do you want to do?`
3. Then gather context, read the repo, and co-author the requirements.
Do not jump straight into writing `00-requirements.md` before the user confirms they want spec help.
## Draft Handling Before Approval
Until the user explicitly approves the spec:
- keep the draft outside the repository worktree
- prefer a temporary session artifact or scratch file
- do **not** create `/.recursive/run/<run-id>/`
- do **not** write `00-requirements.md`
If the user rejects the draft, revise it or discard the temporary draft artifact. Do not leave behind a half-approved run folder.
## Required Read Behavior
Before drafting requirements, read:
1. `/.recursive/STATE.md`
2. `/.recursive/DECISIONS.md`
3. `/.recursive/memory/MEMORY.md`
4. relevant memory shards only when they actually matter
5. the most relevant code and tests for the requested area
The skill should be **repo-aware**, not a blind questionnaire. Use the control-plane docs to understand current truth and the codebase to understand actual surfaces, coupled modules, existing tests, and likely boundaries.
## Authoring Flow
Use a guided interview. Ask one focused question at a time when the answer is not already grounded by repo docs or code.
Recommended sequence:
1. Goal and user outcome
2. Task type: feature, bugfix, refactor, migration, investigation
3. Affected subsystem or files
4. In-scope requirements (`R#`)
5. Observable acceptance criteria for each requirement
6. Edge cases, failure paths, and exclusions
7. Constraints, fixed decisions, and boundaries
8. Open unknowns that must be resolved before Phase 0 is locked
Prefer proposing draft wording and asking the user to confirm or correct it rather than asking the user to author the whole document from scratch.
## Quality Rules
Borrow the strongest authoring ideas from contract-first workflows, but keep the output native to recursive-mode:
- start with user intent and desired outcome
- separate fixed decisions from open questions
- define deterministic, observable acceptance criteria
- include exception and failure-path thinking instead of only the happy path
- make boundaries concrete enough to guide later AS-IS analysis and planning
- keep out-of-scope items explicit
Do **not** introduce a separate `.spec` DSL or a second workflow format.
## Output Contract
The finished output should become:
- `/.recursive/run/<run-id>/00-requirements.md`
Use the repository's native Phase 0 requirements structure:
- keep the scaffolded header from `recursive-init`, including Workflow version: `recursive-mode-audit-v2`
- keep the required `## TODO` section and replace placeholder checklist items rather than deleting the heading
- `## Requirements`
- `## Out of Scope`
- `## Constraints`
Within `## Requirements`, each `R#` should include:
- a short title
- a clear description
- observable acceptance criteria bullets
## Run Creation Rule
Do not create the run folder immediately.
1. Draft and refine the requirements with the user first.
2. Keep the draft in a temporary non-repo artifact until approval.
3. Confirm the user approves the spec and that it is complete enough to proceed.
4. Create the run with `scripts/recursive-init.py` or `scripts/recursive-init.ps1`.
5. Replace the scaffolded `00-requirements.md` with the approved requirements content.
This keeps the run artifact grounded in user-approved requirements instead of half-formed notes.
## Routing Awareness
If spec authoring uses delegated critique, delegated review, or any other external model help to shape the draft, re-read:
- `/.recursive/config/recursive-router.json`
- `/.recursive/config/recursive-router-discovered.json`
immediately before choosing that CLI/model, and route through `recursive-router` instead of inventing an ad hoc model choice.
## Boundaries
- Stay focused on `00-requirements.md` authoring for a new run.
- Do not silently convert this into Phase 2 planning.
- Do not start implementation just because the requirements became clear.
- Do not skip code reading when repository structure matters to scope or constraints.
- Do not create a run until the user-approved spec is ready to write.
- Do not write repository requirements artifacts from an unapproved draft.
## References
- `/.recursive/RECURSIVE.md`
- `/.recursive/STATE.md`
- `/.recursive/DECISIONS.md`
- `/.recursive/memory/MEMORY.md`
- `../../references/artifact-template.md`
- `./references/patterns.md`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |