Imported from AGIBuild/Sinaris (src/Sinaris.Cli/Assets/skills/sinaris-design/SKILL.md). Install upstream with npx skills add AGIBuild/Sinaris --skill sinaris-design. Copyright stays with the author.

Sinaris Design

Use this skill for the Design stage shared by both Sinaris entry paths:

New project: Guide -> Design -> Apply -> Evaluator
Existing project demand: Proposal -> Design -> Apply -> Evaluator

Evaluator vocabulary is hierarchical: a user journey contains checkpoints, and each checkpoint contains the concrete test steps needed to prove that checkpoint. Do not model Evaluator journeys as a flat list of steps. Use "checkpoint" for the acceptance unit in product and domain design; reserve "test steps" for the executable actions inside a checkpoint. "Job" may be used later for runtime scheduling, not for the business-facing journey structure.

Design is solution design before implementation. It turns a confirmed Guide milestone or a proposal-approved demand into phase-level design markdown and ready tasks. For a new demand in an existing project, default to Proposal before Design unless the work is already a single ready Apply task. Do not write code during Design.

Host Agent Mode Boundary

Do not enter any host Agent Plan mode while running Design. Continue through Sinaris commands and workflow gates only. If the host is already in Plan mode, stop and ask the user to exit that mode before continuing.

Required Inputs

1. Read confirmed project context:

{{SINARIS}} guide context --format json

2. Read the user request or claimed milestone/task.
3. Decide whether this needs Design or can go directly to Apply.

Before recording any phase, resolve the DesignSource:

DesignSource:
- Kind: GuideMilestone | Proposal
- MilestoneId: <milestone-id>
- ProposalId: <proposal-id or none>
- GateNextAction: <proposal prepare-design nextAction or none>

If Kind=Proposal, proposal prepare-design is mandatory and the phase registration must include --proposal <proposal-id>. This is the only workflow transition that applies a Designed proposal to a phase.

Design Entry Gate

Before entering Design, verify that Guide produced a complete milestone map. Design consumes the confirmed roadmap; it does not invent or repair the business roadmap.

For proposal-derived work, first ask the proposal gate:

{{SINARIS}} proposal prepare-design <proposal-id> --format json

If canPrepareDesign=false, do not start Design. Follow nextAction first (for example milestone next + milestone save --source-proposal for a new proposal-derived milestone).

Stop and return to Guide when:

• the milestone map is incomplete;
• the confirmed milestones are only a rough capability list;
• the current milestone has no clear business outcome, included capabilities, out-of-scope boundary, success signal, sequence rationale, or dependency context;
• the first milestone does not support the confirmed business value or success criteria;
• a technical foundation is being treated as the first business milestone without explicit user confirmation.

If any of these are true, do not start a Milestone Blueprint. Explain the missing business clarification and ask the user to continue Guide.

Entry Classification

Start by classifying the request:

I classify this request as:
- Type: <bug / feature / refactor / migration / hub / hook / asset / context change>
- Scope: <single ready task / needs structured breakdown / unclear>
- Requires Design: <yes/no>
- Reason: <short reason>

Use Design when:

• The input is a milestone or broad requirement, not a ready task.
• Multiple modules, behaviors, or user-facing choices are involved.
• There are multiple reasonable solution paths.
• Task boundaries, order, acceptance criteria, or verification strategy are unclear.
• The work may affect ProjectContext, hub, hooks, assets, DB/file boundaries, migrations, backup/recovery, or user workflows.

Skip Design only when the task is already ready for Apply: behavior, scope, acceptance criteria, verification, and risk are clear.

Convergence Rule

Design takes a milestone all the way to Apply-ready in a single pass.

The stable rule is:

A Design pass designs every phase of the current milestone in detail.
Apply does not start until all phases are recorded with ready tasks.

Proposal-Derived Small Increments

Proposal-derived work may be intentionally smaller than a full roadmap milestone. A single-phase design is allowed only when all of these are true:

• proposal prepare-design <proposal-id> returned canPrepareDesign=true.
• The user explicitly chooses a single-phase Sinaris design.
• The change has one cohesive behavior outcome and no hidden follow-up phase.
• You record the decision under Phase Granularity Decision in the phase design markdown.

Use this exact section when applying the override:

## Phase Granularity Decision
Decision: single-phase
Reason: <why one phase covers the proposal-derived milestone without losing design context>

Why: rolling design (design phase 1 → apply phase 1 → design phase 2 …) loses the global perspective. Late phases discover constraints that should have changed earlier phases, and the milestone drifts. Design the whole milestone first; commit to Apply only when the milestone-level Sinaris design is internally consistent.

Use two layers:

1. Milestone Blueprint

   • Split the milestone into 2-5 phases.
   • For each phase, capture goal, boundary, dependency, completion signal, and main risk.
   • Validate that the phase sequence covers the full milestone outcome with no gaps and no overlaps.

2. Per-Phase Design (repeat for every phase in the blueprint)

   • Resolve the phase's solution-design questions one at a time.
   • Produce ready tasks for that phase: behavior boundary, acceptance criteria, verification method, main risk.
   • After all phases are designed, re-check the blueprint: did later phases force changes to earlier phases? Reconcile before recording.

One Question Loop

Solve one solution-design question at a time.

Do not ask multiple questions at once. If two design choices both matter, ask the higher-risk question first, record that decision, then ask the next one in a later turn.

Interactive Question Contract

Use the host's structured question UI whenever the current Agent/runtime supports it. This is the default Design experience.

When the AskQuestion tool is available, call AskQuestion for every Design question that offers options. Do not render numbered choices in chat. In Cursor, AskQuestion is the supported structured question UI.

• Use one single-choice structured question through the AskQuestion tool for solution-design alternatives.
• Include Provide more options when the user may need additional candidates.
• Include Other when the user may need to supply a custom answer.
• Treat the structured answer as confirmed for the current design decision and record it immediately. Do not ask for a second confirmation.

Question Template

Current milestone/request:
<short description>

Current design scope:
<milestone blueprint / next phase / single ready task>

The next solution question is:
<one question>

Why this matters:
<correctness/scope/risk/user impact reason>

Structured interaction:
- Use one single-choice structured question through the AskQuestion tool.
- Append "(Recommended)" to the label of the recommended option so it is visually identifiable without reading the Recommendation paragraph.
- Place the recommended option first in the list.
- Option label: <Option A> (Recommended)
  - Pros:
  - Cons:
- Option label: <Option B>
  - Pros:
  - Cons:
- Option label: <Option C>
  - Pros:
  - Cons:
- Option label: Provide more options
- Option label: Other: <user input>

Recommendation:
<recommended option and reason>

Unsupported Agent Fallback

Use this section only when the current Agent/runtime cannot present a structured question UI. Only use this fallback when AskQuestion is unavailable. Do not use this as the default Design experience.

Options:
1. <Option A>
   - Pros:
   - Cons:
2. <Option B>
   - Pros:
   - Cons:
3. <Option C>
   - Pros:
   - Cons:
4. Provide more options
5. Other: <user input>

After the user chooses, summarize the decision and continue to the next blocking solution question. Do not ask multiple questions at once.

Completeness Checklist

Check these internally, but only ask the user about blocking items:

• User behavior: what changes for the user.
• Scope: whether this should become one task or multiple tasks.
• Data: file, DB, hash, migration, backup/recovery impact.
• Integration: CLI, hub, hooks, assets, agent activation, guide context impact.
• Compatibility: existing workspaces, old assets, and shipped behavior.
• Verification: unit, subcutaneous, focused smoke, and full test expectations.
• Rollout: CLI version bump, asset version bump, migration, install/update needs.
• Drift: whether this conflicts with confirmed ProjectContext or decisions.

Design Sufficiency Gate

Design is sufficient only when Apply can execute tasks without inventing missing decisions.

Before writing phase markdown, running phase save, or creating ready tasks, review the design against these principles:

• Goal / Non-goal: the phase goal is concrete, and out-of-scope work is explicit.
• Acceptance Criteria: each ready task can be verified from written criteria, not prior chat memory.
• Scope Impact: code, CLI protocol, generated or managed assets, docs, DB/file boundaries, hub/API, hooks, platform behavior, and migrations were considered when relevant.
• Architecture Ownership: each behavior has one owning service/component; the design does not duplicate logic across boundaries or break encapsulation.
• State / Data Flow: inputs, outputs, persistence, state transitions, error paths, and recovery behavior are clear.
• Risk / Trade-off: important alternatives, trade-offs, and residual risks are recorded.
• Testing Strategy: verification is scoped to unit/subcutaneous tests and focused checks that comply with the workspace testing policy.
• Apply Readiness: an agent can claim each task and implement it without asking new design questions or editing confirmed context.

If any item is insufficient, revise the design or ask the next one-question-loop prompt before recording. Do not compensate by creating vague tasks or leaving design decisions for Apply.

Design Completion Gate

Design can stop and move to recording only when all of these hold:

• The milestone business outcome is clear.
• The milestone is split into 2-5 phases.
• Each phase has goal, boundary, dependency, completion signal, and main risk.
• Every phase in the blueprint is designed in detail with ready tasks (no phase is left as a placeholder).
• Each ready task has behavior boundary, acceptance criteria, verification method, and main risk.
• Out-of-scope work is explicit.
• The Design Sufficiency Gate passed, including Apply Readiness.
• Late-phase decisions did not invalidate earlier-phase decisions; if they did, earlier phases were updated.

Output Template

When the whole milestone is internally consistent, output:

Milestone Design summary:
- Milestone/request:
- Milestone Blueprint (P1..PN):
- Per-phase design:
  - P1 <title>: confirmed decisions, ready tasks, risks
  - P2 <title>: confirmed decisions, ready tasks, risks
  - ...
- Out of scope:
- Verification strategy:
- Design Sufficiency Gate: <passed / blocking items resolved>
- Cross-phase risks / consistency notes:

I will record every Sinaris phase design and its tasks to the Sinaris board before Apply.

Then move on to "Recording the Milestone Design" below.

Recording the Milestone Design

Once Design is convergent for the entire milestone, persist every phase as a phase design and its ready tasks. Phase design documents live as markdown files on disk; the CLI only registers metadata on the project_phases row.

While the milestone status is Designing (its default while you're recording phase designs), you may attach task batch rows to any phase of that milestone — not only the most recently saved one. This lets you record all phase designs first to keep the global perspective, then come back and batch tasks per phase. Once the milestone advances past Designing (Apply Mode), task creation locks to the current/active phase only.

Storage layout

.sinaris/
  charter.md                          # authored during Guide and registered by `guide publish` — do not edit here
  milestones/
    m1/
      p1-<phase-slug>.md
      p2-<phase-slug>.md
    m2/
      p1-<phase-slug>.md

• <milestone> segment uses the milestone's sequence (m1, m2, ...). Look it up via {{SINARIS}} guide status --format json or {{SINARIS}} guide context --format json.
• <phase-slug> is kebab-case derived from the phase title, ASCII letters/digits only, max ~60 chars.
• The leading pN- keeps phase order obvious in directory listings; sequence resets per milestone.

Recording a phase plan

For each phase in the milestone, do these two steps in order:

1. Author the phase design markdown directly to its workspace path using your file-Write tool. The body must contain these four H2 sections — phase save rejects phase designs missing ## Impact On Charter:

# Phase 1: <Phase title>

## Goals
- <One concrete behavior outcome the phase delivers>

## Key Decisions
- <Each design decision confirmed during the One Question Loop>

## Acceptance Criteria
- <How a reviewer can tell the phase is Done>

## Impact On Charter
Preserves: <which charter goals stay valid>

2. Register the file with Sinaris. The CLI never edits the markdown - it only reads the file, hashes it, and stores (title, milestoneId, contentPath, contentHash) in the database. The plan title is auto-extracted from the file's # H1 unless you override it with --title.

For DesignSource.Kind=GuideMilestone:

{{SINARIS}} phase save \
  --path .sinaris/milestones/m1/p1-<phase-slug>.md \
  --milestone <milestone-id> \
  --format json

For DesignSource.Kind=Proposal:

{{SINARIS}} phase save \
  --path .sinaris/milestones/m<seq>/p<n>-<phase-slug>.md \
  --milestone <milestone-id> \
  --proposal <proposal-id> \
  --format json

phase save --proposal <proposal-id> validates the proposal gate, enforces milestone consistency, links the phase to the proposal, and advances the proposal to Applied.

To revise a phase design, edit the markdown file in place and re-run the same phase save --path … — the phase id is derived from the path so it upserts the existing row.

Ready task rows

Once every phase design is registered (preferred order: save p1..pN first to lock in the milestone shape), batch-create the ready tasks for each phase. While the milestone is still Designing, you can target any phase id returned by phase save, regardless of save order:

{{SINARIS}} task batch --phase <phase-id> --format json <<'EOF'
[
  { "title": "<Self-contained task title>",
    "description": "Acceptance: <observable outcome>. Risk: <main risk>.",
    "priority": 10 },
  { "title": "<Next task>",
    "description": "Acceptance: <...>. Risk: <...>.",
    "priority": 8 }
]
EOF

Rules for the rows:

• Each description must be self-contained. An agent who claims this task without prior chat context must still be able to implement it — include the acceptance criteria and the main risk explicitly.
• Use meaningful priority gaps (e.g. 10, 8, 5) so future tasks can be inserted between existing ones without renumbering.
• Use parent/child only when one task is a true container of others. Sinaris enforces:
  • A parent task cannot be claimed while it has any non-Done child.
  • When all children of a parent reach Done, the parent auto-completes. Build subtask hierarchies via {{SINARIS}} task create -t "..." --parent <parent-id> after task batch.

After recording

Once every Sinaris phase design is saved and every phase has its ready tasks, all phases enter status Ready and the milestone transitions to Ready. The milestone-level Ready state is the precondition for Apply — Sinaris will not let Apply start until every phase of the milestone is at least Ready. Design Mode is complete. Do not write code yet.

When the user explicitly enters Apply, switch to the sinaris-apply skill. Apply is the execution entry point for claim discipline, session ownership, development-task TDD, and completion evidence.

Boundaries

Design Mode

Do:

• Keep the discussion at solution-design level.
• Prefer 2-3 options plus a recommendation.
• Design every phase of the current milestone in detail before recording.
• Author each phase design as a markdown file under .sinaris/milestones/m{seq}/p{N}-{slug}.md, then register it with phase save --path; include --proposal <proposal-id> for proposal-derived work.
• Start only from a complete, confirmed milestone map.

Do not:

• Edit .sinaris/context/*.md or .sinaris/charter.md; Guide owns those.
• Implement code during Design Mode.
• Stop after only one phase is ready-for-apply — record the whole milestone before Apply starts.
• Treat a rough milestone as a ready Apply task.
• Use the CLI to author phase content (no phase save < file.md, no heredoc into save). The CLI only registers files you authored with your Write tool.
• Fill in missing business roadmap details during Design; switch back to Guide instead.

Apply Handoff

Do:

• Wait for explicit user intent before starting implementation, and do not use any host Agent execute-plan control as that intent.
• Switch to sinaris-apply when the user says to implement, apply, start, or continue execution.
• Keep Design complete before Apply starts.

Do not:

• Claim tasks from Design mode.
• Write implementation code during Design.
• Keep a second Apply procedure in this skill; sinaris-apply owns execution.