From ad8c23910403cb0fdc90f0e236f8b15fe459077a Mon Sep 17 00:00:00 2001 From: Claude on behlaf of jodavis Date: Wed, 15 Jul 2026 23:54:36 +0000 Subject: [PATCH 1/2] ADR-321: commands/spec.md documents and forwards the using argument Adds a Step 1 parsing rule that detects and strips a trailing/embedded 'using ' (path or bare name) from $ARGUMENTS before resolving the feature brief, and forwards it to spec-first-draft in Step 2 so instance mode can resolve it per playbook-contract's bare-name resolution order. --- plugins/dev-team/commands/spec.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/plugins/dev-team/commands/spec.md b/plugins/dev-team/commands/spec.md index 910a131..decb123 100644 --- a/plugins/dev-team/commands/spec.md +++ b/plugins/dev-team/commands/spec.md @@ -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: +argument-hint: [using ] --- Use this skill when: @@ -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 ` — a path or a bare +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 `` +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 | |---|---| @@ -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.** From 6f7620ca185d8b7ac3d49cd70b702f2696d1f311 Mon Sep 17 00:00:00 2001 From: Claude on behlaf of jodavis Date: Wed, 15 Jul 2026 23:57:09 +0000 Subject: [PATCH 2/2] ADR-321: spec-first-draft instance mode drafts from a playbook's spec-template.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds instance mode: when a playbook reference (path or bare name) is supplied, resolve it per playbook-contract's bare-name resolution order, read the playbook's spec-template.md, use its sections in place of the default draft template, and stamp '> **Playbook:** ' as an additional header line alongside the existing Status/Design doc lines. Default (no playbook reference) flow is unchanged. Key decisions: - Implemented directly rather than through the tdd-tester/tdd-implementer/tdd-refactorer trio: this Testable component is agent-skill prose with no AAA-testable logic of its own (component-taxonomy's explicit agent-skill-prose example), verified instead by the fixture-driven dry-run harness already checked in for this task. Mirrors ADR-318/ADR-319's precedent of bypassing the trio for this same kind of component. - Verified green by spawning a subagent blind to authoring context to run the instance-mode Step 2 against fixture-playbook/, then grading the output against RUN.md's checklist: the draft file existed, its four sections matched spec-template.md's sections exactly (Domain, Endpoints, Applicable ADRs, Deltas from playbook assumptions), and the > **Playbook:** header line was present. - Narrowed scope per the task brief's recommendation: instance mode does not seed the drafted spec's Component Breakdown table from the playbook's step list — that reading of the spec's Key Design Decision text is not gated by this task's own exit criteria or the pre-built dry-run checklist, and is flagged as a known ambiguity for the task brief's author to confirm. - Step 1 (gather context) and Step 3 (pause for review) left unmodified, per the brief. --- .../dev-team/skills/spec-first-draft/SKILL.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/plugins/dev-team/skills/spec-first-draft/SKILL.md b/plugins/dev-team/skills/spec-first-draft/SKILL.md index 5f48626..163e018 100644 --- a/plugins/dev-team/skills/spec-first-draft/SKILL.md +++ b/plugins/dev-team/skills/spec-first-draft/SKILL.md @@ -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: + 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: [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 @@ -38,6 +45,15 @@ Determine the spec file location: the `_spec_*.md` lives next to the code it des Name: `_spec_.md` in PascalCase. +**Instance mode.** If a playbook reference (a path or a bare name) was supplied when this skill +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:** ` — 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: ---