Skip to content

ADR-321: Implement instance mode in spec-first-draft and /spec forwarding #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jodavis-claude wants to merge 2 commits into
base: feature/ADR-316-harvest
Choose a base branch
from
Open

ADR-321: Implement instance mode in spec-first-draft and /spec forwarding #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ad8c239
ADR-321: commands/spec.md documents and forwards the using <playbook>…
ElwoodMoves Jul 15, 2026
6f7620c
ADR-321: spec-first-draft instance mode drafts from a playbook's spec…
ElwoodMoves Jul 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 12 additions & 3 deletions plugins/dev-team/commands/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
description: >
Use when writing a complete new spec for a feature or GitHub issue.
Guides through context gathering, first draft, iterative refinement, readiness review, and task breakdown.
argument-hint: <work-item-id | #issue | feature name and description>
argument-hint: <work-item-id | #issue | feature name and description> [using <playbook>]
---

Use this skill when:
Expand All @@ -15,7 +15,13 @@ You are writing a complete new spec, working with the user to refine the spec, b

### 1 — Resolve the feature brief

Use the `identify-project-work-items` skill to resolve the argument to a `work-item-id` and `work-item-type`, then fetch the work item:
Parse `$ARGUMENTS` for a trailing or embedded `using <playbook-reference>` — a path or a bare

@jodavis-claude jodavis-claude Jul 16, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor correctness/fault-tolerance note (non-blocking): stripping a using <playbook-reference> that can appear "trailing or embedded" anywhere in $ARGUMENTS risks silently mangling a legitimate feature brief that happens to contain the ordinary English word "using" (e.g. "notification service using webhooks for delivery") — there'd be no error, just a quietly wrong brief and a spurious playbook-resolution attempt. This matches the spec's own literal /spec ... using <playbook> wording, so it's not a defect introduced here, but consider tightening the guidance to prefer a trailing match and/or require the following token look like a bare skill name or path (no spaces) before stripping, to reduce false positives from conversational free text.

installed-skill name — and strip it out before resolving the rest; this may also be given
conversationally rather than as a literal `using` clause. If found, carry `<playbook-reference>`
forward unresolved — `spec-first-draft` resolves it itself in Step 2 below, per
`playbook-contract`'s bare-name resolution order.

Use the `identify-project-work-items` skill to resolve the remaining argument text to a `work-item-id` and `work-item-type`, then fetch the work item:

| `work-item-type` | Action |
|---|---|
Expand All @@ -27,7 +33,10 @@ If the work item does not exist, tell the user and stop.

### 2 — Write the first draft

Use the `spec-first-draft` skill with the feature brief to gather context from docs, source code, and the user, and write the draft spec file.
Use the `spec-first-draft` skill with the feature brief — and the playbook reference from Step 1,
if one was detected — to gather context from docs, source code, and the user, and write the
draft spec file. When a playbook reference is present, `spec-first-draft` drafts in instance
mode instead of its default flow.

**PAUSE — wait for the user to review the draft.**

Expand Down
18 changes: 17 additions & 1 deletion plugins/dev-team/skills/spec-first-draft/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,18 @@ user-invocable: false
description: >
Use when writing a first draft of a complete new spec or a new part of an existing spec.
Gathers context from docs, source code, and the user, then writes the draft to a _spec_*.md file.
argument-hint: <feature brief | work-item-id | spec-file-path>
In instance mode (a playbook reference supplied), drafts a thin instance spec from that
playbook's spec-template.md instead of the default template.
argument-hint: <feature brief | work-item-id | spec-file-path> [playbook reference]
---

Use this skill when:
- You are writing a first draft of a complete new spec or a new part of an existing spec
- A playbook reference (a path or bare name) was supplied — draft a thin instance spec from that
playbook's `spec-template.md` instead of the default template (instance mode)

Use the `playbook-contract` skill for: the playbook directory contract and bare-name playbook
resolution order. This skill cites those definitions — it does not restate them.

## Steps

Expand Down Expand Up @@ -38,6 +45,15 @@ Determine the spec file location: the `_spec_*.md` lives next to the code it des

Name: `_spec_<FeatureName>.md` in PascalCase.

**Instance mode.** If a playbook reference (a path or a bare name) was supplied when this skill

@jodavis-claude jodavis-claude Jul 16, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking, flagged for confirmation rather than a defect: the spec's "Explicit trigger, explicit naming" Key Design Decision text says the playbook's step list also feeds the drafted spec's own ## Component Breakdown table, but this instance-mode implementation only substitutes template sections and stamps the header. That's the narrower scope the task's own exit criteria and the pre-built RUN.md checklist actually gate, per the task brief's recommendation, so I'm not blocking on it here — just surfacing it again so the user/spec owner can confirm whether Component Breakdown seeding belongs in this task, a later one (e.g. ADR-322), or should be dropped from the spec text.

was invoked, resolve it per `playbook-contract`'s bare-name resolution order (cite, don't
restate). Once resolved, read the playbook directory's `spec-template.md` and use its own
sections as the draft's body in place of the default `## Overview` through `## Related Docs`
sections below. Keep the header block's `> **Status:**` and `> **Design doc:**` lines unchanged,
and add one more line — `> **Playbook:** <name or path>` — stamping the resolved playbook
reference into the header. If no playbook reference was supplied, use the default structure
below unchanged — instance mode is additive, never the default path.

Write the file using this structure:

---
Expand Down
Loading