メニュー
Solution spec — acceptance criteria, breadboard, slices. Triggers: "write spec" | "spec this" | "solution design" | "what will we build" | "design the solution" | "acceptance criteria" | "define acceptance criteria" | "spec it out" | "write the spec".
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | spec |
| description | Solution spec — acceptance criteria, breadboard, slices. Triggers: "write spec" | "spec this" | "solution design" | "what will we build" | "design the solution" | "acceptance criteria" | "define acceptance criteria" | "spec it out" | "write the spec". |
I := σ written ∧ pre-check pass ∧ |χ| ≤ 5
V := ls artifacts/specs/{N}-*.md* ∧ pre-check: 0 failures
Let:
α := artifacts/analyses/{N}-{slug}-analysis.md
σ := artifacts/specs/{N}-{slug}-spec.md
φ := artifacts/frames/{slug}-frame.md
ρ := reviewer set
χ := [NEEDS CLARIFICATION]
Ω := skill: "interview"
Q := present choice, wait for user reply
SRC := source doc (α ∨ φ)
Analysis (or frame) → approved spec. Interview → pre-check → expert review → user approval.
¬worktree, ¬PR. Shape phase only. Implementation → /plan.
/spec --issue N → find analysis for #N (or frame if analysis skipped)
/spec --analysis path → use provided analysis as source
/spec --frame path → use provided frame (analysis was skipped)
| Step | ID | Required | Verifies via | Notes |
|---|---|---|---|---|
| 0 | resolve | ✓ | SRC ∃ | — |
| 1 | scan | — | σ ∃? | — |
| 1b | audit | — | — | --audit only |
| 2 | generate | ✓ | σ written | Ω interview |
| 3 | pre-check | ✓ | 0 failures | — |
| 4 | review | — | agents return | ∥ spawn |
| 5 | approval | ✓ | git log shows commit | gate |
Success: σ written ∧ pre-check pass ∧ |χ| ≤ 5
Evidence: ls artifacts/specs/ ∧ pre-check output
Steps: resolve → generate → pre-check → review → approval
¬clear → STOP + ask: "What artifact should this spec derive from?"
--issue N → scan priority order:
# 1. Find analysis with matching issue number
ls artifacts/analyses/{N}-*.md* 2>/dev/null | head -1
# 2. Find frame with matching issue in frontmatter
grep -rl "issue: N" artifacts/frames/ 2>/dev/null | head -1
--analysis path / --frame path → read directly.
¬SRC found → Q: "Run /analyze --issue N first, or provide path directly?"
Read SRC → extract: title, issue#, tier, problem, outcome, appetite, recommended shape (if α).
∃ issue (--issue N ∨ found in SRC frontmatter) → use it.
¬∃ issue → draft from SRC:
gh issue create --title "<title>" --body "<body>"
# body: ## Problem\n{problem}\n\n## Outcome\n{outcome}
Capture returned issue #N.
Glob artifacts/specs/{N}-*, artifacts/specs/*{slug}*.
∃ σ → Q: Reuse existing (→ Step 3) | Start fresh
--audit → after reading SRC, present reasoning audit per reasoning-audit.md (spec guidance).
→ Q: Proceed | Adjust approach | Abort
¬--audit → skip to Step 2.
Ω, args: "--promote artifacts/analyses/{N}-{slug}-analysis.md" (or frame path if no α).
Interview pre-fills from SRC. Focus on gaps to spec level:
F-lite/F-full: generate forge-chart sidecars per forge-chart-sidecar.md before writing σ.
Write σ. Must include:
| Section | Skip if |
|---|---|
## Context — source + promoted-from link | — |
## Goal — one-sentence outcome | — |
## Users — who is affected | — |
## Expected Behavior — narrative walkthrough | — |
## Data Model & Consumers — forge-chart sidecars (see below) | Tier S |
## Breadboard — affordance tables + wiring | Tier S |
## Slices — vertical increments table | Tier S |
## Success Criteria — - [ ] checkboxes, each binary | — |
Read forge-chart-sidecar.md before generating visuals.
## Data Model & Consumers must include:
{N}-{slug}-data-model.html (fgraph layered or fd-engine): core types/models, fields, relationships. Frozen/mutable in node labels.{N}-{slug}-consumers.html (hub-spoke or architecture): who consumes data, which fields, when. Solid edges = this issue; dashed = future.Link each sidecar (¬inline mermaid, ¬ASCII):
**Data structure:** [{title}](../visuals/{N}-{slug}-data-model.html)
**Consumer map:** [{title}](../visuals/{N}-{slug}-consumers.html)
Sidecars go BEFORE Breadboard. They answer "what is the data shape and who uses it" while Breadboard answers "how do pieces wire together."
May contain χ (max 3–5). χ items block /plan — must be resolved first.
"Unit tests for English" — run before expert review:
| Check | Rule | Skip condition |
|---|---|---|
| Testable criteria | Each - [ ] item is binary (pass/fail) | — |
| No dangling refs | All breadboard IDs (U*/N*/S*) appear in ≥1 slice | ¬Breadboard ∨ ¬Slices |
| Ambiguity budget | ≤5 χ items | — |
| Slice coverage | Every affordance appears in ≥1 slice | ¬Breadboard ∨ ¬Slices |
| Edge completeness | Each edge case has handling strategy | — |
≥2 failures → inform user:
Pre-check: 2 of 5 checks failed
✗ Testable criteria: "The UI should feel fast" is not binary
✗ Ambiguity budget: 7 [NEEDS CLARIFICATION] items found (max 5)
Q: Fix spec first (open σ, collect corrections, revise, re-check) | Continue to review anyway
Auto-select ρ (¬ask user). Architect always included:
| ρ | When | Focus |
|---|---|---|
| architect | Always | Technical soundness, feasibility, slice ordering |
| doc-writer | Always | Structure, clarity, breadboard completeness |
| product-lead | Always | Criteria quality, scope, user story validity |
| devops | ∃ CI/CD / deploy / infra criteria | Operational feasibility |
| axial-adr-review | ∃ axial ADR (axial: true ∈ docs/architecture/adr/) ∧ (spec adds adapter/integration/target ∨ touches infrastructure/) | Drift along non-primary axis (N×M trap) — read-only review |
Note on axial-adr-review asymmetry (intentional): The
/speccondition is semantic/intent-based — it triggers when the spec proposes adding a new adapter/integration/target or touchesinfrastructure/. The code-review phase (/code-review) uses a structural condition (diff touchesinfrastructure/,adapters/,domains/, orstages/). The two are complementary:/speccatches intent-level N×M violations,/code-reviewcatches implementation-level ones. A spec that adds infrastructure/ changes without proposing a new adapter is not a spec-level axial concern but may still be caught at code-review. Seeplugins/shared/references/axial-decomposition.md.
∀ r ∈ ρ → spawn ∥:
Task(
subagent_type: "dev-core:<r>",
description: "<r> spec review — #{N}",
prompt: "Review the spec at {σ_path} for <focus>. Check pre-check results: {pre_check_summary}. ¬TaskCreate. Return: good / needs improvement / concerns + specific line references."
)
Agent name map: architect → dev-core:architect | doc-writer → dev-core:doc-writer | product-lead → dev-core:product-lead | devops → dev-core:devops | axial-adr-review → dev-core:axial-adr-review
Incorporate feedback → revise σ → note unresolved concerns.
Open σ: code artifacts/specs/{N}-{slug}-spec.md.
Present summary: scope, |slices|, |acceptance criteria|, |χ|, pre-check results, unresolved expert concerns.
Q: Approve → continue pipeline | Revise → collect feedback → revise σ → loop from Step 3.
On approval → commit: git add artifacts/specs/{N}-{slug}-spec.md artifacts/visuals/ + commit per CLAUDE.md Rule 5.
Run Gate 2.5 → update issue status:
bun ${CLAUDE_PLUGIN_ROOT}/skills/issue-triage/triage.ts set <N> --status Specs
∄ sub-issues → "Spec complete. Run /plan --issue <N> to generate the implementation plan."
∃ sub-issues → "Run /plan --issue <sub_N> for each sub-issue in dependency order."
Tier S → skip. Read references/smart-splitting.md.
Triggers: |acceptance criteria| > 8 ∨ |slices| > 3.
- [ ] checkboxes in ## Success Criteria## Slices table¬triggers ∧ ¬both sections present → skip. ∃ triggers → run smart splitting per reference doc.
| Scenario | Behavior |
|---|---|
| ¬α ∧ ¬φ found | Q: run /analyze first or provide path |
| ∃ σ, user picks reuse | Present existing → jump to Step 3 |
| Analysis skipped (F-lite) | Use frame as SRC for interview promotion |
--issue N ∧ ¬GitHub issue | Create issue from SRC content |
| Expert subagent fails | Report error, continue without that reviewer |
| All pre-checks fail | Strongly recommend fix before review (¬block, user decides) |
| χ | |
| Tier S | Skip Breadboard + Slices |
| Circular deps in split | Reject split proposal, inform user |
/analyze (F-full) ∨ /frame (F-lite, analyze skipped)/plan/dev owns the dev-pipeline task lifecycle externally/dev: write artifact with status: approved, commit, return silently. ¬ask "proceed to /plan?". /dev re-scans and auto-chains to /plan in the same turn.Approved. Next: /plan --issue N. Stop./dev marks task cancelled.$ARGUMENTS
Set up local dev environment — stack.yml, CLAUDE.md Critical Rules, docs scaffolding, LSP. Triggered by /dev-init or standalone /env-setup. Triggers: "env setup" | "setup environment" | "configure stack" | "scaffold rules".
Populate scaffolded architecture/standards docs with real content extracted from CLAUDE.md and codebase analysis — fills TODO stubs, writes AI Quick Reference sections. Triggers: "seed docs" | "bootstrap docs" | "populate docs" | "fill architecture docs" | "seed architecture".
Initialize project — orchestrates env-setup, ci-setup, release-setup + axial ADR. Use when setting up a new repo or re-running Roxabi project init. Triggers: "dev-init" | "setup project" | "initialize project" | "/dev-init". Not the harness built-in /init (CLAUDE.md scaffold only).
Promote staging→main — pre-flight, version bump, changelog, PR & tag. Triggers: "promote staging" | "release" | "deploy" | "cut a release" | "--finalize" | "merge to main" | "promote to production" | "ship a release" | "tag and release" | "publish release".
Set up CI/CD — GitHub Actions workflows, TruffleHog, Dependabot, pre-commit hooks, marketplace plugins. Triggers: "ci setup" | "setup ci" | "configure ci" | "setup hooks" | "setup github actions".
Health check — verify dev-core config, GitHub project, labels, workflows, branch protection, secret scanning, CI hardening. Triggers: "checkup" | "health check" | "check setup" | "verify config" | "security baseline".