Swain Design

<!-- swain-model-hint: opus, effort: high — default for artifact creation; see per-section overrides below -->

Spec Management

<!-- session-check: SPEC-121 --> Before proceeding with any state-changing operation, check for an active session:

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null

If the JSON output has "status" other than "active", inform the operator: "No active session — start one with /swain-init?" Proceed if they dismiss.

This skill defines the canonical artifact types, phases, and hierarchy. Detailed definitions and templates live in references/ (relative to this skill's directory). If the host repo has an AGENTS.md, keep its artifact sections in sync with the skill's reference data.

Artifact type definitions

Each artifact type has a definition file (lifecycle phases, conventions, folder structure) and a template (frontmatter fields, document skeleton). Read the definition for the artifact type you are creating or transitioning.

Choosing the right artifact type

When the user's request doesn't name a specific type, infer it from their intent:

Initiative vs Epic — the key distinction:

• Initiative: a direction with multiple deliverables. "Harden security" is an initiative — it spans scanning, gates, policies. The operator steers it.
• Epic: a deliverable with multiple specs. "Build the scanning tool" is an epic — it has clear completion criteria. Agents execute it.
• Rule of thumb: if the work needs 2+ epics to describe, it's an Initiative. If it needs 2+ specs, it's an Epic. If it's one spec, just create the spec.

Spec under Initiative (small work path) — bugs, minor enhancements, and chores that relate to an Initiative's direction but don't warrant an Epic can attach directly to the Initiative via parent-initiative. If small work clusters, suggest promoting it to an Epic.

Updating artifact metadata

When the operator asks to update a field on an existing artifact (e.g., "set VISION-001 priority to high", "re-parent EPIC-017 under INITIATIVE-001"):

1. Read the artifact's definition file to confirm the field name and valid values 2. Edit the frontmatter field directly (e.g., priority-weight: high) 3. Update the last-updated date 4. Run bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" build to refresh the graph cache 5. Commit the change

Common updates:

• priority-weight on Visions, Initiatives, Epics, and Specs — accepts high, medium, or low. Cascades: Vision → Initiative (can override) → Epic (can override) → Spec (can override). Affects downstream recommendation scoring and sibling sort order in swain chart.
• parent-initiative on Epics and Specs — re-parents them under an Initiative. A Spec can have parent-epic OR parent-initiative, never both.
• parent-vision on Initiatives — attaches to a Vision.

When the operator says "priority" or "weight" in the context of a Vision or Initiative, they mean the priority-weight frontmatter field.

Creating artifacts

Error handling

When an operation fails (missing parent, number collision, script error, etc.), consult references/troubleshooting.md for the recovery procedure. Do not improvise workarounds — the troubleshooting guide covers the known failure modes.

Complexity tier detection (SPEC-045)

Before running the full authoring ceremony, classify the artifact into a complexity tier:

Low complexity (fast-path eligible):

• SPEC with type: bug or type: fix and no parent-epic and no downstream depends-on links
• SPIKE with no parent-epic
• Any artifact where the user uses language like "quick", "simple", "trivial", or "fast"

Medium/High complexity (full ceremony):

• Feature SPECs (type: feature)
• Any SPEC or SPIKE with a parent-epic
• EPICs, INITIATIVEs, Visions, Journeys, ADRs — always full ceremony
• Any artifact where the user describes significant architectural decisions

When fast-path applies, output: [fast-path] Skipped: specwatch scan, scope check, index update

Workflow

1. Determine the next available number for the prefix by running:

   bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/next-artifact-id.sh" <PREFIX>

This scans ALL local branches and the working tree to prevent ID collisions across worktree sessions (SPEC-193). If the script is unavailable, fall back to scanning docs/<type>/ on the current HEAD — but note this risks collisions in worktree workflows. 2. For VISION artifacts: Before drafting, ask the user whether this is a competitive product or a personal product. The answer determines which template sections to include and shapes the entire downstream decomposition. See the vision definition for details on each product type. 2a. For DESIGN artifacts: First, ask which domain this design covers: interaction (UI/UX — screens, flows, states), data (data architecture — entities, schemas, flows, invariants), or system (system contracts — API boundaries, behavioral guarantees, integration interfaces). Default to interaction if unclear. Then prompt for Design Intent content — Context (one sentence anchoring the design to its purpose), Goals (what experience or guarantee we're trying to create), Constraints (reviewable boundaries), and Non-goals (what we explicitly decided not to do). This section is write-once: it is set at creation and not updated as the mutable sections evolve. Use the domain-specific template sections from the DESIGN template. 3. Read the artifact's definition file and template from the lookup table above. 4. Create the artifact in the correct phase subdirectory. Create the phase directory with mkdir -p if it doesn't exist yet. See the definition file for the exact directory structure. 5. Populate frontmatter with the required fields for the type (see the template). Set authored-by to the model identity resolved from the system prompt (e.g., GLM-5.1). If subagents were involved in creating the artifact, list all models with roles — e.g., GLM-5.1 (supervisor), Kimi-K2.5 (subagent). If the model identity is unavailable, use AI Assistant as a fallback. 6. Initialize the lifecycle table with the appropriate phase and current date, using this rule:

• User-requested → `Active`: if the user explicitly asked for this artifact (e.g., "new SPIKE about X", "write a spec for Y"), create it directly in Active. The user has already decided they want this work — Proposed adds no value.
• Agent-suggested → `Proposed`: if the agent creates the artifact on its own initiative (e.g., suggesting a SPIKE while the user asked for an EPIC, decomposing a Vision into child Epics), create it in Proposed. The user hasn't explicitly committed — Proposed signals "here's what I recommend, please confirm."
• Fully developed in-session → later phase: an artifact may be created directly in a later phase if it was fully developed during the conversation (see Phase skipping).

6.5. Hyperlink bare artifact ID references in body text — after writing the artifact body, scan all text below the closing --- frontmatter fence for bare artifact ID references matching the pattern (SPEC|EPIC|INITIATIVE|VISION|SPIKE|ADR|PERSONA|RUNBOOK|DESIGN|JOURNEY|TRAIN|CHORE)-[0-9]+. For each bare ID that is:

• not already inside a markdown link ([...](...)), and
• not inside a code fence (` ` block) or inline code ( `backtick ``),

resolve it with:

   bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/resolve-artifact-link.sh" <ARTIFACT-ID> <SOURCE-FILE>

Replace the bare ID with [ARTIFACT-ID](relative-path). If the script returns a non-zero exit code or empty output (artifact not found), leave the bare ID as-is — do not fail the operation. Frontmatter values must remain as plain IDs (YAML compatibility); only body text gets hyperlinks. 7. Validate parent references exist (e.g., the Epic referenced by a new Agent Spec must already exist). 7.5. Same-type overlap check — (standing-track types only: DESIGN, Persona, Runbook) scan docs/<type>/Active/ for existing Active artifacts of the same type. Flag overlap if:

• The new artifact's linked-artifacts references another artifact of the same type — this is a direct supersession signal.
• The new artifact's scoping section (Interaction Surface for DESIGNs, Trigger for Runbooks, Role for Personas) describes a surface that overlaps with or subsumes an existing Active artifact's scope.

If overlap is detected, ask the operator: "This overlaps with <EXISTING-ID> (<title>). Does the new artifact supersede it?" If yes, transition the existing artifact to Superseded (set superseded-by, update status, move to Superseded/ directory, add lifecycle entry) as part of the same operation. 8. ADR compliance check — run bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/adr-check.sh" <artifact-path>. Review any findings with the user before proceeding. 8a. Alignment check — (skip for fast-path tier) run bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" scope <artifact-id> and assess per references/alignment-checking.md. Report blocking findings (MISALIGNED); note advisory ones (SCOPE_LEAK, GOAL_DRIFT) without gating the operation. When displaying scope chains or ancestry to the operator, use artifact-context.sh for each node to show plain-language names alongside IDs. Fall back to bare IDs if unavailable. 8b. Unanchored check — after validating parent references, check if the new artifact has a path to a Vision via parent edges. If not, warn: ⚠ No Vision ancestry — this artifact will appear as Unanchored in swain chart. Offer to attach to an existing Initiative or Epic. Do not block creation. 9. Post-operation scan — (skip for fast-path tier) run bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/specwatch.sh" scan. This now also runs design-check.sh as part of the scan pipeline. Fix any stale references or design drift findings before committing. 10. Index refresh step — (skip for fast-path tier; batch refresh at session end via `rebuild-index.sh`) update list-<type>.md (see Index maintenance).

Superpowers integration

When superpowers is installed, the following chains are mandatory — invoke the skills, do not skip them or do the work inline:

1. Before creating Vision, Initiative, or Persona artifacts: Invoke the brainstorming skill for Socratic exploration. Pass the artifact context (goals, audience, constraints). Capture brainstorming output into swain's artifact format with proper frontmatter and lifecycle table.

2. When new feature work begins (brainstorming → artifacts → implementation): Brainstorming explores the idea and produces a design doc. Brainstorming's terminal state is invoking swain-design to create formal artifacts (epic + specs). Then, for each SPEC coming up for implementation, invoke writing-plans per-spec. After writing-plans saves a plan file, invoke swain-do for plan ingestion. The chain is: brainstorming → swain-design → per-spec writing-plans → swain-do.

2b. When an existing SPEC comes up for implementation (no brainstorming needed): Invoke writing-plans with the SPEC's acceptance criteria and scope. After writing-plans saves a plan file, invoke swain-do for plan ingestion.

3. For Testing → Implemented transitions: Invoke requesting-code-review for spec compliance and code quality review (if the review skills are available).

Detection: ls .agents/skills/brainstorming/SKILL.md .claude/skills/brainstorming/SKILL.md 2>/dev/null — if at least one path exists, superpowers is available. Cache the result for the session.

Read references/superpowers-integration.md for thin SPEC format and full routing details. All integration is optional — swain functions fully without superpowers.

<!-- swain-model-hint: sonnet, effort: low — transitions are procedural -->

Phase transitions

Phases are waypoints, not mandatory gates — artifacts may skip forward. Read references/phase-transitions.md for phase skipping rules, the transition workflow (validate → move → commit → hash stamp), verification/review gates, and completion rules.

Supersession specwatch-ignore maintenance

Whenever ANY artifact transitions to Superseded — whether via the phase transition workflow (step 5a in phase-transitions.md) or during artifact creation (same-type overlap detection) — append glob patterns to .agents/specwatch-ignore for the intentional backward references that the supersession creates. This prevents specwatch from flagging provenance links as warnings.

1. Create .agents/specwatch-ignore if it doesn't exist. 2. Append patterns for: (a) the superseded artifact path, (b) the superseding artifact path, (c) any ADR created as part of the same operation that references the superseded artifact. 3. Each entry gets a comment: # <OLD-ID> superseded by <NEW-ID> (<YYYY-MM-DD>). 4. Deduplicate: skip patterns that already exist in the file.

# INITIATIVE-001 superseded by INITIATIVE-013 (2026-03-19)
docs/initiative/Superseded/(INITIATIVE-001)*
docs/initiative/Active/(INITIATIVE-013)*

This step runs before the back-reference update (step 5b) and specwatch scan (step 9 in the creation workflow, step 8 in phase-transitions.md) so the scan output is clean.

Back-reference update on supersession

After specwatch-ignore maintenance (step 5a), update all non-terminal artifacts that reference the superseded artifact in frontmatter (linked-artifacts, depends-on-artifacts, addresses). See step 5b in phase-transitions.md for the full procedure. Key points:

• Check alignment before updating — supersession often changes scope. Read the referencing artifact's context and compare against the successor. If the relationship doesn't hold for the successor, flag it for the operator instead of silently repointing.
• Dedup — if the successor is already in the list, remove the old entry instead of adding a duplicate.
• Commit message provenance — record what changed (e.g., "update EPIC-031 linked-artifacts: INITIATIVE-001 → INITIATIVE-013") so git history preserves the original reference.
• Provenance links from the superseding artifact itself go to specwatch-ignore, not rewritten.

DESIGN lifecycle hooks

These hooks apply to DESIGN artifacts during phase transitions:

On DESIGN creation:

• Validate all sourcecode-refs paths exist at HEAD (if any are populated). Warn on broken paths before completing creation.

On Proposed → Active transition:

• Run design-check.sh on the DESIGN — all refs must be CURRENT.
• If any are STALE or BROKEN, warn the operator before completing the transition. Do not silently proceed with stale refs.

On Active → Superseded transition:

• The new (superseding) DESIGN should inherit sourcecode-refs from the old DESIGN with fresh pins via --repin.

Decision protection hooks

These hooks are agent-level behavioral guidance — they are not enforced by scripts but by the agent following this skill file.

SPEC Implementation transition: When a SPEC transitions to Implementation and has a linked DESIGN (via either side's linked-artifacts or artifact-refs):

• Surface the DESIGN's Design Intent section (Goals, Constraints, Non-goals) for alignment awareness. Present this to the operator so implementation stays within design boundaries.

SPEC completion: When a SPEC completes and its implementation changed files tracked by a DESIGN's sourcecode-refs:

• Cross-reference changed files (from the SPEC's commits) against active DESIGNs' sourcecode-refs.
• If overlap is found: nudge the operator to update the DESIGN and re-pin via design-check.sh --repin.

Alignment cascading: When an Epic has artifact-refs with rel: [aligned] pointing to a DESIGN:

• When child SPECs are created or modified, check scope against the DESIGN's Constraints and Non-goals.
• Traversal path: SPEC → parent EPIC → artifact-refs with rel: [aligned] → DESIGN → Design Intent.
• Only surface violations — silent pass for aligned SPECs.

Design-to-code drift: When a DESIGN's mutable sections are modified but sourcecode-refs blobs haven't changed:

• Surface: "DESIGN-NNN evolved but tracked code hasn't caught up." Nudge the operator to reconcile.

Drift resolution (SPEC-307)

On SPEC create, edit, or phase transition — if the SPEC has a parent (EPIC, Initiative, or Vision) — run drift resolution. Read both the SPEC and the parent. If the SPEC's scope, acceptance criteria, or constraints drift from the parent's goals or success criteria, apply a fix: either re-align the child (edit the SPEC) or update the parent.

Fix direction uses signals and content judgment: count prior drift decisions against the parent (more means parent is likely stale), plus assess which direction produces the better outcome. Apply the fix, then present the result for operator review: accept, modify, or revert. All outcomes are recorded as drift decisions via swain-session-state.sh record-decision.

README reconciliation nudge

When transitioning a Vision, Design, Journey, or Persona to a new phase, emit a soft signal if the transition changes the project's public-facing claims:

README.md may need updating to reflect this change.

This is informational, not blocking — the operator can dismiss it.

Trigger conditions — nudge when:

• A Vision transitions to Active (new direction) or Abandoned (dropped direction)
• A Design transitions to Active (new interaction model, data architecture, or system contract) or Superseded (replaced)
• A Journey transitions to Active (new user flow) or Abandoned (deprecated path)
• A Persona transitions to Active (new audience) or Abandoned (dropped audience)

Brainstorming context — when the brainstorming skill runs for a project that has a README but no artifacts (or a thin artifact tree — fewer than 3 Active Visions, Designs, Journeys, or Personas combined), it should use the README as the starting context for Socratic exploration. The README's claims, audience, and described behavior seed the brainstorming conversation instead of starting from scratch.

Detection for brainstorming context:

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
ACTIVE_COUNT=$(find "$REPO_ROOT/docs" -path "*/Active/*" -name "*.md" 2>/dev/null | grep -cE "(VISION|DESIGN|JOURNEY|PERSONA)" || echo "0")
HAS_README=$( [ -f "$REPO_ROOT/README.md" ] && echo "yes" || echo "no" )

If HAS_README=yes and ACTIVE_COUNT < 3, pass README content to brainstorming as primary context.

Trove integration

During research phase transitions (Spike Proposed -> Active, ADR Proposed -> Active, Vision/Epic creation), check for existing troves and offer to link or create one. Read references/trove-integration.md for the full hook, trove scanning, and back-link maintenance procedures.

Execution tracking handoff

When implementation begins on a SPEC, invoke swain-do. Read references/execution-tracking-handoff.md for the four-tier tracking model, swain-do: required frontmatter field, intent triggers, and coordination artifact decomposition.

GitHub Issues integration

SPECs link to GitHub Issues via the source-issue frontmatter field. During phase transitions on linked SPECs, post comments or close the issue. Read references/github-issues-integration.md for promotion workflow, transition hooks, and backend abstraction.

<!-- swain-model-hint: sonnet, effort: low — status queries are data aggregation -->

Status overview

For project-wide status, progress, or "what's next?" queries, defer to the swain-session skill (it aggregates swain chart + tk + git + GitHub issues). For artifact-specific graph queries, use bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" — see references/specgraph-guide.md. The default output is a vision-rooted hierarchy tree; lenses (ready, recommend, debt, unanchored, etc.) filter and annotate the tree for different decision contexts.

<!-- swain-model-hint: opus, effort: high — audits require deep cross-artifact analysis -->

Auditing artifacts

When the user requests an audit, read references/auditing.md for the full two-phase procedure (pre-scan + parallel audit agents including ADR compliance). Include an unanchored check pass: run bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/chart.sh" unanchored and report any artifacts without Vision ancestry as domain-level findings alongside alignment and ADR compliance results.

Implementation plans

Implementation plans bridge declarative specs and execution tracking. When implementation begins, read references/implementation-plans.md for TDD methodology, superpowers integration, plan workflow, and fallback procedures.

Scenario modeling

<!-- swain-model-hint: opus, effort: high — scenario edits require graph-wide awareness -->

Scenario modeling is point-in-time impact analysis via git branching. The operator surfaces a question; the agent does everything. The operator never touches git.

The goal is to produce real edits on disk so git diff can surface the impact — changed artifacts, shifted roadmaps, and code references. The operator's only role is to review the impact and say "accept" or "reject."

This is a pure LLM procedure within swain-design. No separate skill, no scripts, no new CLI flags.

Trigger phrases

Activate scenario modeling when the operator says any of:

• "what if ADR-X were active"
• "what if we'd chosen Y instead of Z"
• "compare the tree under different ADR assumptions"
• "scenario: <description>"
• "show me the impact of switching from A to B"

Procedure

1. Confirm intent. Briefly confirm the counterfactual assumption with the operator: "You want to see the artifact tree if ADR-046 were Active instead of Superseded?"

2. Branch.

   git checkout -b scenario/<kebab-case-name>

Derive the name from the question (e.g., scenario/adr-046-active, scenario/pre-helm-refactor).

3. Identify the edit set. Walk the supersession graph from the named ADR or decision. For each artifact the flip touches, trace:

• Artifacts that superseded it (also need flips).
• Designs paired with the ADR (e.g., ADR-048 ↔ DESIGN-033).
• Initiative and epic roadmaps that reference the flipped artifacts in linked-artifacts, depends-on-artifacts, or addresses arrays.

Use swain chart output and the graph cache to resolve references.

4. Apply edits. Edit frontmatter on the scenario branch:

• Flip status on the primary ADRs and their paired designs.
• Update back-references in initiative/epic frontmatter arrays (linked-artifacts, etc.).
• Do not edit prose bodies — frontmatter fields only.
• Do not create or delete artifact files.

5. Validate. Run swain chart on the branch. Confirm the tree resolves without broken references. Present the alternative tree to the operator.

6. Surface impact. Run and summarize:

   git diff trunk...HEAD --stat
   git diff trunk...HEAD -- docs/ | grep -oP 'sourcecode-refs:\K[^\n]+'

Present to the operator: number of artifacts changed, which initiative/epic roadmaps shifted, source code paths referenced.

7. Offer actions:

• Accept: merge to trunk and commit.
• Compare side by side: add a trunk worktree, run swain chart in both, present the diff.
• Reject: delete the branch.

Operator feedback loops

If the operator says "also flip DESIGN-034" or "don't touch INITIATIVE-005," adjust the edit set and re-validate. Iteration is conversational — the operator steers, the agent acts.

Cleanup

The agent handles both outcomes:

• Accepted: git checkout trunk && git merge scenario/<name>, commit, push.
• Rejected: git branch -D scenario/<name>.

Example

Operator: "what if ADR-046 had stood?"

1. Branch: git checkout -b scenario/adr-046-active 2. Edit set: flip ADR-046 → Active, ADR-048 → Superseded, DESIGN-032 → Active, DESIGN-033 → Superseded. Update INITIATIVE-018 roadmap to swap DESIGN-033 for DESIGN-032. 3. Validate: swain chart — passes. 4. Impact: 4 artifacts changed, 1 initiative roadmap shifted, 2 source code paths referenced.

---

Reference material

Consult these files when a workflow step references them:

• Artifact relationships: references/relationship-model.md — ER diagram of type hierarchy and cross-references
• Lifecycle table format: references/lifecycle-format.md — commit hash stamping convention
• Index maintenance: references/index-maintenance.md — list-<type>.md refresh rules
• Tooling: Scripts live in scripts/ (relative to this skill's directory). See references/specwatch-guide.md, references/specgraph-guide.md, references/adr-check-guide.md for details.

Session bookmark

After state-changing operations, update the bookmark: bash "$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.agents/bin/swain-bookmark.sh" "<action> <artifact-ids>" --files <paths>

ADR Compliance Check Guide

Reference for interpreting adr-check.sh output and performing content-level review.

Interpreting output

The script outputs structured findings:

• `RELEVANT` — An Active ADR's scope overlaps the artifact. Read the ADR's Decision section and verify the artifact's content doesn't contradict it. Common violations: proposing an approach rejected in "Alternatives Considered," ignoring constraints from "Consequences," or (ADR-on-ADR) contradicting an Active decision without explicitly superseding it.
• `DEAD_REF` — The artifact references a Retired or Superseded ADR. If superseded, review against the replacement. If retired with no replacement, assess whether the artifact's design still holds.
• `stale` flag on RELEVANT — The ADR became Active after the artifact was last updated. The artifact may need revision to align with the newer decision.

Exit codes: 0 = clean (no findings), 1 = advisory (non-stale RELEVANT only), 2 = actionable (DEAD_REF or stale RELEVANT), 3 = usage error.

Content-level review (does the artifact actually comply?) requires reading both documents — the script identifies which ADRs to check, the agent applies judgment.

Content-level review procedure

For each RELEVANT finding:

1. Read the ADR's Decision and Consequences sections. 2. Read the artifact's content (body, not just frontmatter). 3. Check for:

• Approaches that were explicitly rejected in the ADR's "Alternatives Considered"
• Constraints or trade-offs from "Consequences" that the artifact ignores
• Scope duplication — artifact covers ground already decided by the ADR without referencing it
• (ADR-on-ADR) Contradictions with an existing Active ADR that aren't framed as explicit supersession

Updating linkage

If the script surfaces a relevant ADR not already cross-referenced, add it:

• linked-artifacts for any artifact type
• depends-on-artifacts for blocking ADR-on-ADR relationships
• A body mention ("per ADR-NNN") as supplementary context

ADRs (ADR-NNN)

Template: adr-template.md.template

Lifecycle track: Standing

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Active
    Active --> Retired
    Active --> Superseded
    Retired --> [*]
    Superseded --> [*]
    Proposed --> Abandoned
    Active --> Abandoned
    Abandoned --> [*]

Follow Michael Nygard's ADR format: each ADR records a single architectural decision with its context, the decision itself, alternatives considered, and consequences. The format is deliberately lightweight — one decision per document, written in short prose, not a formal specification.

• Directory structure: docs/adr/<Phase>/(ADR-NNN)-<Title>.md — each ADR is a single Markdown file placed in the subdirectory matching its current lifecycle phase. Phase subdirectories: Proposed/, Active/, Retired/, Superseded/.
• Example: docs/adr/Active/(ADR-001)-Subtree-Split-Distribution-Model.md
• When transitioning phases, move the file to the new phase directory (e.g., git mv docs/adr/Proposed/(ADR-003)-Foo.md docs/adr/Active/(ADR-003)-Foo.md).
• Never store ADRs flat in docs/adr/ with phase tracked only in frontmatter — the directory structure must reflect the phase.
• ADRs are cross-cutting: they link to all affected artifacts but are not owned by any single one.
• ADRs are NOT for descriptive or explanatory architecture content. If the content describes "how the system works" without presenting a decision between alternatives, it belongs as an architecture overview supporting doc in the Vision folder — not as an ADR.
• Use the Proposed phase while investigation (Spikes) is still in progress or when the recommendation is formed and ready for review. Move to Active when the decision is adopted.

Alignment Checking

Agent instructions for semantic alignment assessment of artifacts in the swain hierarchy.

What alignment means

Alignment means oriented toward the same goal — usually the Vision at the top of the hierarchy. It does not mean content must match or detail levels must agree.

• Goal coherence: Each artifact's purpose should serve its parent's purpose, which in turn serves the Vision's value proposition.
• Non-contradiction: Artifacts should not actively work against each other's goals or constraints.
• Scope consistency: An artifact should not address problems or audiences outside its parent's defined boundaries.

Things that merely do not contradict each other but are otherwise semantically distant can still align with the same goal. Alignment is about shared direction, not proximity.

When to run alignment checks

Procedure

1. Run bash scripts/chart.sh scope <ID> to identify the alignment scope — the parent chain, siblings, and lateral links. 2. Read the Vision at the top of the chain. This is the "North Star" — the goal everything should orient toward. 3. Read the changed/created artifact. 4. Assess each relationship level per the checks below.

What to check per relationship level

Vision - Epic

• Does the Epic's goal serve the Vision's value proposition?
• Is the Epic's scope within the Vision's stated boundaries (non-goals)?
• Does the Epic target an audience consistent with the Vision's audience?

Epic - SPEC

• Does the SPEC's problem statement address something within the Epic's scope?
• Do the acceptance criteria contribute to the Epic's success criteria?
• Is the SPEC's type (enhancement/bug) consistent with the Epic's current phase?

Vision - Journey

• Does the Journey's user goal connect to the Vision's audience and value proposition?
• Are the Journey's pain points problems the Vision aims to solve?

Journey pain point - addressing artifacts

• Does the addressing artifact (SPEC/EPIC) actually resolve the described friction?
• Is the pain point's severity consistent with the addressing artifact's priority?

ADR - SPEC/Epic

• Is the approach consistent with the ADR's decision? Does the artifact avoid rejected alternatives?
• If the ADR constrains technology choices, does the artifact respect those constraints?

Persona - Journey

• Does the Journey's user match the Persona's profile?
• Are the needs and behaviors described in the Persona reflected in the Journey?

Architecture overview - ADRs

• Do Active ADRs match what the architecture overview describes?
• Has the overview been updated to reflect recent ADR decisions?

Sibling SPECs under same Epic

• Do they contradict each other or create redundancy?
• Do overlapping acceptance criteria agree on expected behavior?
• Are there gaps between siblings that the Epic expects to be covered?

Finding types and severity

MISALIGNED (blocking)

Active contradiction between artifacts. The artifact's stated goal or approach directly conflicts with its parent's goal, an Active ADR's decision, or a sibling's acceptance criteria.

Examples:

• A SPEC implementing an approach that an Active ADR explicitly rejected
• An Epic whose goal undermines its parent Vision's value proposition
• Sibling SPECs with contradictory acceptance criteria

SCOPE_LEAK (advisory)

The artifact works outside its parent's boundaries. The content addresses problems or audiences not within scope.

Examples:

• A SPEC under an Epic about "authentication" that adds unrelated logging features
• A Spec targeting a persona not defined in the parent Vision

GOAL_DRIFT (advisory)

The artifact's purpose has diverged from the Vision's intent. Typically happens when an artifact was aligned at creation but has been updated independently.

Examples:

• A SPEC whose problem statement evolved to address a different concern than what the Epic describes
• An Epic whose success criteria no longer connect to the Vision's value proposition

STALE_ALIGNMENT (advisory)

The artifact was aligned when created, but its parent changed since. The alignment has not been re-verified.

Examples:

• A SPEC created under an Epic that subsequently changed scope
• An artifact linked to an ADR that was superseded

SUPERSEDED_OVERLAP (blocking — standing-track types only)

A new standing-track artifact (DESIGN, Persona, Runbook) covers the same surface as an existing Active artifact of the same type. The new artifact likely supersedes the old one.

Signals (any one is sufficient):

• The new artifact's linked-artifacts references another artifact of the same type
• The new artifact's scoping section (Interaction Surface, Trigger, Role) describes a surface that overlaps with or subsumes an existing Active artifact's scope

Action: Ask the operator whether the new artifact supersedes the existing one. If yes, transition the existing artifact to Superseded as part of the same operation.

Examples:

• A new DESIGN for "swain-box launcher UX" created while an Active DESIGN for "swain-box agent selection" exists — the new one subsumes the old
• A new RUNBOOK for "sandbox operations" created while an Active RUNBOOK for "sandbox cleanup" exists — the new one may supersede or complement

IMPLICIT_CONFLICT (advisory)

No explicit link exists between the artifacts, but their content contradicts. Found during broader scope analysis.

Examples:

• Two SPECs under different Epics that make incompatible assumptions about the same system component
• A Runbook that describes a procedure inconsistent with an ADR's decision

Noise reduction

Do not flag:

• Detail-level differences — A Vision is naturally more abstract than its child SPECs. Different granularity is expected, not a finding.
• Terminological variation — An Epic calling something a "module" while a SPEC calls it a "service" is not a conflict unless the concepts genuinely differ.
• Terminal-phase artifacts — Completed, Abandoned, or Superseded artifacts are historical record. Only flag if an active artifact references them as current guidance.
• Informational cross-refs that are merely distant — An ADR referencing a SPEC in a different Epic for background context is not misalignment.
• Missing optional links — Not every artifact needs every possible cross-reference. Only flag missing links when the content demonstrates an undeclared dependency.

Rule of thumb: If the finding wouldn't change what the developer decides, don't report it.

Auditing Artifacts

Audits have two phases: a pre-scan that fixes structural problems, then parallel audit agents that inspect the corrected state.

Phase 1: Pre-scan (run first, before agents)

Run scripts/specwatch.sh scan synchronously. This performs: 1. Stale reference detection — broken markdown links and unresolvable frontmatter refs 2. Artifact/tk sync check — mismatches between artifact status and tk item state (if tk is in use)

Fix any issues surfaced by the scan before proceeding. For stale refs, update links or frontmatter. For tk sync mismatches, invoke swain-do to reconcile (close stale tk items or transition artifacts). Run specwatch.sh phase-fix to move any artifacts whose phase directory doesn't match their frontmatter status.

Only proceed to Phase 2 once the pre-scan is clean (or all actionable issues are resolved).

Phase 2: Parallel audit agents

Spawn seven agents in a single turn:

Dependency coherence auditor

The dependency coherence auditor catches cases where the graph exists but is wrong. The cross-reference checker confirms targets resolve to real files; this agent checks whether those edges still make sense. Specific checks:

1. Dead-end dependencies — depends-on targets an Abandoned or Rejected artifact. The dependency can never be satisfied; flag it for removal or replacement. 2. Orphaned satisfied dependencies — depends-on targets a Complete artifact but the dependent is still in Proposed. The blocker is resolved — is the dependent actually stalled for a different reason, or should it advance? 3. Phase-inversion — A dependent artifact is in a later lifecycle phase than something it supposedly depends on (e.g., a Complete spec that depends-on a Proposed spike). This suggests the edge was never cleaned up or was added in error. 4. Content-drift — Read both artifacts and assess whether the dependency relationship still holds given what each artifact actually describes. Artifacts evolve; an edge that made sense at creation time may no longer reflect reality. Flag edges where the content of the two artifacts has no apparent logical connection. 5. Missing implicit dependencies — Scan artifact bodies for references to other artifact IDs (e.g., "as decided in ADR-001" or "builds on SPIKE-003") that are not declared in depends-on or linked-* frontmatter. These are shadow dependencies that should be formalized or explicitly noted as informational.

For checks 4 and 5, the agent must actually read artifact content — frontmatter alone is not sufficient. Present findings as a table with: source artifact, target artifact, check type, evidence (quote or summary), and recommended action (remove edge, add edge, update frontmatter, or investigate).

Alignment auditor

The alignment auditor checks that artifacts are semantically oriented toward the same goal. It requires reading artifact content — frontmatter alone is not sufficient. Procedure:

1. Run bash scripts/chart.sh --all to identify all active Visions. 2. For each active Vision, use chart.sh scope on every non-terminal descendant (Epics, SPECs under that Vision). 3. For each artifact, assess alignment per alignment-checking.md:

• Read the Vision's goal (the "North Star")
• Read the artifact content
• Check each relationship level (Vision↔Epic, Epic↔SPEC, etc.)

4. Report findings with severity (MISALIGNED, SCOPE_LEAK, GOAL_DRIFT, STALE_ALIGNMENT, IMPLICIT_CONFLICT).

Present findings as a table with: source artifact, related artifact, finding type, evidence (quote or summary), and recommended action. Apply the noise reduction rules from alignment-checking.md — only report findings that would change what a developer decides.

Desired Outcomes check

The Naming & structure validator checks every active SPEC, EPIC, and INITIATIVE artifact for a ## Desired Outcomes heading in the document body. Missing sections are advisory findings — they do not block the audit or fail validation.

Detection: grep for ^## Desired Outcomes in the artifact's primary .md file. Only check artifacts whose track is implementable or container AND whose type prefix is SPEC, EPIC, or INITIATIVE.

Reporting: Group missing-section findings under a "Missing Desired Outcomes" heading in the audit report with this table format:

The "Suggested action" column tells the remediator which existing sections to draw from when drafting.

Desired Outcomes remediation workflow

When audit findings include missing Desired Outcomes sections, the audit agent offers batch remediation:

1. Read context: For each artifact missing the section, read its existing outcome-adjacent content:

• SPEC: Problem Statement + parent Epic's Goal/Objective or parent Initiative's Strategic Focus
• EPIC: Goal/Objective + parent Initiative's Strategic Focus or parent Vision's Success Metrics
• INITIATIVE: Strategic Focus + parent Vision's goals

2. Draft: Write a Desired Outcomes section following the content guidance (Who benefits? What changes for them? How does this advance aspirations?). Reference personas by ID when applicable. 3. Present for review: Show all drafted sections to the operator in batch — do not auto-commit. Each draft should show the artifact ID, the drafted text, and the source sections it drew from. 4. Apply approved drafts: Insert approved sections at the correct position (after Problem Statement for SPECs, after Goal/Objective for EPICs, after Strategic Focus for INITIATIVEs) and commit.

Remediation is optional — the operator may decline individual drafts or skip remediation entirely. The advisory findings remain in the audit report regardless.

Reporting

Each agent reports gaps as a structured table with file path, issue type, and missing/invalid field. Merge the tables into a single audit report. Always include a 1-2 sentence summary of each artifact (not just its title) in result tables.

Enforce definitions, not current layout. The artifact definition files (in references/) are the source of truth for folder structure. If the repo's current layout diverges from the definitions (e.g., epics in a flat directory instead of phase subdirectories), the audit should flag misplaced files and propose git mv commands to bring them into compliance. Do not silently adopt a non-standard layout just because it already exists.

Chores (CHORE-NNN)

Template: chore-template.md.template

Lifecycle track: Implementable

mermaid
stateDiagram-v2
    [*] --> Active
    Active --> Complete
    Complete --> [*]
    Active --> Abandoned
    Abandoned --> [*]

A Chore is lightweight cleanup work — small, bounded, and independently executable. It does not ship feature code. Chores are the appropriate type for file moves, renames, relinking, index generation, and other infrastructure hygiene tasks.

Reduced frontmatter

Chores omit fields that are not relevant to lightweight cleanup work:

• No `parent-epic` — chores are standalone; they don't need epic coordination
• No `swain-do` — chores are typically one task; plan creation is optional
• No `type` — chores don't have feature/bug variants
• No `priority-weight` — chores are uniformly low-priority cleanup
• No `addresses` — chores don't address personas

Folder structure

docs/chores/<Phase>/(CHORE-NNN)-<Title>/ — the chore folder lives inside a subdirectory matching its current lifecycle phase. Phase subdirectories: Proposed/, Active/, Complete/.

• Example: docs/chores/Active/(CHORE-001)-Artifact-Cleanup/
• Primary file: (CHORE-NNN)-<Title>.md — the chore document itself.
• When transitioning phases, move the folder to the new phase directory.

Body sections

• Problem — what needs to be cleaned up and why
• Checklist — concrete steps to complete the chore
• Notes — any relevant context or follow-up items

Relationship to ADR-045

This artifact type was established by ADR-045. Chores track alongside SPECs in the implementable track but use a simplified lifecycle (Active → Complete, no Proposed/Ready/InProgress phases).

Designs (DESIGN-NNN)

Template: design-template.md.template

Lifecycle track: Standing

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Active
    Active --> Retired
    Active --> Superseded
    Retired --> [*]
    Superseded --> [*]
    Proposed --> Abandoned
    Active --> Abandoned
    Abandoned --> [*]

A design artifact captures the shape of a system concern as a standing document that persists across implementation cycles. Designs sit between Journeys (experience narratives) and Specs (implementation). They answer "what does X look like?" — not "how do we build it?" (Spec) or "what is the user's experience narrative?" (Journey).

Designs cover three domains, selected via the domain frontmatter field:

When domain is omitted, it defaults to interaction for backward compatibility.

• Folder structure: docs/design/<Phase>/(DESIGN-NNN)-<Title>/ — always foldered because a single design may contain multiple document types (screen wireframes, flow diagrams, interactive mockup links, annotated screenshots).
• Example: docs/design/Active/(DESIGN-003)-Skill-Installation-Flow/
• When transitioning phases, move the folder to the new phase directory (e.g., git mv docs/design/Proposed/(DESIGN-003)-Foo/ docs/design/Active/(DESIGN-003)-Foo/).
• Phase subdirectories: Proposed/, Active/, Retired/, Superseded/.
• Primary file: (DESIGN-NNN)-<Title>.md — the design overview and entry point.
• Supporting docs: individual screen wireframes, flow diagrams, state machines, annotated mockups, prototype links, asset inventories.
• Scoping rule: One Design per cohesive surface within its domain:
• interaction: One Design per interaction surface or workflow. "The skill installation flow" is a Design. "The settings page" is a Design.
• data: One Design per bounded data domain or data product. "The artifact metadata schema" is a Design. "The task tracking data model" is a Design.
• system: One Design per integration boundary or API surface. "The specgraph CLI interface" is a Design. "The webhook contract" is a Design.

If a Design covers multiple unrelated surfaces, it should be split. The artifact it's linked to sets the natural boundary — a Design linked to an Epic covers that Epic's surface; a Design linked to a Spec is narrower.

• Designs are cross-cutting reference artifacts — they link to Epics and Specs via linked-artifacts but are not owned by any single one. Multiple artifacts can reference the same Design.
• A Design is "Active" when stakeholders agree it represents the intended interaction. "Superseded" when a newer Design replaces it (link via superseded-by: in frontmatter). "Retired" when the interaction surface it describes no longer exists.
• Diagrams required: Any Design that describes a workflow, data model, or system interface MUST include a mermaid diagram. The diagram type depends on the domain:
• interaction: Flowchart (flowchart TD or flowchart LR) showing the decision spine — user choices and paths.
• data: ER diagram (erDiagram) showing entities, relationships, and cardinality. Supplement with flowcharts for data flow.
• system: Flowchart showing request/response flow, or sequence diagram (sequenceDiagram) for multi-party interactions.
• Syntax rules: Node IDs must be descriptive snake_case (e.g., detect_env, prompt_user) — never single-letter IDs. All labels must be quoted (["Label"], |"yes"|).
• Scope: Optimize for the human visual system: a scannable diagram beats a comprehensive one. Error handling belongs in "Edge Cases" sections, not on the main diagram.
• Multiple paths/branches: Show each as a branch off a decision diamond with essential steps. Don't fully expand each branch.
• Complex branches: If too complex for a few nodes, give it its own diagram in a subsection.
• Designs capture the shape of a concern, not the implementation. Implementation details belong in Specs that reference the Design. Architectural decisions with broader implications belong in ADRs.

Structured references

artifact-refs

Designs may use artifact-refs for commit-pinned cross-references with typed relationships:

artifact-refs:
  - artifact: SPEC-067
    rel: [aligned]
    commit: abc1234
    verified: 2026-03-19

The rel field specifies the relationship type (see relationship-model.md for the vocabulary). Plain informational cross-references that don't need commit pinning should use linked-artifacts (v1 flat list) instead.

sourcecode-refs

Designs may reference implementation files via sourcecode-refs -- blob-pinned file references that enable staleness detection when source code changes:

sourcecode-refs:
  - path: src/components/Button/Button.tsx
    blob: a1b2c3d
    commit: def5678
    verified: 2026-03-19

• path -- repo-relative file path
• blob -- git blob SHA for the referenced file version
• commit -- commit hash where this blob was verified
• verified -- date of last manual verification

sourcecode-refs entries implicitly carry a describes relationship -- no explicit rel field. A Design "describes" the surface that the source code implements — whether that's UI components (interaction), schema files (data), or API modules (system).

Design Intent section

The Design Intent section provides stable criteria against which to evaluate whether implementation changes constitute drift or intentional evolution. It contains three structured subsections:

• Goals answer "what experience are we trying to create?" — the desired user-facing outcome.
• Constraints are machine-checkable or reviewable boundaries that the design must respect.
• Non-goals prevent scope creep by explicitly recording what was decided against.

Write-once convention

Design Intent is established when the DESIGN is created or transitions to Active. It is not updated when the mutable sections (flows, states, screens) evolve. If the intent itself fundamentally changes, Supersede the DESIGN and create a new one.

Write-once is enforced by agent convention, not tooling. The structured format (Goals/Constraints/Non-goals) makes unintentional edits obvious in code review.

Epics (EPIC-NNN)

Template: epic-template.md.template

Lifecycle track: Container

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Active
    Active --> Complete
    Complete --> [*]
    Proposed --> Abandoned
    Active --> Abandoned
    Abandoned --> [*]

A strategic initiative that decomposes into multiple Agent Specs, Spikes, and ADRs. The coordination layer between product vision and feature-level work.

• Folder structure: docs/epic/<Phase>/(EPIC-NNN)-<Title>/ — the Epic folder lives inside a subdirectory matching its current lifecycle phase. Phase subdirectories: Proposed/, Active/, Complete/.
• Example: docs/epic/Active/(EPIC-001)-Spec-Management/
• When transitioning phases, move the folder to the new phase directory (e.g., git mv docs/epic/Proposed/(EPIC-001)-Foo/ docs/epic/Active/(EPIC-001)-Foo/).
• Primary file: (EPIC-NNN)-<Title>.md — the epic document itself.
• Supporting docs live alongside it in the same folder.
• Architecture overview: An architecture-overview.md in the Epic folder describes the architectural scope of this specific initiative — component boundaries, data flows, and integration points. Must include at least one diagram (mermaid preferred). Recommended diagram types: C4 Container or Component diagram, sequence diagram, data flow diagram, or detailed flowchart. This is narrower than the Vision-level architecture overview — it covers just this Epic's slice of the system.
• An Epic is "Complete" when all child Agent Specs reach "Complete" and success criteria are met.
• Priority weight (optional): priority-weight: high | medium | low in frontmatter. Overrides the parent Initiative/Vision weight for this Epic and its children. When absent, weight is inherited from the parent chain. This allows sorting Epics within the same Initiative by priority.
• Epics can trace back to journey pain points via addresses: in frontmatter (list of JOURNEY-NNN.PP-NN IDs). This is informational — it records which pain points the Epic was created to resolve.
• Tracking requirement: Swain-do runs on child SPECs, not on the Epic directly. If implementation is requested on an Epic, swain-design decomposes it into children first (see SKILL.md § Execution tracking handoff).

Execution Tracking Handoff

Artifact types fall into four tracking tiers based on their relationship to implementation work:

The swain-do frontmatter field

Artifacts that need swain-do carry swain-do: required in their frontmatter. This field is:

• Always present on SPEC artifacts (injected by their templates)
• Added per-instance on SPIKE artifacts when swain-design assesses the spike is complex enough to warrant tracked research
• Never present on EPIC, VISION, JOURNEY, ADR, PERSONA, RUNBOOK, or DESIGN artifacts — orchestration for those types lives in the skill, not the artifact

When an agent reads an artifact with swain-do: required, it should invoke the swain-do skill before beginning implementation work.

When implementation begins on a SPEC, swain-design should keep the lifecycle state aligned with the real work:

• If the SPEC is not already in In Progress, transition it to In Progress before handing off implementation tracking.
• If that SPEC has a parent EPIC and the EPIC is not already Active, transition the parent EPIC to Active as well.
• Treat both transitions as idempotent: if either artifact is already in the target state, leave it unchanged.

What "comes up for implementation" means

The trigger is intent, not phase transition alone. An artifact comes up for implementation when the user or workflow indicates they want to start building — not merely when its status changes.

• "Let's implement SPEC-003" → invoke swain-do
• "Move SPEC-003 to Ready" → phase transition only, no tracking yet
• "Fix SPEC-007 (type: bug)" → invoke swain-do
• "Let's work on EPIC-008" → decompose into SPECs first, then track the children

Coordination artifact decomposition

When swain-do is requested on an EPIC, VISION, or JOURNEY:

1. Swain-design leads. Decompose the artifact into implementable children (SPECs) if they don't already exist. 2. Swain-do follows. Create tracked plans for the child artifacts, not the container. 3. Swain-design monitors. The container transitions (e.g., EPIC → Complete) based on child completion per the existing completion rules.

GitHub Issues Integration

SPECs can be linked to GitHub Issues via the source-issue frontmatter field. This enables bidirectional sync between swain's artifact workflow and GitHub's issue tracker.

Promoting an issue to a SPEC

When the user wants to turn a GitHub issue into a SPEC:

1. Run scripts/issue-integration.sh check to verify gh CLI availability. 2. Run scripts/issue-integration.sh promote <issue-url-or-ref> to fetch issue data as JSON. 3. Create a new SPEC using the standard creation workflow, populating:

• source-issue: github:<owner>/<repo>#<number> in frontmatter
• Problem Statement from the issue body
• Title from the issue title

Accepted reference formats:

• github:<owner>/<repo>#<number> (canonical)
• https://github.com/<owner>/<repo>/issues/<number> (URL, converted automatically)

Transition hooks

During phase transitions on SPECs with a source-issue field, post notifications to the linked issue:

If gh CLI is unavailable, log a warning and continue the transition — issue sync is best-effort, not a gate.

Backend abstraction

The source-issue value uses URL-prefix dispatch: github: routes to the GitHub backend (gh CLI). Future backends (Linear, Jira) would add new prefixes and implement the same operations: promote, comment, close. Core swain-design logic does not change when a backend is added.

Implementation Plans

Implementation plans bridge declarative specs (docs/) and execution tracking. They are not doc-type artifacts. All CLI operations are handled by the swain-do skill — invoke it to bootstrap the task backend before creating plans.

TDD methodology

Implementation plans follow test-driven development as the default methodology. Every plan should structure tasks so that tests are written before the code they verify — the classic red-green-refactor cycle. This matters because tests written after implementation tend to confirm what was built rather than what was specified; writing tests first forces the plan to stay anchored to the acceptance criteria.

Task ordering principles:

1. Test first. For each functional unit, the plan should contain a test task before its implementation task. The test task writes a failing test derived from the artifact's acceptance criteria. The implementation task makes it pass. 2. Small cycles. Prefer many small red-green pairs over a single "write all tests" → "write all code" split. Each cycle should cover one acceptance criterion or one behavioral facet. 3. Refactor explicitly. When a cycle produces working but rough code, include a refactor task after the green phase. Not every cycle needs one — only when the implementation warrants cleanup. 4. Integration tests bookend the plan. Start with a skeleton integration test that exercises the end-to-end path (it will fail until the pieces exist). The final task verifies it passes.

When superpowers is present, the brainstorming step should produce a TDD-structured plan. When seeding manually, decompose the spec's acceptance criteria into red-green task pairs.

Anti-rationalization safeguards

When creating or reviewing implementation plans, watch for these rationalizations that undermine TDD:

These safeguards apply to both manually-seeded plans and superpowers-generated plans. Review the plan against this table before starting execution.

Workflow

1. If superpowers is present, use the superpowers integration flow to author the plan. Otherwise, seed manually from the spec's "Implementation Approach" section, structuring tasks as TDD cycles derived from acceptance criteria. 2. Create an implementation plan linked via an origin ref (e.g., SPEC-003). Create tasks with dependencies, each tagged with spec tags for originating specs. Order test-writing tasks before their corresponding implementation tasks. 3. When a task impacts additional specs, add spec tags and cross-plan dependencies.

Closing the loop

• Progress lives in the execution backend, not the spec doc.
• When all plan tasks are complete, transition the Spec to Needs Manual Test (not directly to Complete). The Needs Manual Test phase is where acceptance criteria are verified against evidence — see spec-definition.md § Needs Manual Test phase.
• In the Needs Manual Test phase, populate the Spec's Verification table: map each acceptance criterion to its evidence (test name, file, demo) and record Pass/Fail/Skip.
• Run scripts/spec-verify.sh <artifact-path> before transitioning from Needs Manual Test → Complete. The script confirms every criterion has evidence.
• Only after verification passes, transition the Spec to Complete.
• Note cross-spec tasks in each affected artifact's lifecycle entry (e.g., "Complete — shared serializer also covers SPEC-007").
• If execution reveals the spec is unworkable, the swain-do skill's escalation protocol flows control back to the swain-design skill for spec updates before re-planning.

Superpowers integration

When superpowers (obra/superpowers) is installed, route implementation through its brainstorming → writing-plans pipeline to produce higher-quality plans before handing off to swain-do.

Detection: Check whether the brainstorming and writing-plans skills exist:

ls .claude/skills/brainstorming/SKILL.md .agents/skills/brainstorming/SKILL.md .claude/skills/writing-plans/SKILL.md .agents/skills/writing-plans/SKILL.md 2>/dev/null

If at least one path exists for each skill, superpowers is available. If neither location has both skills, use the current direct-to-swain-do flow.

Routing when superpowers IS present:

1. Invoke the brainstorming skill with the artifact's context — pass the problem statement, acceptance criteria, and scope from the artifact's frontmatter and body. 2. Brainstorming produces a design and invokes writing-plans automatically. 3. writing-plans saves a plan file to docs/plans/YYYY-MM-DD-<feature-name>.md. 4. After the plan file is saved, invoke swain-do's plan ingestion:

   uv run python3 .claude/skills/swain-do/scripts/ingest-plan.py \
     docs/plans/<plan-file>.md <ARTIFACT-ID>

5. This creates a tk epic with child tasks, sequential dependencies, and spec lineage tags.

Routing when superpowers is NOT present:

Use the current flow — invoke swain-do directly for ad-hoc task breakdown.

If the user rejects the brainstorming design: Stop cleanly. No plan file is produced, no tk tasks are created. The user can either retry brainstorming or fall back to the direct flow.

Superpowers is a recommended companion, not a hard dependency. Never install it automatically or block implementation if it's missing.

Fallback

If swain-do is unavailable, fall back to the agent's built-in todo system (todo, in_progress, blocked, done). Maintain lineage by including artifact IDs in task titles (e.g., [SPEC-003] Add export endpoint).

Index Maintenance

Every doc-type directory keeps a single lifecycle index (list-<type>.md). The index is a human-facing display artifact — specgraph reads frontmatter directly, not the index. Index updates are lazy: skipped per-artifact, batched at session end.

Lazy refresh model (SPEC-047)

Per-artifact creation/transition: Do NOT update list-<type>.md. Only write the artifact frontmatter and lifecycle table.

Batch refresh (session end): Run scripts/rebuild-index.sh <type> for each artifact type that had activity in the session. This is called automatically by swain-sync before committing.

Explicit refresh: Run rebuild-index.sh <type> when the user requests an up-to-date index view.

What the batch refresh produces

rebuild-index.sh <type> scans docs/<type>/ across all phase subdirectories and regenerates list-<type>.md: 1. Groups artifacts by phase (Proposed, Ready, Active, Complete, etc.) 2. Extracts artifact:, title:, last-updated:, and latest lifecycle commit from each file 3. Writes the table sections in phase order 4. Atomic write via temp file → rename (idempotent — safe to run multiple times)

Usage

# Refresh spec index
bash scripts/rebuild-index.sh spec

# Refresh multiple types after a busy session
bash scripts/rebuild-index.sh spec epic spike

When to run

Legacy behavior

Prior to SPEC-047, the index was refreshed per-artifact as step 10 of the authoring workflow. That behavior is now replaced by the lazy model above. If you encounter old workflow instructions saying "refresh the index now", skip that step — rebuild-index.sh will handle it at session end.

Initiatives (INITIATIVE-NNN)

Template: initiative-template.md.template

Lifecycle track: Container

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Active
    Active --> Complete
    Complete --> [*]
    Proposed --> Abandoned
    Active --> Abandoned
    Abandoned --> [*]

A strategic focus that coordinates multiple Epics toward a shared direction. The alignment layer between product vision and epic-level work.

• Folder structure: docs/initiative/<Phase>/(INITIATIVE-NNN)-<Title>/ — the Initiative folder lives inside a subdirectory matching its current lifecycle phase. Phase subdirectories: Proposed/, Active/, Complete/, Abandoned/, Superseded/.
• Example: docs/initiative/Active/(INITIATIVE-001)-Prioritization-Layer/
• When transitioning phases, move the folder to the new phase directory (e.g., git mv docs/initiative/Proposed/(INITIATIVE-001)-Foo/ docs/initiative/Active/(INITIATIVE-001)-Foo/).
• Primary file: (INITIATIVE-NNN)-<Title>.md — the initiative document itself.
• Supporting docs live alongside it in the same folder.
• Architecture overview: An architecture-overview.md in the Initiative folder describes the architectural scope of this strategic focus — component boundaries, data flows, and integration points across the child Epics. Must include at least one diagram (mermaid preferred). Recommended diagram types: C4 Container or Component diagram, sequence diagram, data flow diagram, or detailed flowchart. This is broader than an Epic-level architecture overview — it covers the coordinated architectural patterns across multiple related Epics.
• Required frontmatter:
• title — human-readable initiative name
• artifact — INITIATIVE-NNN identifier
• track — always "container"
• status — lifecycle phase (Proposed, Active, Complete, Abandoned, Superseded)
• parent-vision — VISION-NNN parent(s) (required; YAML list, one or more). Initiatives may serve multiple Visions per ADR-009. Priority inheritance uses highest weight among parents unless explicitly overridden. Initiatives without a vision parent are flagged as orphans.
• author — person who created it
• authored-by — AI model(s) that created it (e.g., GLM-5.1, or GLM-5.1 (supervisor), Kimi-K2.5 (subagent) when subagents were involved)
• created — ISO-8601 date
• last-updated — ISO-8601 date
• Optional frontmatter:
• priority-weight — high/medium/low (inherited from parent Vision unless overridden)
• success-criteria — list of measurable outcomes
• depends-on-artifacts — list of blocking artifacts (VISION-, EPIC-, INITIATIVE-*, etc.)
• addresses — list of journey pain points (JOURNEY-NNN.PP-NN)
• evidence-pool — reference to supporting research
• An Initiative is "Complete" when all child Epics reach "Complete" and success criteria are met.
• Initiatives can contain child Epics (via parent-initiative on the Epic) and standalone Specs (via parent-initiative on the Spec).
• Initiatives represent a coordinated strategic focus — multiple related Epics pursuing the same direction.
• The Initiative purpose section is "Strategic Focus" (not "Goal / Objective" like Epics) — it emphasizes direction and intent rather than individual deliverables.
• Initiatives can trace back to journey pain points via addresses: in frontmatter (list of JOURNEY-NNN.PP-NN IDs). This is informational — it records which pain points the Initiative was created to resolve.
• Tracking requirement: Swain-do runs on child EPICs or SPECs, not on the Initiative directly. If implementation is requested on an Initiative, swain-design decomposes it into children first (see SKILL.md § Execution tracking handoff).

User Journey (JOURNEY-NNN)

Template: journey-template.md.template

Lifecycle track: Standing

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Active
    Active --> Retired
    Active --> Superseded
    Retired --> [*]
    Superseded --> [*]
    Proposed --> Abandoned
    Active --> Abandoned
    Abandoned --> [*]

Maps an end-to-end user experience across features and touchpoints. Journeys describe how a user accomplishes a goal and surface pain points and opportunities that inform which Epics to create.

• Folder structure: docs/journey/<Phase>/(JOURNEY-NNN)-<Title>/ — the Journey folder lives inside a subdirectory matching its current lifecycle phase. Phase subdirectories: Proposed/, Active/, Retired/, Superseded/.
• Example: docs/journey/Proposed/(JOURNEY-001)-First-Time-Setup/
• When transitioning phases, move the folder to the new phase directory (e.g., git mv docs/journey/Proposed/(JOURNEY-001)-Foo/ docs/journey/Active/(JOURNEY-001)-Foo/).
• Primary file: (JOURNEY-NNN)-<Title>.md — the journey narrative.
• Supporting docs: flow charts, interview notes, extended research.
• A Journey is "Active" when its steps and pain points have been confirmed through review or prototype testing.
• Journeys are discovery artifacts — they inform Epic and Agent Spec creation but are not directly implemented. They do NOT contain acceptance criteria or task breakdowns.

Mermaid journey diagram

Every journey MUST include a Mermaid journey diagram embedded in the primary file. The diagram is a structured visualization of the narrative — it encodes stages, actions, satisfaction levels, and actors in a single view. Place the diagram immediately after the Steps / Stages section.

Syntax:

~~~markdown

journey
    title <Journey Title>
    section <Stage Name>
      <Action>: <score>: <Actor>

~~~

Mapping conventions:

Satisfaction scores (1–5 scale):

Every pain point identified in the narrative MUST appear as a score ≤ 2 task in the diagram, and every score ≤ 2 task MUST have a corresponding pain point in the narrative. This keeps the diagram and narrative in sync.

Example:

~~~markdown

journey
    title First-Time Project Setup
    section Discovery
      Find product landing page: 4: Developer
      Read getting-started guide: 3: Developer
    section Installation
      Install CLI tool: 5: Developer
      Run init command: 4: Developer
      Configure credentials: 2: Developer
    section First Use
      Create first project: 4: Developer
      Invite team member: 1: Developer, Admin
      Run first build: 5: Developer

~~~

In this example, "Configure credentials" (2) and "Invite team member" (1) surface as pain points — the narrative must describe the corresponding friction and opportunities.

Pain point IDs

Every pain point in a journey MUST be assigned a stable, unique ID using the format `JOURNEY-NNN.PP-NN` — a compound ID scoped to the parent journey.

• IDs are sequential within each journey: PP-01, PP-02, PP-03, ...
• IDs are stable — when a pain point is removed, its number is never reused.
• The compound form (JOURNEY-001.PP-03) is globally unique across the project and grep-friendly.

Pain Points Summary table — every journey MUST include this table in the ## Pain Points section. The table is the authoritative registry of pain point IDs for the journey.

• The ID column contains the short form (PP-01) within the journey document. The fully qualified form (JOURNEY-NNN.PP-NN) is used when referencing pain points from other artifacts.
• Each pain point with a score ≤ 2 in the Mermaid diagram MUST have a row in this table.

Inline callouts — in the Steps / Stages narrative, pain points are called out using:

> **PP-01:** Description of the friction...

The PP-NN label in the callout MUST match a row in the Pain Points Summary table.

Downstream traceability — Epics and Agent Specs can reference journey pain points via addresses: in their frontmatter (list of JOURNEY-NNN.PP-NN IDs). This is an informational traceability link, not a blocking dependency.

Workflow integration:

• When creating a journey, draft the narrative first, then build the diagram from it. The diagram is a derived visualization, not the source of truth — the narrative is.
• When updating a journey (adding stages, revising pain points), update both the narrative and the diagram in the same commit.
• When transitioning a journey to Active, confirm that satisfaction scores reflect validated research findings, not initial assumptions. Adjust scores as user feedback dictates.

Lifecycle Table Format

Frontmatter fields (Initiative-related)

Two scalar fields introduced with the INITIATIVE artifact type are also valid on EPIC and SPEC:

Example EPIC frontmatter:

parent-vision: VISION-001
parent-initiative: INITIATIVE-003
priority-weight: high

Every artifact embeds a lifecycle table tracking phase transitions:

### Lifecycle

| Phase | Date | Commit | Notes |
|-------|------|--------|-------|
| Planned | 2026-02-24 | abc1234 | Initial creation |
| Active  | 2026-02-25 | def5678 | Dependency X satisfied |

Stamping patterns

There are two patterns for recording the transition commit hash, selected based on artifact complexity tier (see SPEC-045 for tier classification).

Two-commit stamp (default — EPICs and full-ceremony SPECs)

Commit the transition first, then stamp the resulting hash into the lifecycle table in a second commit. This keeps the stamped hash reachable in git history.

Commit A: lifecycle(SPEC-001): transition to Complete

Co-Authored-By: <model-name-from-system-prompt> <noreply@unknown>
  ↳ lifecycle row: | Complete | 2026-03-14 | -- | ... |

Commit B: docs(SPEC-001): stamp lifecycle hash for Complete transition

Co-Authored-By: <model-name-from-system-prompt> <noreply@unknown>
  ↳ lifecycle row: | Complete | 2026-03-14 | <commit-A-hash> | ... |

Resolve the model name from the system prompt. When subagents ran under a different model, include one Co-Authored-By trailer per model (see AGENTS.md Model attribution).

Use two-commit stamp for:

• All EPICs (always — they are linked by child SPECs)
• Feature SPECs with downstream dependents (depends-on or linked-artifacts from other artifacts)
• Any artifact where precision is required for audit trails

Inline stamp (fast-path tier artifacts only)

For fast-path eligible artifacts with no downstream dependents, use git rev-parse HEAD before the transition commit to pre-fill the lifecycle row hash. Only one commit is needed.

IMPL_HASH=$(git rev-parse HEAD)
# Edit lifecycle table: | Complete | 2026-03-14 | $IMPL_HASH | ... |
git mv docs/spec/Ready/(SPEC-099)-.../ docs/spec/Complete/(SPEC-099)-.../
git add ...
git commit -m "lifecycle(SPEC-099): transition to Complete

Co-Authored-By: <model-name-from-system-prompt> <noreply@unknown>"

Commit A: lifecycle(SPEC-099): transition to Complete
  ↳ lifecycle row: | Complete | 2026-03-14 | <prev-HEAD-hash> | ... |

The hash points to the implementation commit (one before the transition), not the transition commit itself. This ~1-commit offset is acceptable for trivial artifacts where lifecycle auditing is rarely needed.

Use inline stamp for:

• Bug/fix SPECs with no parent-epic (fast-path tier)
• SPIKEs with no parent-epic (fast-path tier)
• Any artifact classified as fast-path that has no other artifacts depending on it

Lifecycle Tracks

Three-track lifecycle model from ADR-003. Each artifact type belongs to exactly one track. The track determines what phases the artifact passes through, what its terminal states are, and when it is considered resolved (no longer requiring action).

Track Definitions

Universal terminal states applicable to all tracks: Abandoned, Retired, Superseded.

Resolution Rules

An artifact is resolved (treated as done by specgraph, excluded from ready/next output) when:

• implementable track: status is Complete, Abandoned, Retired, or Superseded
• container track: status is Complete, Abandoned, Retired, or Superseded
• standing track: status is Active, Retired, or Superseded (Active is the live/adopted state — it is not "work to do")

Track Field in Artifacts

Every artifact's YAML frontmatter includes a track field:

track: implementable   # SPEC
track: container       # INITIATIVE, EPIC, SPIKE
track: standing        # VISION, JOURNEY, PERSONA, ADR, RUNBOOK, DESIGN

When the track field is absent (legacy artifacts), specgraph infers the track from the artifact type using the table above and emits a TRACK_MISSING warning.

Relationship to ADR-003

This file is a machine-readable companion to ADR-003. It should change only when ADR-003 is superseded. Do not edit the track definitions here independently — raise an ADR update first.

Personas (PERSONA-NNN)

Template: persona-template.md.template

Lifecycle track: Standing

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Active
    Active --> Retired
    Active --> Superseded
    Retired --> [*]
    Superseded --> [*]
    Proposed --> Abandoned
    Active --> Abandoned
    Abandoned --> [*]

A user archetype that represents a distinct segment of the product's audience. Follow Alan Cooper's persona model (from The Inmates Are Running the Asylum): a Persona is a concrete, narrative description of a fictional but realistic user — defined by goals, behaviors, and context, not demographics alone. Personas are cross-cutting — they are referenced by Journeys, Visions, and other artifacts but are not owned by any single one.

• Folder structure: docs/persona/<Phase>/(PERSONA-NNN)-<Title>/ — the Persona folder lives inside a subdirectory matching its current lifecycle phase. Phase subdirectories: Proposed/, Active/, Retired/, Superseded/.
• Example: docs/persona/Active/(PERSONA-001)-Solo-Developer/
• When transitioning phases, move the folder to the new phase directory (e.g., git mv docs/persona/Proposed/(PERSONA-001)-Foo/ docs/persona/Active/(PERSONA-001)-Foo/).
• Primary file: (PERSONA-NNN)-<Title>.md — the persona definition.
• Supporting docs: interview notes, survey data, behavioral research, demographic analysis.
• A Persona is "Active" when its attributes have been confirmed through review or data analysis.
• Personas are reference artifacts — they inform Journey and Agent Spec creation but are not directly implemented. They do NOT contain acceptance criteria, task breakdowns, or feature specifications.