Spec driven prompt

Spec-Driven Prompt Generation

Generate bounded work unit specs for agent execution using spec-driven development principles.

When to Use

• RAV discussion with user is complete
• Task scope, mode, and expected outcomes are established
• Ready to hand off a discrete work unit to an executor agent

Philosophy

Spec-Driven Development: Each deliverable has matched validation(s). The agent has full implementation freedom within spec bounds. Define what and how to verify, never how to implement.

Failure Attribution: Modern coding agents are capable tools. If a task with clear deliverables and clear validations fails, the spec failed. Debug the spec first.

Bounded Work Units: Each spec represents a discrete, self-contained unit of work. Size varies (small fix to substantial feature), but boundaries are always clear. The agent knows exactly when it's done.

Agent Agnostic: The spec structure works across executors: Codex, Claude Code, OpenCode, GeminiCLI, or any capable coding agent. The Execution Environment block captures executor-specific details without polluting the spec itself.

Worklog Closure: Every spec execution produces a matching worklog and is then archived. The spec is not complete until the agent has written the worklog, appended the registry row, and moved the spec into its month archive. This is a deliverable, not optional bookkeeping.

Naming Convention

Specs and worklogs share a naming pattern. Replace spec with worklog to find the matching pair.

Type	Pattern	Example
Spec	YYYY-MM-DD-<repo-short>-spec-NN-topic.md	2026-05-29-ml01ops-spec-01-fleet-inventory-schema.md
Worklog	YYYY-MM-DD-<repo-short>-worklog-NN-topic.md	2026-05-29-ml01ops-worklog-01-fleet-inventory-schema.md

<repo-short> is the controlled short name for the target repo. Use the short already in use by that repo's existing specs and worklogs; the project tracker is the authoritative list. Repo-less or cross-cutting platform work uses infra.

Sequence numbers (NN) are per repo short per date, starting at 01. Two agents working different repos on the same day never coordinate sequence numbers. The worklog mirrors its spec exactly: identical date, repo short, sequence, and topic, with only the spec/worklog token differing. Ad-hoc worklogs that have no spec use sequence 00.

Locations

Artifact	Path
Specs (active queue)	/opt/agents/spec/
Completed specs (archived)	/opt/agents/spec/<YYYY-MM>/
Worklogs	/opt/agents/work-logs/
Worklog template	/opt/agents/work-logs/WORKLOG-TEMPLATE-AGENT.md
Work registry	/opt/agents/work-logs/work-registry.csv

The flat spec/ directory holds only active, not-yet-completed specs, so it doubles as the live work queue. On completion the agent archives the spec into a month folder (see step 8). Worklogs are not archived; they stay flat in work-logs/ and are indexed by the registry.

Workflow

1. Confirm RAV Complete

Before generating, verify:

• Task scope is unambiguous
• Mode is selected (Infrastructure / Code / Debug / Documentation)
• Expected outcomes are concrete
• Validation criteria are testable

If any of these are unclear, continue RAV. Do not generate ambiguous specs.

2. Determine Repo Short and Sequence Number

Pick the <repo-short> for the target repo (infra for repo-less platform work). Check existing specs for today's date under that short, in both the active queue and the current month archive:

ls /opt/agents/spec/YYYY-MM-DD-<repo-short>-spec-* /opt/agents/spec/YYYY-MM/YYYY-MM-DD-<repo-short>-spec-* 2>/dev/null

Use the next available sequence number for that repo short on that date.

3. Write Frontmatter

Specs use YAML frontmatter wrapped in an HTML comment block. This is consistent with all project documentation.

Required fields: title, description, author, date, version, status, tags (type: specification, domain from tagging strategy, tech list), related_documents.

4. Define Objective

One paragraph stating the concrete "done" state. Write it as a verifiable end condition, not a process description. The reader should know exactly what the world looks like when this spec is complete.

5. Set Execution Environment

Two-column table capturing where and how the spec runs. This is the only section that changes between executors.

Required fields: Host, OS, Hardware (when relevant), Agent Runtime. Optional fields vary by task: Global Env, GPU Driver, existing software versions, network constraints.

Include DEBIAN_FRONTEND=noninteractive for any spec that may touch apt.

6. Define Scope

Four subsections with explicit boundaries:

Subsection	Purpose
Pre-existing (do not create)	Things the spec assumes already exist. Prevents the agent from recreating infrastructure.
Modify	Files, directories, and services the agent can change. This is the write boundary.
Reference	Context to consult but not modify. AGENTS.md, existing docs, other specs.
Do not touch	Explicit exclusions. Network interfaces, running services, other repos.

When targeting Codex, the Modify list aligns with sandbox permissions. For Claude Code, scope boundaries compensate for the lack of worktree isolation.

7. Build Deliverables and Validations

Each deliverable gets:

• A descriptive heading (#### Deliverable N: Title)
• Prose paragraph(s) stating what to build and key decisions
• A validation checklist of checkbox items

Validations are declarative and testable: commands that return expected output, files that exist with specific properties, services that respond on specific ports. Never "verify it works" without specifying how.

8. Add Closeout Deliverable (Worklog and Archive)

The final deliverable in every spec is closeout. This is non-negotiable.

#### Deliverable N: Worklog and archive

Write a worklog following the template at `/opt/agents/work-logs/WORKLOG-TEMPLATE-AGENT.md`. Filename mirrors this spec: `YYYY-MM-DD-<repo-short>-worklog-NN-topic.md`. Append a summary row to `/opt/agents/work-logs/work-registry.csv`. Then move this spec file into its month archive `/opt/agents/spec/<YYYY-MM>/` (the `YYYY-MM` taken from this spec's filename date), creating the directory if it does not exist.

Validation:
- [ ] Worklog exists at `/opt/agents/work-logs/YYYY-MM-DD-<repo-short>-worklog-NN-topic.md`
- [ ] Worklog frontmatter has all required fields populated
- [ ] Work registry CSV has a new row matching this execution
- [ ] This spec now lives under `/opt/agents/spec/<YYYY-MM>/` and no longer in the active queue

The registry stores filenames, not paths, so archiving the spec does not break its registry reference.

9. Set Constraints

Task-specific restrictions. Keep these minimal, meaningful, and tied to real risks. Common constraints:

• Network interface protection (additive only, never touch management interfaces)
• DEBIAN_FRONTEND=noninteractive for apt operations
• Service isolation (don't restart unrelated services)
• Path restrictions (stay within specified directories)

10. Define Execution Order

Numbered list of deliverables in dependency order. Some deliverables must complete before others can begin (e.g., certificate must exist before nginx can reference it). The closeout deliverable (worklog and archive) is always last.

11. Add Notes

Optional section for context that doesn't fit elsewhere: historical decisions, architectural rationale, gotchas from previous attempts, relationships to other specs. Keep it relevant; agents read this section and it costs tokens.

12. Generate

Use the template from assets/template.md.

Executor Notes

Codex (Default)

• Each spec maps to one Codex thread with its own worktree
• Sandbox restricts filesystem writes to the working directory by default
• Runs PowerShell-native on Windows; WSL available if needed
• Cloud or local execution; note preference when it matters
• Thread context does not persist between specs; include all needed context
• codex exec supports non-interactive automation for cron-driven tasks

Claude Code

• Runs in terminal; full filesystem access unless constrained by rules
• AGENTS.md provides project context automatically
• No worktree isolation by default; scope boundaries matter more
• Interactive sessions cannot report token usage; --output-format=stream-json enables it for non-interactive runs

OpenCode (aoe)

• Persistent tmux sessions on ML01, one per repo
• GLM-4.7 via Z.ai is the default model
• Full filesystem access on ML01
• Token tracking via ccusage/opencode package when configured

GeminiCLI

• Long context window, good for large file analysis
• Reads AGENTS.md natively
• Free tier on Gemini 2.5 Pro; generous allocation

Common Failure Modes

Problem	Symptom	Fix
Vague deliverable	Agent delivers wrong thing	Make output concrete and specific
Unverifiable validation	Agent can't confirm completion	Add testable, declarative criteria
Missing scope boundary	Agent modifies unintended files	Explicit Modify and Do-not-touch lists
Skipped RAV	Prompt has ambiguities	Return to discussion, don't guess
Over-specified implementation	Agent fights the spec	Remove "how", keep only "what"
Missing context	Agent asks clarifying questions or guesses wrong	Include all needed context in spec
Missing Execution Environment	Agent wastes cycles discovering the host	Fill the table completely
Wrong or missing repo short	Filename collides or misfiles	Match the short the repo already uses; infra for repo-less
No worklog written	Execution untracked	Closeout deliverable is mandatory
Spec left in active queue	Completed work clutters the queue	Archive step in closeout is mandatory
Scope creep in notes	Agent treats notes as deliverables	Keep notes informational, not actionable

Scope Limits

This skill produces a structured spec. That is its entire deliverable.

Out of scope:

• Reviewing the agent's completion report
• Commit/PR decisions
• Code review loop
• Worklog template maintenance (see /opt/agents/work-logs/README.md)