run-pending-specs
Skill2 starsChanged 7 months agoMITView on GitHub
Discover pending implementation specs, execute them in dependency order, verify acceptance criteria, archive the spec, and write a session signal for Dream.
In this repository26 other files it gives its agents.
- advise-tech-stackSkill
- commit-with-affectsSkill
- db-dev-guideSkill
- export-db-indexesSkill
- frontend-dev-guideSkill
- frontend-ux-evaluatorSkill
- generate-pr-descriptionSkill
- generate-test-from-impactSkill
- generate-test-skeletonSkill
- lock-global-conventionsSkill
- plan-component-hierarchySkill
- plan-page-mapSkill
- proposal-reviewSkill
- propose-workflow-improvementsSkill
- pr-self-reviewSkill
- record-decisionSkill
- review-guardrailsSkill
- run-testsSkill
- scan-bundle-bloatSkill
- scan-code-hygieneSkill
- scan-dead-routesSkill
- scan-frontend-qualitySkill
- scan-orphan-componentsSkill
- scan-unused-exportsSkill
- sync-llm-contextSkill
- verify-specSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
24 rules. About 0 are common, 9 are distinctive, and 15 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
15
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
No project-specific business rules belong in this skill.
- Very specific: line 24
Read project.config.json first.
- Very specific: line 32
Create agent.signal_dir and agent.delivery_dir if they do not exist.
- Very specific: line 56
If work-dir is absent, use the current repository root.
- Very specific: line 57
If test-command is absent, follow the commands written inside each task or in ## Acceptance Criteria.
- Very specific: line 61
Use find, not shell globs, so empty directories do not produce shell errors:
- Very specific: line 71
Look for any matching session-{slug}-*.md in signal_dir.
- Very specific: line 74
No pending spec means exit with: All specs completed.
- Very specific: line 83
Only run parallel-ok: true specs in parallel when the execution environment explicitly supports independent workers.
- Very specific: line 85
If dependency metadata is missing, treat it as depends-on: none and parallel-ok: false.
- Distinctive: line 89
Before editing code, read the full target spec and write:
- Very specific: line 111
If Unclear Items or Suspected Contradictions is not None, pause for planner clarification.
- Very specific: line 112
If only Execution Risks exist, continue and let Dream review them later.
- Distinctive: line 113
Do not edit the spec file.
- Distinctive: line 117
Use the spec as the source of truth:
- Distinctive: line 119
Read every file listed under "must read", "involved files", or equivalent sections.
- Distinctive: line 121
After each task, run the task's stated verification command if present.
- Distinctive: line 122
Do not modify locked test expectations to make implementation pass.
- Distinctive: line 123
Put scratch scripts and diagnostic output under the configured temp directory.
- Very specific: line 127
After implementation, invoke .agents/skills/verify-spec/SKILL.md against the current spec.
- Distinctive: line 129
If verification returns failures:
- Distinctive: line 133
Stop after three failed repair attempts for the same acceptance item.
- Very specific: line 134
Write arbitration-{slug}-{timestamp}.md and pause.
- Very specific: line 144
Write the live session to signal_dir first so Dream can consume it:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
Run Pending Specs
Purpose
This skill turns a reviewed implementation spec into an executable handoff. It is designed for a planner/executor split:
- Planner writes a structured
spec-*.md. - Executor reads and implements the spec.
- Executor writes
session-*.md. - Dream later reads the session as the durable signal of what actually happened.
No project-specific business rules belong in this skill. Project rules must come from
project.config.json, docs/conventions.md, docs/lessons/, and the spec itself.
Paths
Read project.config.json first. Use these defaults when fields are missing:
| Config field | Default | Meaning |
agent.signal_dir | tmp/agent-signals | Live specs, sessions, prereviews, incidents |
agent.delivery_dir | docs/agent-runs/delivery | Archived spec/session/prereview bundles |
agent.management_dir | docs/agent-runs/management | Dream and Analyzer management output |
Create agent.signal_dir and agent.delivery_dir if they do not exist.
File Contract
| File pattern | Meaning |
{signal_dir}/spec-{slug}-{YYYYMMDD_HHMMSS}.md | Planner-authored implementation spec |
{signal_dir}/prereview-{slug}-{YYYYMMDD_HHMMSS}.md | Executor feasibility review before implementation |
{signal_dir}/session-{slug}-{YYYYMMDD_HHMMSS}.md | Executor completion summary and Dream signal |
{signal_dir}/arbitration-{slug}-{YYYYMMDD_HHMMSS}.md | Manual arbitration request after repeated verification failure |
Slug extraction removes the spec- prefix and a trailing -YYYYMMDD_HHMMSS.md timestamp.
Required Spec Metadata
Each spec should include these machine-readable fields near the top:
**depends-on**: none
**parallel-ok**: false
**work-dir**: /absolute/path/to/project
**test-command**: npm testIf work-dir is absent, use the current repository root.
If test-command is absent, follow the commands written inside each task or in ## Acceptance Criteria.
Step 1: Scan Pending Specs
Use find, not shell globs, so empty directories do not produce shell errors:
SIGNAL_DIR="${SIGNAL_DIR:-tmp/agent-signals}"
find "$SIGNAL_DIR" -maxdepth 1 -name "spec-*.md" -type f 2>/dev/null | sortFor each spec:
- Extract slug.
- Look for any matching
session-{slug}-*.mdinsignal_dir. - Mark as
DONEif a session exists, otherwisePENDING.
No pending spec means exit with: All specs completed.
Step 2: Select Execution Order
For all pending specs:
- Read
**depends-on**. - A dependency is satisfied when
session-{depends-on}-*.mdexists insignal_diror indelivery_dir/{depends-on}/session.md. - Execute serial specs first.
- Only run
parallel-ok: truespecs in parallel when the execution environment explicitly supports independent workers.
If dependency metadata is missing, treat it as depends-on: none and parallel-ok: false.
Step 3: Prereview
Before editing code, read the full target spec and write:
## Prereview - {slug} - {timestamp}
**Executor feasibility review**: identifies execution blockers only. It does not redesign the spec.
### Unclear Items
- None
### Suspected Contradictions
- None
### Execution Risks
- None
### Decision
- [ ] No blockers, proceedRules:
- If
Unclear ItemsorSuspected Contradictionsis notNone, pause for planner clarification. - If only
Execution Risksexist, continue and let Dream review them later. - Do not edit the spec file.
Step 4: Execute The Spec
Use the spec as the source of truth:
- Read every file listed under "must read", "involved files", or equivalent sections.
- Implement tasks in the order specified by the spec.
- After each task, run the task's stated verification command if present.
- Do not modify locked test expectations to make implementation pass.
- Put scratch scripts and diagnostic output under the configured temp directory.
Step 5: Verify Acceptance
After implementation, invoke .agents/skills/verify-spec/SKILL.md against the current spec.
If verification returns failures:
- Fix implementation.
- Re-run the failing check.
- Stop after three failed repair attempts for the same acceptance item.
- Write
arbitration-{slug}-{timestamp}.mdand pause.
Step 6: Archive And Write Session
Archive into delivery_dir/{slug}/:
spec.mdprereview.mdif presentsession.mdafter writing it
Write the live session to signal_dir first so Dream can consume it:
## Spec
- {original spec path}
- Archived: {delivery_dir}/{slug}/spec.md
## Completed Tasks
- Task A: {files changed and behavior delivered}
## Verification Results
- {paste verify-spec output: ✓ / ✗→✓ / ○}
## Problems Encountered
- None
## Deviations From Spec
- Fully followed the spec
## Dream Candidates
- NoneThe session is the durable signal. If no session is written, Dream must treat the execution as invisible.
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
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.

