spec steering workflow

Use a lightweight spec + steering workflow for long, interruptible, multi-phase tasks that need checkpointed progress, recoverable state, and multi-session c...

Security Scan

The skill is internally coherent: it implements a file-first spec/checkpoint workflow and only reads/writes workspace files and local templates; there are no network calls or secret access requested — but verify how the script resolves the workspace and ensure you trust the location where files will be written.

Purpose & Capability

Name/description match the implementation: templates, rules, and a helper script (scripts/specctl.py) exist to create and manage spec workspaces, checkpoints, handoffs, and archives. No unrelated credentials, binaries, or network access are requested.

Instruction Scope

Runtime instructions direct the agent to read/write files under workspace paths (specs/active, specs/archive, steering/) and to use scripts/specctl.py for operations — this matches the stated purpose. Note: the helper script computes the workspace by walking three parent directories from its own location (script.parents[3]), which is brittle: if the skill is installed in an unexpected path that calculation could point to a different directory than you expect. Confirm the agent's installation layout and sandbox so files are written only where intended.

Install Mechanism

No install spec or remote downloads; this is an instruction-plus-local-code skill. No external packages are fetched and nothing is written to disk at install time beyond the skill artifact itself.

Credentials

Skill declares no required environment variables or secrets and the code shows no network or secret-access behavior. Minor inconsistency: the bundle does not declare a required runtime (python3) even though scripts/specctl.py is a Python script — the platform likely provides an interpreter but you should verify that the agent environment can execute the script.

Persistence & Privilege

always:false and no requests to modify other skills or system-wide configs. The agent is allowed to invoke the skill autonomously (normal default) and the skill will create and manage files under the workspace only.

Assessment

This skill appears to do what it claims: manage long-running specs via files and a local helper script. Before installing, check these points: 1) Confirm your agent runtime has Python available (specctl.py is a Python script). 2) Confirm where the skill will be installed so the script's workspace calculation (script.parents[3]) resolves to the directory you intend — otherwise it may create or modify files outside the expected sandbox. 3) Because the skill writes and updates files under specs/ and steering/, back up any important workspace data and review created files (meta.json, handoff.md, tasks.md) to ensure state is captured as you expect. 4) If you need stronger isolation, run the skill in a restricted workspace or verify filesystem permissions. Overall the footprint is local and file-scoped with no credential or network access, so risks are limited if you validate the workspace and runtime interpreter.

Use this skill when work is long, interruptible, multi-phase, or needs recovery in a new session.

Start or recommend a spec when any of these are true:

• The task is likely to take more than 20 minutes.
• The task has more than one deliverable.
• The task needs staged execution.
• The task is likely to be interrupted.
• The task needs research plus execution.
• The task must survive across sessions.
• The user asks for plan first, then execution.

This skill manages execution state with workspace files:

• specs/active/<spec-id>/
• specs/archive/<spec-id>/
• steering/

Default workflow:

1. Read steering/workflow.md and steering/preferences.md.
2. If resuming, read handoff.md, then tasks.md, then meta.json.
3. Work only on the current batch.
4. After each batch, or every 20-30 minutes, write a checkpoint.
5. Before stopping, update handoff.md and meta.json.

Valid checkpoint types are only:

• done
• blocked
• failed

Do not treat "working on it", "continue", or "in progress" as valid progress reports.

Use {baseDir}/scripts/specctl.py for these operations:

• init <spec-id> --title "<title>" --kind <kind>
• checkpoint <spec-id> --type done|blocked|failed --batch <batch-id> --next "<next action>"
• status <spec-id>
• resume <spec-id>
• validate <spec-id>
• archive <spec-id>
• set-status <spec-id> --status ready|review|completed [--phase <phase>] [--next "<next action>"]
• doctor

Read references only as needed:

• {baseDir}/references/workflow-rules.md for trigger and lifecycle rules
• {baseDir}/references/checkpoint-rules.md for checkpoint requirements
• {baseDir}/references/recovery-rules.md for resume order and stale-state rules
• {baseDir}/references/integration-rules.md for coexistence with other skills
• {baseDir}/references/template-contracts.md for file contracts and required fields

Use templates from {baseDir}/assets/templates/. Keep the skill lean: detailed rules belong in references/, file bodies belong in assets/templates/, and only execution state belongs in workspace specs/ and steering/.