Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions .agents/skills/sce-change-to-plan/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,12 @@ description: >

Own this workflow from input through its terminal user-visible response.
Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them.
Keep internal phase results private and continue immediately until a defined wait or stop.
Keep intermediate workflow state private and continue immediately until a defined wait or stop.
Resume user waits in this same skill and session.
Render user-visible output only from the named workflow layouts or phase reports.
Render user-visible output only from the named workflow layouts or reports.
Do not expose raw internal state or add text around a rendered layout or report.
Non-SCE helpers may assist, but must return to the active step without changing
phase order, gates, waits, writes, validation, stops, or terminal output.
workflow order, gates, waits, writes, validation, stops, or terminal output.
Do not invoke another SCE skill, package, or workflow command.

## Phase references
Expand Down Expand Up @@ -121,9 +121,13 @@ Then stop and wait. Do not implement, and do not run the handoff yourself.

### 4. Revise the plan on request

When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the same `loaded_context_brief` from step 1. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the same `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`.
When the user answers clarification questions from step 2, resume the **Initial-clarification continuation** with `original_request`, `clarification_answers`, and the current `loaded_context_brief`. Preserve `original_request` unchanged and never ask the user for the original change request again. When the user answers open questions listed in the summary or requests changes to an already-written plan, resume the **Existing-plan revision continuation** with `plan_path`, `correction`, and the current `loaded_context_brief`. Do not ask them to rerun `/change-to-plan`.

Run the **Plan authoring phase** with the applicable continuation fields. The brief still holds; durable context did not change because the user disagreed with a task boundary. Do not reload it.
Reuse `loaded_context_brief` when the revision stays within the focus it covers.
If the revision materially expands the plan into an area the brief did not cover,
rerun the **Context load phase** for the expanded focus before running the
**Plan authoring phase**. Do not reload context for revisions already covered by
the brief.

An answer that resolves a doubt removes that open question. An answer that does not resolve it leaves the question standing; do not drop it because the user replied to it. If the reply raises a new doubt, the revised plan carries a new open question.

Expand All @@ -143,7 +147,6 @@ Stop.

- Plan at most one change request per invocation. Revisions to the plan that request produced are part of the same invocation, not a second request.
- Read each phase's reference before running that phase.
- Always tell the user the plan can be revised, and always name its assumptions as the first thing worth checking.
- Do not gate the handoff on open questions listed in the plan summary. Blocking questions return `needs_clarification` before any plan is written. Offering revision is not the same as demanding it, and inventing doubts to justify a review gate is not allowed.
- Do not suppress, soften, or answer an open question or clarification question on the user's behalf.
- Do not defer the user's revision to a rerun of `/change-to-plan`, and do not defer it to the implementation phase. Revise the plan here.
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/sce-change-to-plan/references/output.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ candidate plan paths and explain that naming one candidate resolves it.

{total-tasks} {task|tasks} planned.

This plan is a draft. State a correction and it will be updated.
This plan is a draft. Check its assumptions first; state any correction and it will be updated.

Next step:

Expand Down
31 changes: 16 additions & 15 deletions .agents/skills/sce-change-to-plan/references/plan-authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,22 @@

Run this phase for step 2 of the workflow, and again for each revision in step 4.

Input: the change request, and the complete `loaded` brief from the context load
phase. Pass the brief verbatim; do not restate, summarize, or reinterpret it.
Inputs are one of:

- Initial authoring: `change_request` and `loaded_context_brief`.
- Clarification continuation: `original_request`, `clarification_answers`,
and `loaded_context_brief`.
- Existing-plan revision: `plan_path`, `correction`, and
`loaded_context_brief`.

Pass `loaded_context_brief` verbatim.

For clarification continuation, preserve `original_request` and resolve it with
the supplied `clarification_answers`.

For an existing-plan revision, read `plan_path` and interpret `correction`
against that plan. A terse correction is not ambiguous merely because it omits
scope and terminology already present in the plan.

This phase owns the planning process:

Expand All @@ -29,19 +43,6 @@ The context brief is the durable memory this plan starts from. Treat its
`key_facts` as recorded current state, its `gaps` as areas with no durable
context, and its `drift` as recorded context that no longer matches the code.

When no brief is supplied, load the context named by the change request before
authoring, and follow the selection discipline in *Inspect relevant context*.

Answers the user gave to earlier clarification questions arrive as part of the
change request. Incorporate them into the plan.

A revision of a plan authored earlier in the session also arrives as the change
request, and it is usually terse: a task boundary the user disagrees with, an
ordering they want changed, work they want added or dropped. Read it against the
existing plan, which supplies the scope, criteria, and terminology it omits.
Terseness is not ambiguity. Do not set internal status `needs_clarification` for
detail the plan already carries; ask only when the revision itself is genuinely
undecidable.

## 2.1 Resolve the plan target

Expand Down
6 changes: 3 additions & 3 deletions .agents/skills/sce-commit/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,12 @@ description: >

Own this workflow from input through its terminal user-visible response.
Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them.
Keep internal phase results private and continue immediately until a defined wait or stop.
Keep intermediate workflow state private and continue immediately until a defined wait or stop.
Resume user waits in this same skill and session.
Render user-visible output only from the named workflow layouts or phase reports.
Render user-visible output only from the named workflow layouts or reports.
Do not expose raw internal state or add text around a rendered layout or report.
Non-SCE helpers may assist, but must return to the active step without changing
phase order, gates, waits, writes, validation, stops, or terminal output.
workflow order, gates, waits, writes, validation, stops, or terminal output.
Do not invoke another SCE skill, package, or workflow command.

## Phase reference
Expand Down
31 changes: 16 additions & 15 deletions .agents/skills/sce-commit/references/atomic-commit.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,8 @@ changes.

### 4. Write each message

Follow `references/commit-message-style.md` for the subject pattern, the body
rules, issue references, the plan-citation rule, and the anti-patterns.
Follow `references/commit-message-style.md` for the subject pattern, body
rules, and issue references.

### 5. Apply the plan-citation rule

Expand All @@ -73,18 +73,7 @@ cite faithfully:
- In `bypass` mode, infer the citation when the diff supports it, and otherwise
omit it. Never stop, and never invent a slug or task ID.

### 6. Apply context-file guidance gating

This step applies in `regular` mode only. Skip it entirely in `bypass` mode; do
not classify staged scope there.

Classify the staged diff:

- Context-only (`context/**`): context-file-focused guidance is allowed.
- Mixed (`context/**` plus non-`context/**`): suppress default context-file
commit reminders and give guidance that reflects the full staged scope.

### 7. Propose split guidance
### 6. Propose split guidance

This step applies in `regular` mode only.

Expand All @@ -95,7 +84,7 @@ each.
When the staged changes form one unit, return one message and no split
guidance. Do not split coherent work to appear thorough.

### 8. Validate the result
### 7. Validate the result

Confirm before returning that:

Expand All @@ -104,6 +93,18 @@ Confirm before returning that:
- No plan slug or task ID appears that the staged diff does not support.
- The mode's own constraints hold.

## Result contract

Return exactly one internal result:

- `blocked`: one or more issues, each carrying its problem, impact, and
required decision.
- `proposal`: regular mode only. Include one or more commits, each with its
complete message and covered files. Include split rationale only when more
than one commit is returned.
- `bypass_message`: bypass mode only. Include exactly one complete message and
the full staged file list.

## Bypass execution handoff

This subsection is the sole definition of the bypass execution sequence. This
Expand Down
13 changes: 1 addition & 12 deletions .agents/skills/sce-commit/references/commit-message-style.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Use this repository style when writing new commits.
- Start with `scope: Subject` for most code changes.
- Common scopes: `runtime`, `language`, `objects`, `tests`, `CI`, `README`.
- Combined scopes are fine when needed (for example `language+runtime`).
- Use an imperative verb in the subject: `Fix`, `Add`, `Refactor`, `Remove`, `Implement`, `Update`, `Rewrite`, `Use`, `Allow`.
- Use an imperative verb in the subject.
- Keep the subject specific and technical (name the subsystem and actual change).
- Keep the subject to one line and do not end it with a period.
- Add a body when the change is non-trivial.
Expand All @@ -31,14 +31,3 @@ Use this repository style when writing new commits.
Fixes #<id> (optional)
```

## Size-based defaults

1. Small fix: subject + 1 short reason line.
2. Medium refactor: subject + short why + short what changed.
3. Large architectural change: subject + context + bullets for major changes + impact/tradeoffs.

## Anti-patterns to avoid

- Vague subjects like "misc updates" or "cleanup".
- Bodies that only repeat the subject without explaining why or impact.
- Overly playful tone in serious bug-fix or architectural change.
38 changes: 19 additions & 19 deletions .agents/skills/sce-decision/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,18 @@
---
name: sce-decision
description: >
Write one immutable ADR for one decision already qualified by context synchronization
Record one already-qualified decision as an immutable ADR, reusing an equivalent active ADR when present
---

# SCE Decision

## Purpose

Write exactly one architecture decision record for one decision already qualified
by successful task context synchronization. Return a deterministic internal
result to the invoking synchronization phase. Do not render an independent
user-visible response.
Resolve exactly one architecture decision record for one decision already
qualified by successful task context synchronization. Reuse an equivalent active
ADR when one exists; otherwise write a new immutable ADR. Return a deterministic
internal result to the invoking synchronization phase. Do not render an
independent user-visible response.

## Input

Expand All @@ -21,7 +22,7 @@ synchronization. It must identify:
- One decision stated as a single durable choice.
- Why it qualifies under the decision gate.
- The implementation / task-verification evidence establishing the decision.
- The resolved plan path and relevant task IDs, when applicable.
- The resolved plan path, plus relevant task IDs when applicable.
- Related current-state context and existing ADR paths.
- An optional requested status.

Expand All @@ -38,9 +39,9 @@ rerun that threshold here.
Require the request to state why the caller qualified the decision and include
supporting evidence. If the request explicitly represents a nonqualifying gate
outcome, return `not_qualified` (or `skipped` when the caller deliberately skipped
the gate) without writing an ADR. If a claimed qualification is unsupported by
its supplied evidence, return `not_qualified`. Missing, contradictory, or
otherwise unsafe material input remains `blocked`.
the gate) without writing an ADR. For a qualified request, do not reassess the
qualification threshold. Missing or contradictory qualification evidence is
unsafe decision-writing input and returns `blocked`.

`not_qualified` and `skipped` are non-blocking to the invoking synchronization
phase.
Expand Down Expand Up @@ -68,7 +69,8 @@ Read `context/decisions/` and the supplied related ADR paths before writing.
- Reuse an existing ADR only when it records an equivalent decision and has an
active status: `Proposed` or `Accepted`. Return its path without creating a
duplicate. Never reuse a `Rejected`, `Deprecated`, or `Superseded` ADR.
- Existing ADRs are immutable regardless of status. Never edit an ADR whose status is `Accepted`; do not edit, overwrite, or silently change the status of any existing record.
- Existing ADRs are immutable regardless of status; never edit, overwrite, or
change the status of an existing record.
- A correction, reversal, or any changed decision always creates a new dated ADR;
it references and supersedes the prior record when applicable, rather than
modifying that record.
Expand Down Expand Up @@ -98,19 +100,19 @@ synchronization phase owns linking the new ADR from authoritative context.

Confirm that exactly one ADR was created or one existing matching ADR was reused;
the filename, status, sections, and references satisfy this contract; every
referenced repository path exists when practical to check; and no accepted ADR
referenced repository path exists when practical to check; and no existing ADR
was modified.

### 6. Return the result

Return exactly one internal result:

- `written`: include `status`, `adr_path`, `decision`, `decision_status`,
`created` (`true` for a new ADR and `false` for reuse), `supersedes`, and
concise verification evidence.
- `not_qualified` or `skipped`: include `status`, the reason the decision gate
did not produce an ADR, and concise supporting evidence. These results are
non-blocking; the invoking synchronization phase continues normally.
`created` (`true` for a new ADR and `false` for reuse), `supersedes` (the prior
ADR path or `null`), and `verification`.
- `not_qualified` or `skipped`: include `status`, `reason`, and `evidence`.
These results are non-blocking; the invoking synchronization phase continues
normally.
- `blocked`: include `status`, the specific `problem`, its `impact`, and the
`required_action`. Use this only when decision writing cannot proceed safely.

Expand All @@ -125,8 +127,6 @@ Do not:
- Write more than one ADR per request.
- Run outside successful task context synchronization.
- Create a command, prompt, context root, or decisions directory.
- Modify application code, tests, plans, current-state context, or existing
accepted ADRs.
- Treat every context update as an architecture decision.
- Modify application code, tests, plans, current-state context, or existing ADRs.
- Choose among unresolved material alternatives on the user's behalf.
- Create a Git commit or push changes.
4 changes: 4 additions & 0 deletions .agents/skills/sce-decision/references/adr-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ Supersedes: `{context/decisions/YYYY-MM-DD-prior-decision.md}`

Omit `Task` or `Supersedes` only when it does not apply. Do not omit `Plan`.

Populate sections only from the validated request and supporting evidence. Do
not invent content to satisfy the template; when the evidence establishes no
content for a section, record `None documented.` instead.

## Context

{Forces, constraints, and evidence that require this decision.}
Expand Down
27 changes: 7 additions & 20 deletions .agents/skills/sce-handover/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,12 @@ description: >

Own this workflow from input through its terminal user-visible response.
Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them.
Keep internal phase results private and continue immediately until a defined wait or stop.
Keep intermediate workflow state private and continue immediately until a defined wait or stop.
Resume user waits in this same skill and session.
Render user-visible output only from the named workflow layouts or phase reports.
Render user-visible output only from the named workflow layouts or reports.
Do not expose raw internal state or add text around a rendered layout or report.
Non-SCE helpers may assist, but must return to the active step without changing
phase order, gates, waits, writes, validation, stops, or terminal output.
workflow order, gates, waits, writes, validation, stops, or terminal output.
Do not invoke another SCE skill, package, or workflow command.

## Input
Expand Down Expand Up @@ -82,14 +82,15 @@ confirmed facts.
#### 4. Confirm the context root

When `context/` does not exist, there is no durable location to write to.
Do not create it; `sce setup --bootstrap-context` owns context bootstrap.
Render the **Writer blocked** layout with `sce setup --bootstrap-context` as
the required action, and stop without writing a file.

#### 5. Write exactly one file

Write the composed document to the path resolved in step 2. Before reporting
success, validate the written file against the template's **Completeness
contract**.
Write only the composed handover document to the path resolved in step 2.
Do not change plan or task state or edit any other file. Before reporting
success, validate the written file against the template's **Completeness contract**.

#### 6. Report

Expand Down Expand Up @@ -129,17 +130,3 @@ step for continuation in the current session.
Loading is read-only: do not edit any file, mark a plan task complete, change
repository state, or begin the recommended next step. Presenting the loaded
guidance is the entire loader contract.

## Rules

- Handle at most one handover per invocation, in exactly one mode.
- Writer mode never overwrites an existing handover file.
- Writer mode never marks a plan task complete or edits any file outside the
one handover document it writes.
- Loader mode never edits a file, writes a new file, or changes plan or task
state.
- Never invoke another SCE skill, sibling SCE package, or SCE workflow command.
- Never treat a file outside `context/handovers/`, or a non-Markdown file, as a
loadable handover.
- Never create the `context/` root; `sce setup --bootstrap-context` owns that.
- Do not begin, plan, or automate the loaded handover's recommended next step.
6 changes: 3 additions & 3 deletions .agents/skills/sce-next-task/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,12 @@ description: >

Own this workflow from input through its terminal user-visible response.
Follow its steps, gates, and stops in order; do not add, skip, reorder, or merge them.
Keep internal phase results private and continue immediately until a defined wait or stop.
Keep intermediate workflow state private and continue immediately until a defined wait or stop.
Resume user waits in this same skill and session.
Render user-visible output only from the named workflow layouts or phase reports.
Render user-visible output only from the named workflow layouts or reports.
Do not expose raw internal state or add text around a rendered layout or report.
Non-SCE helpers may assist, but must return to the active step without changing
phase order, gates, waits, writes, validation, stops, or terminal output.
workflow order, gates, waits, writes, validation, stops, or terminal output.
Do not invoke another SCE skill, package, or workflow command except `sce-decision`,
and only from the successful context-synchronization decision gate.

Expand Down
5 changes: 1 addition & 4 deletions .agents/skills/sce-next-task/references/output.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,9 +71,6 @@ Run the final validation:

# Implementation gate

Always show this gate at the start of the **Task execution phase**, before editing any
file.

The gate is user-facing prose. It is never serialized into a YAML result. This
file is the only authority for the gate's content and order.

Expand Down Expand Up @@ -104,7 +101,7 @@ file is the only authority for the gate's content and order.

## Approach

Describe the smallest coherent implementation approach in 2–5 steps.
Describe the smallest coherent implementation approach with enough detail for approval.

## Assumptions

Expand Down
Loading
Loading