implement-spec

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Implement Spec

Be extremely concise. Sacrifice grammar for the sake of concision.
No em-dashes or en-dashes. Ever.

The owner dispatches; it never edits repo files itself. Deliver the complete
spec or ticket on one branch and leave one PR ready for human review. Workers
load their `agents/*.md` role contracts and use octo-lite skills as guidance.
Workers are the whole mechanism: no role resolver, loop workflow, journal, or
exact-role gate sits on top of them.

## Inputs

Require:

- canonical spec
- spec issue
- target root `AGENTS.md`

A ticket whose behavior the existing spec on main already states needs no
shaping or new acceptance: that spec's commit on main is the spec acceptance
receipt, and the ticket is the spec issue (a spec change goes back to shaping).
The primary issue is the one-node graph: Start step 1 files nothing, and only
filing is skipped. Every worker step still runs: one implementer in its own
worktree, one integrator, one reviewer. The primary issue stays open until merge.

In a repo whose specs are Spec Chat's, a ticket that changes a screen its
spec's mockup set does not draw goes back to shaping, which draws it and
returns the spec to review, before any implementer starts. A screen that must
differ from its accepted mockup goes back the same way before the build
differs (spec `#delivery-mockup`).

A processed human **spec acceptance** (page action **Accept spec**, formerly
called Finish review) permits implementation dispatch under the reviewed
canonical spec. Follow `spec-chat/skill/review-spec/SKILL.md` under
`## Remote hosting lifecycle` for review resource lifetime. It does not accept
the implementation PR, approve a merge, promote to preproduction, or approve
live traffic.

The tickets are a task graph, not ordered steps. The ready frontier contains
every incomplete ticket whose blockers are complete. Keep Linear titles,
descriptions, relations, assignees, and states aligned with reality throughout.
Do not copy ticket or spec prose into agent messages. Send essential absolute
source paths in the message body; artifact metadata alone is insufficient.

The lane owner keeps its lane record current as the lane-record hook in `agents/orchestrator.md` and `spec/domains/octo-lite.spec.html#lane-record` define.

Record the requested handoff in the existing brief. Manual QA readiness means
a usable feature deployment, required dependencies, working account roles and
starting scenarios, with a secure credential pointer and stated limitations.
Do not replace that outcome with exhaustive agent proof. Required spec/target
evidence still applies; human QA, code readiness and acceptance are separate.

## Start

1. After spec acceptance, file the dependency-linked tickets under the spec
   issue as [consent](../octo-lite-github/SKILL.md#consent) allows, else keep
   the graph in the local brief: one outcome each, spec anchors, real blockers
   only. Before filing, read the target's changelog convention (file,
   format, which changes get an entry, by default every change its users can
   see) from its `AGENTS.md` or `CLAUDE.md`, or a rule file one of them points
   to; octo-lite names no changelog path or format. When the lane makes a
   change it logs, give the entry to one ticket (spec `#delivery-changelog`).
2. Read the spec, issue, and enough of the graph to identify the first
   frontier.
3. When exploration would remove duplicated implementation work, spawn one
   optional exploration agent through `herdr-comms`. Give it write access only
   to the lane's notes directory, `$(octo-lite-state)/lanes/<lane record name>-notes/`
   (spec `#delivery-notes`). Its deliverable is concise Markdown notes there,
   linked from the relevant tickets.
4. Continue the draft PR the orchestrator opened while shaping, else create the
   integration branch from the target base and open one draft PR.
   Push, open PRs, and file issues only as
   [consent](../octo-lite-github/SKILL.md#consent) allows; otherwise the lane stays on local
   branches and ends at a local integration head.
   Put `Closes <issue-key>` lines in the PR body for the spec issue and every
   implementation ticket, and one changelog line: `Changelog: <entry title>`,
   or `Changelog: none: <reason>` when the lane makes no change the
   convention logs or the target declares no convention.
5. Before dispatch, run the spec validator, backslash-artifact scan, and
   tag-balance scan. Repo tests run in delivery, never during shaping. Run one short cross-source conflict check: does the spec
   contradict another canonical spec, merged main, or an open PR?

## Herdr workers

Use the verified launch path from `herdr-comms`; inspect help only when that
invocation is unknown or changed. Spawn every exploration,
implementation, merge, review-fix worker through Herdr. Prefer background tabs
and fill available capacity from the current frontier.

Spawn every worker into the owner's space, `--workspace "$HERDR_WORKSPACE_ID"`,
named `<role>-<ticket>` lowercase (`implementer-ann-64`; a lane-wide worker such
as the integrator carries the primary issue key), per spec
`#transport-spawn-name`. Close a worker before reusing its name. Herdr owns
session selection. Spawn Claude workers
(`-- claude`, CLI default model; brief via `herdr-say`); Codex only when the operator
explicitly selects it. Keep the worker-specific nuance: every writer still
gets its own worktree, and only one integrator writes the integration branch.

For each ready ticket:

1. Create a dedicated worktree and branch from the current integration branch.
2. Mark the Linear ticket In Progress only when its worker starts.
3. Spawn a Herdr implementer in that worktree, under the `implementer` role
   contract. Prompt it with pointers to the ticket, spec, target `AGENTS.md`,
   optional research notes, integration branch, and relevant prior commits.
   Name the accepted mockup of each screen the ticket changes: its file in the
   spec's mockup set at the spec acceptance receipt's commit (spec
   `#delivery-mockup`).
   Cite each repo-wide rule the ticket bears on by its marked criterion's spec
   and anchor (spec `#roles-repo-wide-rule`); an `AGENTS.md` line is only a
   pointer to it. The brief of the ticket that owns the changelog entry names
   the convention's file, so its implementer writes the entry in the same PR.
4. The contract declares the skills available to it and the bounds it works in,
   so neither has to be restated here or kept in step by hand. A Claude worker
   loads it with `--agent implementer`; a Codex worker gets it as developer
   instructions from `herdr-spawn --role implementer`.

The worker owns only that ticket, validates it, commits it, and returns the

From varelaseb/octo-lite, Apache-2.0.

More from varelaseb/octo-lite