agentleFS
wisterx-specwisterx-spec/agent-rails/.agents/skills/run-pending-specs/SKILL.md

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.

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
  1. Very specific:

    No project-specific business rules belong in this skill.

    line 19
  2. Very specific:

    Read project.config.json first.

    line 24
  3. Very specific:

    Create agent.signal_dir and agent.delivery_dir if they do not exist.

    line 32
  4. Very specific:

    If work-dir is absent, use the current repository root.

    line 56
  5. Very specific:

    If test-command is absent, follow the commands written inside each task or in ## Acceptance Criteria.

    line 57
  6. Very specific:

    Use find, not shell globs, so empty directories do not produce shell errors:

    line 61
  7. Very specific:

    Look for any matching session-{slug}-*.md in signal_dir.

    line 71
  8. Very specific:

    No pending spec means exit with: All specs completed.

    line 74
  9. Very specific:

    Only run parallel-ok: true specs in parallel when the execution environment explicitly supports independent workers.

    line 83
  10. Very specific:

    If dependency metadata is missing, treat it as depends-on: none and parallel-ok: false.

    line 85
  11. Distinctive:

    Before editing code, read the full target spec and write:

    line 89
  12. Very specific:

    If Unclear Items or Suspected Contradictions is not None, pause for planner clarification.

    line 111
  13. Very specific:

    If only Execution Risks exist, continue and let Dream review them later.

    line 112
  14. Distinctive:

    Do not edit the spec file.

    line 113
  15. Distinctive:

    Use the spec as the source of truth:

    line 117
  16. Distinctive:

    Read every file listed under "must read", "involved files", or equivalent sections.

    line 119
  17. Distinctive:

    After each task, run the task's stated verification command if present.

    line 121
  18. Distinctive:

    Do not modify locked test expectations to make implementation pass.

    line 122
  19. Distinctive:

    Put scratch scripts and diagnostic output under the configured temp directory.

    line 123
  20. Very specific:

    After implementation, invoke .agents/skills/verify-spec/SKILL.md against the current spec.

    line 127
  21. Distinctive:

    If verification returns failures:

    line 129
  22. Distinctive:

    Stop after three failed repair attempts for the same acceptance item.

    line 133
  23. Very specific:

    Write arbitration-{slug}-{timestamp}.md and pause.

    line 134
  24. Very specific:

    Write the live session to signal_dir first so Dream can consume it:

    line 144

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 fieldDefaultMeaning
agent.signal_dirtmp/agent-signalsLive specs, sessions, prereviews, incidents
agent.delivery_dirdocs/agent-runs/deliveryArchived spec/session/prereview bundles
agent.management_dirdocs/agent-runs/managementDream and Analyzer management output

Create agent.signal_dir and agent.delivery_dir if they do not exist.

File Contract

File patternMeaning
{signal_dir}/spec-{slug}-{YYYYMMDD_HHMMSS}.mdPlanner-authored implementation spec
{signal_dir}/prereview-{slug}-{YYYYMMDD_HHMMSS}.mdExecutor feasibility review before implementation
{signal_dir}/session-{slug}-{YYYYMMDD_HHMMSS}.mdExecutor completion summary and Dream signal
{signal_dir}/arbitration-{slug}-{YYYYMMDD_HHMMSS}.mdManual 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 test

If 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 | sort

For each spec:

  1. Extract slug.
  2. Look for any matching session-{slug}-*.md in signal_dir.
  3. Mark as DONE if a session exists, otherwise PENDING.

No pending spec means exit with: All specs completed.

Step 2: Select Execution Order

For all pending specs:

  1. Read **depends-on**.
  2. A dependency is satisfied when session-{depends-on}-*.md exists in signal_dir or in delivery_dir/{depends-on}/session.md.
  3. Execute serial specs first.
  4. Only run parallel-ok: true specs 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, proceed

Rules:

  • If Unclear Items or Suspected Contradictions is not None, pause for planner clarification.
  • If only Execution Risks exist, 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:

  1. Read every file listed under "must read", "involved files", or equivalent sections.
  2. Implement tasks in the order specified by the spec.
  3. After each task, run the task's stated verification command if present.
  4. Do not modify locked test expectations to make implementation pass.
  5. 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:

  1. Fix implementation.
  2. Re-run the failing check.
  3. Stop after three failed repair attempts for the same acceptance item.
  4. Write arbitration-{slug}-{timestamp}.md and pause.

Step 6: Archive And Write Session

Archive into delivery_dir/{slug}/:

  • spec.md
  • prereview.md if present
  • session.md after 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
- None

The session is the durable signal. If no session is written, Dream must treat the execution as invisible.

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.