Skip to content

DataArt/artisyn-implementation-harness / skills/implementation-harness

implementation-harness

Flagged

Install the portable AI-dev harness, rebuild its operational graph standalone, harvest project skill improvements into its canonical templates, package direct canonical edits into a portable bundle, or apply canonical updates to an existing project. Use /implementation-harness launch, /implementation-harness reindex-graph, or /implementation-harness patch harvest|prepare|apply.

FileKindSize
CHANGELOG.mdmarkdown37.5 KB
README.mdmarkdown13.7 KB
SKILL.mdskill md9.6 KB
bin/artisyn-implementation-harness.mjsexecutablescript11.8 KB
bin/lib/placer.mjsscript2.6 KB
bin/lib/providers.mjsscript1.8 KB
bin/lib/reporter.mjsscript3.0 KB
bin/lib/zip.mjsscript4.0 KB
canonical/adaptors/claude/browser.mdmarkdown2.5 KB
canonical/adaptors/claude/context.mdmarkdown517 B
canonical/adaptors/claude/credentials.mdmarkdown512 B
canonical/adaptors/claude/delegation.mdmarkdown910 B
canonical/adaptors/claude/interaction.mdmarkdown359 B
canonical/adaptors/claude/planning.mdmarkdown745 B
canonical/adaptors/claude/review.mdmarkdown1.0 KB
canonical/adaptors/claude/task-tracking.mdmarkdown897 B
canonical/adaptors/codex/browser.mdmarkdown1.0 KB
canonical/adaptors/codex/context.mdmarkdown517 B
canonical/adaptors/codex/credentials.mdmarkdown480 B
canonical/adaptors/codex/delegation.mdmarkdown910 B
canonical/adaptors/codex/interaction.mdmarkdown359 B
canonical/adaptors/codex/planning.mdmarkdown904 B
canonical/adaptors/codex/review.mdmarkdown973 B
canonical/adaptors/codex/task-tracking.mdmarkdown1.1 KB
canonical/adaptors/copilot/browser.mdmarkdown620 B
canonical/adaptors/copilot/context.mdmarkdown881 B
canonical/adaptors/copilot/credentials.mdmarkdown992 B
canonical/adaptors/copilot/delegation.mdmarkdown1.2 KB
canonical/adaptors/copilot/interaction.mdmarkdown454 B
canonical/adaptors/copilot/planning.mdmarkdown785 B
canonical/adaptors/copilot/review.mdmarkdown791 B
canonical/adaptors/copilot/task-tracking.mdmarkdown723 B
canonical/agents/architect/INTENT.mdmarkdown2.4 KB
canonical/agents/architect/TEMPLATE.mdmarkdown6.5 KB
canonical/agents/docs-writer/INTENT.mdmarkdown2.2 KB
canonical/agents/docs-writer/TEMPLATE.mdmarkdown2.8 KB
canonical/agents/infra/INTENT.mdmarkdown2.1 KB
canonical/agents/infra/TEMPLATE.mdmarkdown5.1 KB
canonical/agents/layer/INTENT.mdmarkdown6.0 KB
canonical/agents/layer/TEMPLATE.mdmarkdown1.5 KB
canonical/agents/onboarding/INTENT.mdmarkdown5.3 KB
canonical/agents/onboarding/TEMPLATE.mdmarkdown4.2 KB
canonical/agents/product-architect/INTENT.mdmarkdown7.5 KB
canonical/agents/product-architect/TEMPLATE.mdmarkdown3.9 KB
canonical/agents/scrum-master/INTENT.mdmarkdown10.9 KB
canonical/agents/scrum-master/TEMPLATE.mdmarkdown12.3 KB
canonical/docs/.og/cli.mjsscript13.6 KB
canonical/docs/.og/cli.test.mjsscript19.6 KB
canonical/docs/.og/constants.mjsscript2.9 KB
canonical/docs/.og/docs-operational-graph.sqlitebinary24.0 KB
canonical/docs/.og/docs.mjsscript5.5 KB
canonical/docs/.og/edges.mjsscript5.8 KB
canonical/docs/.og/schema.mjsscript741 B
canonical/docs/.og/utils.mjsscript5.2 KB
canonical/docs/Engineering Guide/01 Conventions.mdmarkdown3.0 KB
canonical/docs/Engineering Guide/03 Engineer Role.mdmarkdown2.6 KB
canonical/docs/Engineering Guide/04 AI Coding Tool Compatibility.mdmarkdown3.6 KB
canonical/docs/Engineering Guide/05 MCP Setup.mdmarkdown6.6 KB
canonical/docs/Engineering Guide/Documentation/01 Principles.mdmarkdown15.3 KB
canonical/docs/Engineering Guide/Documentation/02 Structure.mdmarkdown3.8 KB
canonical/docs/Engineering Guide/Documentation/03 HLD Intent.mdmarkdown8.1 KB
canonical/docs/Engineering Guide/Documentation/04 LLD Intent.mdmarkdown9.7 KB
canonical/docs/Engineering Guide/Documentation/05 NFR Intent.mdmarkdown6.0 KB
canonical/docs/Engineering Guide/Documentation/07 Terminology.mdmarkdown1.4 KB
canonical/docs/Engineering Guide/Lifecycles/00 Overview.mdmarkdown5.8 KB
canonical/docs/Engineering Guide/Lifecycles/01 Dev Lifecycle.mdmarkdown19.9 KB
canonical/docs/Engineering Guide/Lifecycles/02 Design Lifecycle.mdmarkdown29.4 KB
canonical/docs/Engineering Guide/Lifecycles/03 Evolve Lifecycle.mdmarkdown7.0 KB
canonical/docs/Engineering Guide/Lifecycles/04 Architecture Lifecycle.mdmarkdown3.6 KB
canonical/docs/Engineering Guide/Lifecycles/05 Documents Flow.mdmarkdown9.5 KB
canonical/manifest.jsonconfig1.6 KB
canonical/mcp.jsonconfig23 B
canonical/root-instructions/INTERFACE.mdmarkdown3.3 KB
canonical/settings.jsonconfig332 B
canonical/skills/design/INTENT.mdmarkdown28.6 KB
canonical/skills/design/TEMPLATE.mdmarkdown19.0 KB
canonical/skills/design/interfaces/architecture.mdmarkdown2.8 KB
canonical/skills/design/interfaces/contract.mdmarkdown7.4 KB
canonical/skills/design/interfaces/design.mdmarkdown2.3 KB
canonical/skills/design/interfaces/efforts.mdmarkdown2.5 KB
canonical/skills/design/interfaces/stack.mdmarkdown1.6 KB
canonical/skills/design/patterns/announce-progress.mdmarkdown997 B
canonical/skills/design/patterns/approval-intelligent.mdmarkdown1.5 KB
canonical/skills/design/patterns/approval-sign-off.mdmarkdown2.4 KB
canonical/skills/design/patterns/context-resolution.mdmarkdown6.6 KB
canonical/skills/design/patterns/design-architect-review.mdmarkdown2.4 KB
canonical/skills/design/patterns/design-oq-triage.mdmarkdown3.8 KB
canonical/skills/design/patterns/design-quality-gate.mdmarkdown1.4 KB
canonical/skills/design/patterns/do-report-commit.mdmarkdown1.2 KB
canonical/skills/design/patterns/docs-writer-authoring.mdmarkdown3.6 KB
canonical/skills/design/patterns/metrics.mdmarkdown11.9 KB
canonical/skills/design/patterns/multi-decision-split.mdmarkdown3.6 KB
canonical/skills/design/patterns/phase-sign-off.mdmarkdown2.4 KB
canonical/skills/design/patterns/satellite-review.mdmarkdown1.5 KB
canonical/skills/design/patterns/session-continuity.mdmarkdown827 B
canonical/skills/design/patterns/task-tracking.mdmarkdown779 B
canonical/skills/design/patterns/waf-review.mdmarkdown4.2 KB
canonical/skills/design/patterns/write-confirm.mdmarkdown963 B
canonical/skills/design/references/00-decision-router.mdmarkdown3.8 KB
canonical/skills/design/references/00-router.mdmarkdown4.6 KB
canonical/skills/design/references/01-context-gathering.mdmarkdown8.1 KB
canonical/skills/design/references/02-ceremony.mdmarkdown4.6 KB
canonical/skills/design/references/03-frame.mdmarkdown6.7 KB
canonical/skills/design/references/04-research.mdmarkdown8.1 KB
canonical/skills/design/references/05-evaluate.mdmarkdown9.0 KB
canonical/skills/design/references/06-solution.mdmarkdown13.7 KB
canonical/skills/design/references/07-review-gate.mdmarkdown4.1 KB
canonical/skills/design/references/08-address-feedback.mdmarkdown8.0 KB
canonical/skills/design/references/09-publish.mdmarkdown8.9 KB
canonical/skills/design/references/10-completion.mdmarkdown7.4 KB
canonical/skills/design/scripts/constants.mjsscript2.0 KB
canonical/skills/design/scripts/design-metrics.mjsscript35.4 KB
canonical/skills/design/scripts/design-metrics.test.mjsscript12.0 KB
canonical/skills/design/scripts/utils.mjsscript3.1 KB
canonical/skills/design/templates/evaluate.mdmarkdown1.4 KB
canonical/skills/design/templates/frame.mdmarkdown2.6 KB
canonical/skills/design/templates/report.mdmarkdown4.8 KB
canonical/skills/design/templates/research.mdmarkdown2.4 KB
canonical/skills/design/templates/stat.jsonconfig1.7 KB
canonical/skills/design/templates/stat.schema.jsonconfig17.1 KB
canonical/skills/dev/INTENT.mdmarkdown15.9 KB
canonical/skills/dev/TEMPLATE.mdmarkdown9.0 KB
canonical/skills/dev/interfaces/intent.mdmarkdown2.6 KB
canonical/skills/dev/patterns/announce-progress.mdmarkdown1.1 KB
canonical/skills/dev/patterns/approval-intelligent.mdmarkdown1.5 KB
canonical/skills/dev/patterns/approval-sign-off.mdmarkdown1.9 KB
canonical/skills/dev/patterns/do-report-commit.mdmarkdown888 B
canonical/skills/dev/patterns/metrics.mdmarkdown17.7 KB
canonical/skills/dev/patterns/phase-sign-off.mdmarkdown2.2 KB
canonical/skills/dev/patterns/review-gate.mdmarkdown3.6 KB
canonical/skills/dev/patterns/satellite-review.mdmarkdown3.1 KB
canonical/skills/dev/patterns/session-continuity.mdmarkdown797 B
canonical/skills/dev/patterns/task-tracking.mdmarkdown766 B
canonical/skills/dev/patterns/write-confirm.mdmarkdown615 B
canonical/skills/dev/references/00-router.mdmarkdown2.2 KB
canonical/skills/dev/references/01-context-gathering.mdmarkdown10.3 KB
canonical/skills/dev/references/02-ceremony.mdmarkdown4.5 KB
canonical/skills/dev/references/03-plan.mdmarkdown14.2 KB
canonical/skills/dev/references/04-implement.mdmarkdown11.7 KB
canonical/skills/dev/references/05-test.mdmarkdown7.8 KB
canonical/skills/dev/references/06-document.mdmarkdown11.7 KB
canonical/skills/dev/references/07-completion.mdmarkdown6.3 KB
canonical/skills/dev/scripts/constants.mjsscript3.2 KB
canonical/skills/dev/scripts/quality.mjsscript9.1 KB
canonical/skills/dev/scripts/quality.test.mjsscript6.6 KB
canonical/skills/dev/scripts/timing.mjsscript38.1 KB
canonical/skills/dev/scripts/timing.test.mjsscript21.0 KB
canonical/skills/dev/scripts/utils.mjsscript3.1 KB
canonical/skills/dev/templates/plan.mdmarkdown3.3 KB
canonical/skills/dev/templates/report.mdmarkdown6.4 KB
canonical/skills/dev/templates/stat.jsonconfig1.4 KB
canonical/skills/dev/templates/stat.schema.jsonconfig29.3 KB
canonical/skills/evolve/INTENT.mdmarkdown1.6 KB
canonical/skills/evolve/TEMPLATE.mdmarkdown1.3 KB
canonical/skills/evolve/interfaces/improvement.mdmarkdown1.2 KB
canonical/skills/evolve/interfaces/reflection.mdmarkdown353 B
canonical/skills/evolve/interfaces/validation.mdmarkdown653 B
canonical/skills/evolve/patterns/task-tracking.mdmarkdown787 B
canonical/skills/evolve/references/00-router.mdmarkdown1.1 KB
canonical/skills/evolve/references/01-reflect.mdmarkdown805 B
canonical/skills/evolve/references/02-triage.mdmarkdown2.6 KB
canonical/skills/evolve/references/03-draft.mdmarkdown1.2 KB
canonical/skills/evolve/references/04-validate.mdmarkdown1.5 KB
canonical/skills/evolve/references/05-adopt.mdmarkdown1.5 KB
canonical/skills/war/INTENT.mdmarkdown4.5 KB
canonical/skills/war/TEMPLATE.mdmarkdown1.8 KB
canonical/skills/war/patterns/present-and-save.mdmarkdown1.0 KB
canonical/skills/war/patterns/scope-resolution.mdmarkdown830 B
canonical/skills/war/references/01-design.mdmarkdown3.4 KB
canonical/skills/war/references/02-implementation.mdmarkdown3.8 KB
canonical/skills/war/templates/design-report.mdmarkdown869 B
canonical/skills/war/templates/implementation-report.mdmarkdown1.8 KB
canonical/skills/where-we-are/INTENT.mdmarkdown3.3 KB
canonical/skills/where-we-are/TEMPLATE.mdmarkdown6.3 KB
canonical/skills/where-we-are/report-template.mdmarkdown2.0 KB
canonical/skills/x-ray/INTENT.mdmarkdown2.4 KB
canonical/skills/x-ray/TEMPLATE.mdmarkdown10.5 KB
implementation-harness.mdmarkdown1.4 KB
package.jsonmanifest696 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/CHANGELOG.md.patchother1.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/README.md.patchother1.9 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/SKILL.md.patchother2.5 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/agents/docs-writer/INTENT.md.patchother1.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/.og/cli.test.mjs.patchother846 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/Engineering Guide/04 AI Coding Tool Compatibility.md.patchother3.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/docs/Engineering Guide/05 MCP Setup.md.patchother5.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/manifest.json.patchother662 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/settings.json.patchother150 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/canonical/skills/design/INTENT.md.patchother19.4 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/patterns/skill-authoring.md.patchother692 B
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/host-capabilities.md.patchother1.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01-launch.md.patchother1.1 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01a-launch-plan.md.patchother1.6 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/01b-launch-install.md.patchother7.3 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/02-launch-questions.md.patchother5.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/launch/08-provider-launch.md.patchother3.2 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/04-patch-harvest.md.patchother2.6 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/05-patch-apply.md.patchother3.0 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/references/patch/06-patch-state.md.patchother7.1 KB
patch/20261105T160045Z-3.3.0-copilot-provider-6630df3d-f6bf-4651-8732-8048942ad1fe/diffs/scripts/lib/agent-format.mjs.patchother2.2 KB

canonical/docs/Engineering Guide/Lifecycles/02 Design Lifecycle.md

View on GitHub
# Design Lifecycle — Context Gathering → Ceremony → Frame → Research → Evaluate → Solution → Review → Address Feedback → Publish → Completion

_Produces an approved architectural design before implementation begins._

---

## Intent

The Design lifecycle front-loads the hard thinking. It frames the problem, researches options without bias, surfaces trade-offs across WAF pillars, makes a falsifiable recommendation, specifies integration and security detail, runs a WAF gate, and requires out-of-band human approval before any code is written.

The output is a `solution/` folder that serves as the implementation spec for the Dev tickets created at Completion.

**Two tracks, one flow.** `{{SKILL_PREFIX}}design` covers both **Product** design (cross-project product architecture — `docs/{{PRODUCT_CONTEXT_DIR}}/`) and **Project** design (this repo's own target architecture — `docs/Target Architecture (HLD)/`). The track is resolved exactly once, in Context Gathering, and recorded in `Report.md`'s `## Context` section (source docs, dest docs, subfolder, architect agent). Every later phase reads it from there — no phase re-derives or branches on track; the diagram and tables below use `{{DESIGN_ARCHITECT_AGENT}}` / `{{DESIGN_DOCS_ROOT}}` for that reason.

One skill (`design`) owns all ten phases as `references/01-context-gathering.md` … `references/10-completion.md`; there is no separate installable skill per phase. **Context Gathering and Ceremony are two separate stages**, mirroring the `dev` skill's own split: Context Gathering only reads and resolves (ticket, tracker, track/subfolder) and creates the story folder; Ceremony is the only stage that mutates the tracker or checks out a branch. Frame is separately its own stage again — not part of that dev-mirrored split — and writes the framing content using what Context Gathering resolved.

**Two stops per phase, both at its end** — same model as the dev lifecycle: a sign-off (`patterns/phase-sign-off.md`), then the commit. Steps inside a phase use intelligent checkpoints (`patterns/approval-intelligent.md`) and keep going when the content qualifies; anything they would have asked about is carried into the one sign-off. Review Gate and Address Feedback are the exception — their stop waits on the real external MR-approval fact, not an agent decision.

**Design-lifecycle artifacts live under `{{DESIGN_STORIES_ROOT}}`** — `docs/Stories/design/` for a Project design, `docs/Stories/product-design/` for a Product design, resolved once by Context Gathering and never re-derived. Active at `{{DESIGN_STORIES_ROOT}}[{TICKET}] {name}/`, archived at `{{DESIGN_STORIES_ROOT}}approved/[{TICKET}] {name}/` or `{{DESIGN_STORIES_ROOT}}declined/[{TICKET}] {name}/` — either way separate from the dev skill's `docs/Stories/[{TICKET}] {name}/impl/`, and the two design roots never mix in the same parent folder.

---

## When to use it

- Ticket is large or spans multiple sprints
- A new container or integration is being introduced
- Non-functional concerns (security, reliability, cost) are meaningfully affected
- The team is uncertain about the right approach

## When NOT to use it

Small, well-understood changes within a single container that introduce no new integrations or architecture decisions. Use `{{SKILL_PREFIX}}dev` directly.

---

## Flow

```mermaid
flowchart TD
    START(["▶ {{SKILL_PREFIX}}design TICKET"]):::actor

    CG["🎯 Context Gathering\nResolve ticket → fetch tracker → resolve track/subfolder → create folder + Report.md → read sources into Evidence → Sign-off → Commit"]:::phase
    CER["🚀 Ceremony\nTracker transition → branch checkout → Sign-off → Commit"]:::phase
    F["📋 Frame\nWrite 00 Frame.md (Problem/Success/Boundaries/Decisions?) → Sign-off → Commit"]:::phase
    R["🔍 Research\nDelegate options → propose OQ triage → Write 01 Research.md → Sign-off → Commit"]:::phase
    E["🏗 Evaluate\nRequirements × Options matrix + Tradeoffs → recommendation → closing WAF → Sign-off → Commit"]:::phase
    S1["📦 Solution\nDraft Architecture/Design/Stack/Efforts back to back → WAF + quality gate → Sign-off (drafts + estimates) → Commit"]:::phase
    REV["🔎 Review\nSuggest MR → developer opens draft MR"]:::phase
    PAPPROVE{"⏸ human approval\n(out-of-band)"}:::human
    AF["💬 Address Feedback\nReiterate into earlier phase → re-approve, or decline"]:::phase
    PUB["📤 Publish\nDoc impact → doc updates → review → Sign-off → Commit"]:::phase
    COMP["🏁 Completion\nTickets? → Archive (approved/declined) → tracker sync → Sign-off → Commit + PR"]:::phase

    ARC_R["{{DESIGN_ARCHITECT_AGENT}}\n3–5 options, no recommendation"]:::sat
    ARC_S["{{DESIGN_ARCHITECT_AGENT}}\narchitecture review\n(auto-triggers on boundary/contract change)"]:::sat
    DR["waf-review pattern\nWAF — 5 pillars"]:::sat
    DW["@docs-writer\ndoc updates"]:::sat
    ARC_P["{{DESIGN_ARCHITECT_AGENT}}\ndoc impact + review\nmax 2 passes"]:::sat

    START --> CG --> CER --> F --> R --> E --> S1 --> REV --> PAPPROVE
    PAPPROVE -->|concerns| AF
    AF -->|re-approved| PAPPROVE
    AF -->|declined| COMP
    PAPPROVE -->|approved| PUB --> COMP

    R -.->|invokes| ARC_R
    S1 -.->|auto-triggers on boundary change| ARC_S
    S1 -.->|invokes| DR
    PUB -.->|invokes| DW
    PUB -.->|invokes| ARC_P

    classDef actor fill:#2C3E50,stroke:#1A252F,color:#fff
    classDef phase fill:#27AE60,stroke:#1E8449,color:#fff
    classDef human fill:#4A90E2,stroke:#2E5C8A,color:#fff
    classDef sat fill:#9B59B6,stroke:#7D3C98,color:#fff
```

## Phases

**Router:** `{{SKILL_PREFIX}}design <TICKET>` — runs all ten phases in one session, stopping once per phase (sign-off, then commit) for confirmation. Bail out at any point and resume with the individual command. One skill (`design`) owns all ten phases; Review, Address Feedback, Publish, and Completion stay independently invocable and resumable the same way they always did: `{{SKILL_PREFIX}}design review-gate` opens the draft MR and the session pauses; `{{SKILL_PREFIX}}design address-feedback` is the next invocation — it confirms the outcome and, only if the approver raised concerns, loops back to an earlier phase, re-approves, or declines; `{{SKILL_PREFIX}}design publish` runs once the gate is approved; `{{SKILL_PREFIX}}design complete` runs alone for a design whose docs landed (or that was declined) but was never archived.

| Phase                 | Individual command                                  | What it produces                                                                                                                      |
| --------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Context Gathering** | `{{SKILL_PREFIX}}design context-gathering <TICKET>` | Ticket/local ID resolved, tracker context fetched, track/subfolder resolved; story folder + `design/Report.md` created                |
| **Ceremony**          | `{{SKILL_PREFIX}}design ceremony <TICKET>`          | Tracker transition + branch checkout confirmed                                                                                        |
| **Frame**             | `{{SKILL_PREFIX}}design frame <TICKET>`             | Problem statement, known + proposed evaluation criteria, boundaries, multi-decision breakdown if any → `design/00 Frame.md`           |
| **Research**          | `{{SKILL_PREFIX}}design research <TICKET>`          | 3–5 neutral options via `{{DESIGN_ARCHITECT_AGENT}}` — no recommendation → `design/01 Research.md`                                    |
| **Evaluate**          | `{{SKILL_PREFIX}}design evaluate <TICKET>`          | Requirements × Options matrix, tradeoffs, recommendation, WAF assessment → `design/02 Evaluate.md`                                    |
| **Solution**          | `{{SKILL_PREFIX}}design solution <TICKET>`          | Certainty-principle artifacts → `solution/Architecture.md`, `Design.md`, `Stack.md`, `Efforts.md`                                     |
| **Review**            | `{{SKILL_PREFIX}}design review-gate <TICKET>`       | Draft MR opened, gate recorded in `Report.md`, session pauses for out-of-band human approval                                          |
| **Address Feedback**  | `{{SKILL_PREFIX}}design address-feedback <TICKET>`  | Confirms the outcome; on concerns, reiterates into the traced-to phase and re-approves, or records a decline and routes to Completion |
| **Publish**           | `{{SKILL_PREFIX}}design publish <TICKET>`           | `{{DESIGN_DOCS_ROOT}}` updated — skipped entirely for a declined design                                                               |
| **Completion**        | `{{SKILL_PREFIX}}design complete <TICKET>`          | Implementation tickets optionally published, story archived to `approved/` or `declined/`, tracker synced, commit + PR handed over    |

---

## Invariants

**Context Gathering:** Read-only. Resolves the ticket number or a local `DESIGN-YYYYMMDD-XXXX` ID, fetches tracker/Confluence context, and — this stage's responsibility — identifies the track (Product or Project), its subfolder, and the Stories root that follows from it, once, via `patterns/context-resolution.md`, writing it to `Report.md`'s `## Context` section — no later phase re-asks or re-derives this. Creates the story folder (under the resolved Stories root) and `design/Report.md` (so Ceremony has something to update), then reads the relevant docs under the resolved Source docs path and records each one in `Report.md`'s `## Evidence` table — the lifecycle's one context-reading pass. Writes no framing content.

**Ceremony:** The only stage that mutates anything external. Tracker transition (assign + move to In Progress) is an intelligent checkpoint; auto-approved when unassigned-or-self-assigned, pre-work status, and In Progress is the obvious next transition, otherwise a sign-off. Branch checkout is always a sign-off — the AI proposes the exact `git checkout -b` command but never runs it; the developer confirms once they're on it.

**Frame:** Writes `design/00 Frame.md` using what Context Gathering already resolved — no re-fetching, no re-resolving track/subfolder. Requirements must include both known (from ticket) and proposed (gaps found by AI — NFRs, observability, GDPR). Proposed requirements are labelled `[proposed]`; these are confirmed at the phase sign-off, not asked about piecemeal. Frame also has its own dedicated step checking the Problem for bundled independent decisions (`patterns/multi-decision-split.md`, Step 2): at most one decision needs no section and no stop; two or more get a `## Decisions` section, written by `@docs-writer`, and their own sign-off right there — a material structural choice, since it decides how many times Research through Solution loop, not a content detail to fold into the main sign-off. These requirements become the evaluation criteria rows in the Requirements × Options matrix during Evaluate.

**Research:** Reads context from `Report.md`'s `## Evidence` table — populated once, in Context Gathering — rather than re-reading the source docs itself. `{{DESIGN_ARCHITECT_AGENT}}` returns options only — no recommendation. At least one "minimal change" option and at least one industry-standard approach must be included. No judgment is made here. Open questions from `{{DESIGN_ARCHITECT_AGENT}}` are proposed a V/E classification by the agent — **(V) Viability** (would disqualify an option) or **(E) Evaluation-input** (affects cost/detail only) — confirmed or corrected at the phase sign-off, not in a separate round. See `patterns/design-oq-triage.md`. If Frame's confirmed Decisions section lists more than one decision, only the content steps loop (one `design/01 Research - {Decision}.md` per decision) — the phase still closes with exactly one Sign-off → Report → Commit, per `references/00-decision-router.md`.

**Evaluate:** Every requirement from `00 Frame.md` and every WAF pillar must be addressed. The recommendation must be falsifiable: it states which assumption, if wrong, would change the recommendation. A closing WAF assessment runs on the recommended option only, and any P1 finding is carried into the phase sign-off as a named decision rather than its own stop. Loops per decision under the same multi-decision policy as Research.

**Solution:** Certainty principle applies. `Architecture.md` is the authoritative integrated end-to-end solution record: it carries every settled decision from Frame, Research, Evaluate, developer clarification, WAF and review feedback, with affected flows, consequences and verification obligations. `solution/` files contain only settled decisions and their direct consequences — no rationale, rejected alternatives or open questions. `Design.md`, `Stack.md` and `Efforts.md` provide supporting detail and must not introduce a material decision absent from or conflicting with Architecture.md. All four are drafted back to back with no stop between them; the `{{DESIGN_ARCHITECT_AGENT}}` architecture review auto-triggers (no permission ask) when a boundary, contract, infra resource, or cross-container data flow changed (see `patterns/design-architect-review.md`). The WAF review gate (`patterns/waf-review.md`, target `solution`) and the design quality gate run after drafting, with any P1 or failing check carried into the one phase sign-off — which also asks the developer to fill in `Efforts.md`'s Estimate column, since that is the one thing only they can supply. An operational-cost model is one of `interfaces/efforts.md`'s optional ways to express the design, included when it adds value, not a required section. Under the multi-decision policy, `Design.md` loops per decision but `Architecture.md` stays a single integrated file — one section per decision. Publish and `{{SKILL_PREFIX}}dev` consume Architecture.md as the solution source of truth.

**Review:** The AI suggests the MR title/body but does not open it. The developer opens the MR and pastes the URL. Session ends here — this is a genuine session boundary, not just a phase transition, since it waits on an out-of-band human approval. Confirming that approval is Address Feedback's opening concern, not this phase's.

**Address Feedback:** Always the next invocation after Review parks for approval — its own Step 1 is what confirms the outcome (**approved**, **concerns**, or **declined**), so this phase decides whether there's anything for it to do rather than Review deciding that for it. **Approved** skips this phase and continues to Publish; **declined** skips this phase and Publish, routing straight to Completion. Only on **concerns** does it actually run: the AI identifies which phase/step the concern traces to and suggests a named reiterate path (e.g. "Reiterate from Evaluate, Step 4"); it does not decide the fix unilaterally. The same three-way question is asked again after each rework round: **re-approved** (continue to Publish), **still concerns** (loop), or **declined**. A decline records the reason in `Report.md`'s `## Gate` section, skips Publish entirely (no permanent docs to update), and routes straight to Completion for an archive under `declined/` instead of `approved/`.

**Publish:** The AI does not approve its own gate — a human must approve the MR out-of-band, with no unresolved concerns, before this phase runs (and it is skipped entirely for a declined design). `{{DESIGN_ARCHITECT_AGENT}}` identifies `{{DESIGN_DOCS_ROOT}}` docs that need updating — auto-approved when every row is unambiguous, otherwise a sign-off; `@docs-writer` applies the updates and `{{DESIGN_ARCHITECT_AGENT}}` reviews (max 2 passes) before the one phase sign-off.

**Completion:** The final stage, and also directly invocable for a design whose docs landed (or that was declined) but was never archived. Branches on the gate's recorded outcome: **approved** publishes the WBS from `Efforts.md` to the tracker (auto-approved when unambiguous), archives to `{{DESIGN_STORIES_ROOT}}approved/[{TICKET}] {name}`, syncs the tracker to Done, and hands over the commit plus suggested PR title/body. **Declined** skips ticket publication, archives to `{{DESIGN_STORIES_ROOT}}declined/[{TICKET}] {name}`, syncs the tracker to its rejected/won't-do status, and ends with a neutral close — no PR, since no permanent docs were ever updated. Either way the worklog effort is derived from the design metrics, delegated to `@scrum-master` by state name, and recorded before the one phase sign-off.

---

## Patterns

Patterns are shared multi-step protocols co-located in the design skill's `patterns/` folder. They are not registered in {{ROOT_INSTRUCTIONS}} — each stage reference loads them on-demand via explicit path reference.

| Pattern                             | File                         | What it enforces                                                                                                                                                                                                                                                                                                                                                                                   | Applied in                                                                                                                 |
| ----------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **context-resolution**              | `context-resolution.md`      | Resolves Product/Project track, source/dest docs, Stories root, subfolder, and architect agent exactly once — an intelligent checkpoint, auto-approved when the track is unambiguous; then reads the resolved Source docs into `Report.md`'s `## Evidence` table (Two-track only — single-track modes read sources via `{{DESIGN_CONTEXT_STEP}}` instead, since there's no pattern file to own it) | Context Gathering Step 3                                                                                                   |
| **multi-decision-split**            | `multi-decision-split.md`    | Default per-decision file-split policy, confirmed once at its own dedicated sign-off (only when 2+ decisions), applied silently from Research onward                                                                                                                                                                                                                                               | Frame Step 2, Research Step 1, Evaluate Step 1, Solution Step 3                                                            |
| **decision-router** _(not a stage)_ | `00-decision-router.md`      | Loop boundary for a multi-decision stage: which steps repeat per decision, which close once regardless of count — never one Sign-off/Report/Commit per decision; also tracks each decision as a child task (one per decision, native-tool progress visibility), the same shape `dev`'s Implement uses for plan steps                                                                               | Applied by Research, Evaluate, Solution when 2+ decisions                                                                  |
| **phase-sign-off**                  | `phase-sign-off.md`          | One sign-off per phase, everything to decide in one message; how the stop works                                                                                                                                                                                                                                                                                                                    | Every stage's Sign-off step                                                                                                |
| **approval-sign-off**               | `approval-sign-off.md`       | What a sign-off is, its three shapes (content / manual operation / external confirmation); sign-offs used sparingly                                                                                                                                                                                                                                                                                | Named sign-off and manual-operation steps across every stage                                                               |
| **approval-intelligent**            | `approval-intelligent.md`    | Auto-approve a checkpoint when stated conditions hold; escalate to a sign-off on any doubt                                                                                                                                                                                                                                                                                                         | Every named intelligent-approval checkpoint                                                                                |
| **do → report → commit** _(design)_ | `do-report-commit.md`        | Report and Commit are routine after the sign-off; Commit is its own stop (manual operation); announce and continue, no separate "ready to continue?" ask                                                                                                                                                                                                                                           | End of every stage                                                                                                         |
| **announce-progress** _(design)_    | `announce-progress.md`       | `✅ Done / 📋 After this phase` after an auto-approved checkpoint or a phase boundary                                                                                                                                                                                                                                                                                                              | `design/SKILL.md` phase transitions, in-phase checkpoints                                                                  |
| **design-oq-triage**                | `design-oq-triage.md`        | Two-tier OQ classification (V/E) protocol; the agent proposes, the developer confirms at the phase sign-off                                                                                                                                                                                                                                                                                        | Research Step 3b, Evaluate Step 1b                                                                                         |
| **design-architect-review**         | `design-architect-review.md` | `{{DESIGN_ARCHITECT_AGENT}}` read-only review of Architecture.md; max 2 iterations; excludes doc gaps from scope                                                                                                                                                                                                                                                                                   | Solution Step 2b (auto-triggered)                                                                                          |
| **satellite-review** _(design)_     | `satellite-review.md`        | `{{DESIGN_ARCHITECT_AGENT}}` read-only reviewer of design artifacts; OK / corrections; max 2 iterations                                                                                                                                                                                                                                                                                            | Solution Step 2b (via `design-architect-review.md`), Publish Step 4                                                        |
| **write-confirm** _(design)_        | `write-confirm.md`           | Write file to disk and say so; review happens once, at the phase sign-off, not per file                                                                                                                                                                                                                                                                                                            | Every stage (per artifact)                                                                                                 |
| **session-continuity** _(design)_   | `session-continuity.md`      | Fresh vs. resume decided once by the router's Resume Detection; this pattern only covers losing context mid-stage                                                                                                                                                                                                                                                                                  | All ten stage references                                                                                                   |
| **waf-review**                      | `waf-review.md`              | Parameterized WAF assessment (`frame`/`research`/`evaluate`/`solution` targets, `--pillars=` filter); appends to Report.md — never a standalone file                                                                                                                                                                                                                                               | Solution Step 7 only (Evaluate keeps its own separate inline assessment; Publish keeps its own satellite review)           |
| **design-quality-gate**             | `design-quality-gate.md`     | Mechanical quality checks before Review Gate; result carried into the phase sign-off, never its own stop                                                                                                                                                                                                                                                                                           | Solution Step 7                                                                                                            |
| **task-tracking** _(design)_        | `task-tracking.md`           | The host's available progress tracker over the ten stages via the installed `runtime/task-tracking.md` procedure, with `Report.md` as the durable source of truth on resume                                                                                                                                                                                                                        | `design` router (one task per stage); also Research/Evaluate/Solution (one task per decision, via `00-decision-router.md`) |

Retired: `compact-between-phases.md` — its proactive-compaction job was redundant with `session-continuity.md`'s reactive one.

---

## What lives where

| Content                        | Lives in                                                                                                 |
| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Options, trade-offs, rationale | `{{DESIGN_STORIES_ROOT}}<TICKET>/design/` — never graduates                                              |
| WAF assessment                 | `design/Report.md` WAF section — never graduates                                                         |
| Chosen approach (outcome only) | `{{DESIGN_STORIES_ROOT}}<TICKET>/solution/` → drives `{{DESIGN_DOCS_ROOT}}` update at Publish            |
| Implementation spec            | `{{DESIGN_STORIES_ROOT}}<TICKET>/solution/` → guides Dev tickets, published to the tracker at Completion |

Active designs live at `{{DESIGN_STORIES_ROOT}}[{TICKET}] {name}/`; archived designs move to
`{{DESIGN_STORIES_ROOT}}approved/[{TICKET}] {name}/` (the normal outcome) or
`{{DESIGN_STORIES_ROOT}}declined/[{TICKET}] {name}/` (rejected at Address Feedback).
`{{DESIGN_STORIES_ROOT}}` is `Stories/design/` for a Project design or
`Stories/product-design/` for a Product design — either way separate from the
dev skill's own `Stories/[{TICKET}] {name}/impl/`.

## Design delivery metrics

Each story owns `design/stat.json` alongside `design/Report.md`. The design metrics
CLI captures ten stage attempts, observed work and waits, review evidence, feedback
rework, blockers, and actual runtime token deltas. Review approval waits persist across
sessions; approval without concerns explicitly skips Address Feedback. Every sign-off-gated
stage (Context Gathering, Ceremony, Frame, Research, Evaluate, Solution, Publish,
Completion) mechanically refuses `stage complete` without a recorded passing
"`<Stage> sign-off`" acceptance check in the current attempt — Review Gate and
Address Feedback are exempt, since their stop is the external MR-approval fact, not
a phase sign-off. Completion, not Publish, is the stage that finalizes metrics and
gates ticket completion, after required archive/tracker work and before any dev
hand-off. Design and dev records remain separate. See the design skill's
`patterns/metrics.md` for exact commands, recovery, approval recording, and the
schema. The design CLI and its constants install independently of other flows.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall