Skip to content

v0.8.0 — /design skill: human-facing design pipeline → agent execution handoff

Choose a tag to compare

View all tags
@alexherrero alexherrero released this 15 May 18:04
· 529 commits to main since this release
v0.8.0
4bc043d

The first toolkit skill that ships its own custom multi-stage workflow. The /design skill walks a human through a precise 10-section design-doc template, gates on review approval, splits the approved design into structural parts, and generates one PLAN.md per part for the harness's /work + /review flow to execute. Published designs surface in wiki/Home.md as the canonical "Why we built X" entry point.

Three sub-commands:

  • /design author <slug> [--visibility] — interactive section-by-section authoring of the 10-section template. Forces explicit N/A-with-rationale on each of the 11 Quality Attribute sub-attrs. Drives Status draft → review → final.
  • /design translate <slug> — splits a Status: final design into structural parts (one per Detailed Design subsection by default; grouping + ~6-cap heuristics; Reshape sub-loop for human override). Writes per-part files with inherited frontmatter + part-specific fields.
  • /design sequence <slug> — Kahn's topological sort with deterministic tie-breaking. Generates one PLAN.md per part using the harness's existing template shape. First part activates at .harness/PLAN.md; rest queue at .harness/designs/<slug>/queued-plans/.

Stage 5 (per-part execution) reuses the harness's existing /work + /review flow — deterministic gates + adversarial-reviewer + evaluator (v0.6.0) + kill-switch/steer/commit-on-stop (v0.7.0) all participate in the per-part execution loop.

Paired release

Paired with agentic-harness v2.3.0, which lands the harness-side:

  • /release §1b lifecycle hook with 3 cases — promote next queued plan when a part completes (Case B), or transition design final → launched + surface in wiki/Home.md + _Sidebar.md when the last part ships (Case C).
  • /setup §7 scaffolding for the wiki/explanation/designs/ landing dir.
  • templates/wiki/explanation/designs/ ships with .gitkeep + README pointing at this how-to.

Design rationale

Captured in ADR 0004 — Design skill design:

  • Hybrid decomposition — skill in toolkit for stages 1-4 + harness /work + /review for stage 5
  • User's 10-section template locked verbatim 2026-05-14 with Alternatives Considered added same day
  • Design doc as canonical wiki entry point (per /release §1b transition)
  • Status lifecycle 4-state machine (draft → review → final → launched)
  • Visibility field routes confidential → .harness/designs/ vs published → wiki/explanation/designs/
  • One PLAN.md per part (not shared)
  • Skill ships in toolkit, not harness (customization-shaped, not phase-shaped per ADR 0001)

Future consumers

/design proves itself by being used. ROADMAP items #7 (ContextVault), #8 (auto-context integration), #9 (evidence-tracking), #10 (quality-gates bundle), and #13 (diataxis-author) will each be designed using /design going forward.

See Use-The-Design-Skill how-to for three worked scenarios end-to-end.

Assets 2
Loading