sspec 2.4.2__tar.gz → 2.6.0__tar.gz

{sspec-2.4.2/tmp/readme_sync → sspec-2.6.0}/.agents/skills/sspec-align/SKILL.md

@@ -1,95 +1,93 @@
----
-name: sspec-align
-description: "Structured, efficient agent-user synchronization at decision points. Formalized exchange over prose."
-metadata:
-  author: frostime
-  version: 12.0.0
----
-
-# SSPEC Align
-
-`@align` is how agents synchronize with users at decision points — **efficiently, structurally, and with minimal friction**. The goal is 5-second scan, instant decision.
-
-**Core principle**: Every @align must answer three questions — What happened? What needs deciding? What are the options? — in structured format, not prose.
-
----
-
-## 1. Levels (When)
-
-| Level | Agent behavior | Typical situations |
-|---|---|---|
-| `report` | Structured summary, **keep going** | Plan done, progress update, low-risk confirmation |
-| `gate` | Structured summary, **stop and wait** | Design done, implement complete, blocker, scope change, irreversible action |
-
-**Rule**: If safe progress depends on a user decision, the agent MUST use `gate`. Otherwise prefer `report`.
-
----
-
-## 2. Presentation (How)
-
-@align information MUST use structured format. Prose-style @align is an anti-pattern.
-
-### Required format elements
-
-- **Tables** for comparisons, options, scope summaries
-- **Labeled items** for decisions, risks, constraints
-- **Code blocks** for interfaces, commands, config
-- **Explicit decision point** — atomic, confirmable question at the end
-
-### Anti-patterns
-
-```
-❌ Prose @align:
-"I've been thinking about the design and I believe we should
-split the service into three parts. The first handles auth,
-the second manages sessions, and the third provides the API.
-What do you think?"
-
-✅ Structured @align:
-## Design Gate
-
-| Component | Source → Target | Responsibility |
-|-----------|----------------|----------------|
-| Auth      | `handlers/monolith.py` → `services/auth.py` | Authentication |
-| Session   | `middleware/chain.py` → `services/session.py` | State mgmt |
-| API       | (new) `api/surface.py` | Thin wrapper |
-
-**Rationale**: Testability + independent deployment
-**Risk**: Migration complexity (feature flag mitigates)
-
-→ Proceed with this split?
-```
-
-### Context and decision separation
-
-1. Present structured context in normal output (tables, diagrams, labeled items)
-2. Use `question-like` tool ONLY for the final concise ask
-3. MUST NOT stuff analysis, tradeoff tables, or multi-paragraph context into the question tool payload
-
----
-
-## 3. Tools (What)
-
-- If a built-in `question`-like tool is available → use it for the final ask
-- Otherwise, if `sspec tool ask` is available → use it as fallback
-- Otherwise → state the question clearly in output, end turn
-
-For large context, write analysis to `.sspec/tmp/` and link it instead of pasting inline.
-
-Fallback tool usage reference: `sspec tool ask --prompt`
-
----
-
-## 4. After Align — Records
-
-Alignment without record = information lost on next session.
-
-| What changed | Where to record |
-|---|---|
-| Design confirmed/revised | `spec.md` / `design.md` |
-| Plan confirmed/revised | `tasks.md` |
-| Direction changed, key decision made | `memory.md` Knowledge |
-| User feedback received | `memory.md` Knowledge (new entry) |
-| Scope/design change after gate | `revisions/NNN-*.md` + `tasks.md` |
-
-**No separate ask record is required.** Put the decision in its natural home.
+---
+name: sspec-align
+description: "Structured, efficient agent-user synchronization at decision points. Formalized exchange over prose."
+metadata:
+  author: frostime
+  version: 12.0.0
+---
+
+# SSPEC Align
+
+**Core principle**: Every @align must answer three questions — What happened? What needs deciding? What are the options? — in structured format, not prose. Goal: 5-second scan, instant decision.
+
+---
+
+## 1. Levels (When)
+
+| Level | Agent behavior | Typical situations |
+|---|---|---|
+| `report` | Structured summary, **keep going** | Plan done, progress update, low-risk confirmation |
+| `gate` | Structured summary, **stop and wait** | Design done, implement complete, blocker, scope change, irreversible action |
+
+**Rule**: If safe progress depends on a user decision, the agent MUST use `gate`. Otherwise prefer `report`.
+
+---
+
+## 2. Presentation (How)
+
+@align information MUST use structured format. Prose-style @align is an anti-pattern.
+
+### Required format elements
+
+- **Tables** for comparisons, options, scope summaries
+- **Labeled items** for decisions, risks, constraints
+- **Code blocks** for interfaces, commands, config
+- **Explicit decision point** — atomic, confirmable question at the end
+
+### Anti-patterns
+
+```
+❌ Prose @align:
+"I've been thinking about the design and I believe we should
+split the service into three parts. The first handles auth,
+the second manages sessions, and the third provides the API.
+What do you think?"
+
+✅ Structured @align:
+## Design Gate
+
+| Component | Source → Target | Responsibility |
+|-----------|----------------|----------------|
+| Auth      | `handlers/monolith.py` → `services/auth.py` | Authentication |
+| Session   | `middleware/chain.py` → `services/session.py` | State mgmt |
+| API       | (new) `api/surface.py` | Thin wrapper |
+
+**Rationale**: Testability + independent deployment
+**Risk**: Migration complexity (feature flag mitigates)
+
+→ Proceed with this split?
+```
+
+### Context and decision separation
+
+1. Present structured context in normal output (tables, diagrams, labeled items)
+2. Use `question-like` tool ONLY for the final concise ask
+3. MUST NOT stuff analysis, tradeoff tables, or multi-paragraph context into the question tool payload
+
+---
+
+## 3. Tools (What)
+
+- If a built-in `question`-like tool is available → use it for the final ask
+- Otherwise, if `sspec tool ask` is available → use it as fallback
+- Otherwise → state the question clearly in output, end turn
+
+For large context, write analysis to `.sspec/tmp/` and link it instead of pasting inline.
+
+Fallback tool usage reference: `sspec tool ask --prompt`
+
+---
+
+## 4. After Align — Records
+
+Alignment without record = information lost on next session.
+
+| What changed | Where to record |
+|---|---|
+| Design confirmed/revised | `spec.md` / `design.md` |
+| Plan confirmed/revised | `tasks.md` |
+| Direction changed, key decision made | `memory.md` Knowledge |
+| User feedback received | `memory.md` Knowledge (new entry) |
+| Scope/design change after gate | `revisions/NNN-*.md` + `tasks.md` |
+
+**No separate ask record is required.** Put the decision in its natural home.

sspec-2.6.0/.agents/skills/sspec-clarify/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: sspec-clarify
+description: "Build shared understanding through dialogue and investigation. Produces Problem Statement + direction sketch. Reusable posture, not rigid phase."
+metadata:
+  author: frostime
+  version: 6.1.3
+---
+
+# SSPEC Clarify
+
+Clarify excavates the problem space: combine user intent + system reality until Design can be a cheap, faithful proxy the user can judge before implementation.
+
+Clarify is a **posture**, not a rigid phase. Re-enter it whenever understanding drifts: Review feedback, implementation contradiction, revision, or scope drift.
+
+**No implementation**: dialogue + investigation only. Do NOT modify code/files except notes.
+
+## Workflow
+
+```text
+Subjective intent ↔ Objective reality → Synthesis → Adversarial audit → Design readiness
+```
+
+Subjective and Objective interleave. Gather whichever side is currently missing.
+
+## Multi-round Decision-tree Clarify
+
+For non-trivial work, use visible rounds. Small obvious fixes may need one short round; vague, architectural, or high-risk requests need multiple rounds.
+
+Each clarification turn MUST:
+
+- Start with `Clarify Round <n>`
+- Provide enough working model for the user to judge the questions: current framing + relevant evidence + decision-tree status
+- After Round 1, prefer delta-only unless framing changed or audit is needed
+- Show decision-tree status relevant to the current question group: closed / opened / revised / classified branches
+- Group questions by dependency: independent branches together; dependent branches across rounds
+- Include the agent's recommended answer or current bet for each question group
+- Explain impact when non-obvious
+
+Incomplete round: asks surface choices without enough working model or decision-tree context for the user to judge them.
+
+Decision tree inputs:
+
+- User intent and priorities
+- Readable system reality: code, docs, project state
+- Trusted external-source reality when relevant: official docs, standards, deprecations, common practice, or current web sources
+- User-supplied external constraints
+- Contradictions between intent, system facts, external sources, and user constraints
+
+### Branch Severity
+
+| Type | Meaning | Action |
+|---|---|---|
+| Blocker | Could change problem framing, scope, user-visible behavior, risk, or implementation direction | Resolve before Design |
+| Assumption | Safe to proceed if explicit and reviewable | Record |
+| Deferred | Intentionally out of current scope/phase | Record boundary |
+| Irrelevant | Does not affect Design | Drop |
+
+## Step 1: Subjective — User Intent
+
+User words are raw input, not the requirement itself.
+
+Do:
+
+- Separate goal / symptom / proposed solution
+- Watch for XY problem: user may describe means rather than goal
+- Surface boundaries, priorities, unknowns, and success criteria
+- State your framing first so the user can correct it
+
+Socratic patterns:
+
+| Pattern | Example |
+|---|---|
+| Restate | "My understanding is we need X, not Y — correct?" |
+| Boundary | "This excludes W — correct?" |
+| Priority | "If only one outcome matters, which one?" |
+| Unknown | "I am unsure whether Z applies — does it?" |
+
+Recursive MECE:
+
+- Branches at each layer are non-overlapping and no-gaps
+- Each answered branch narrows the tree and may expose sub-branches
+- Continue until no open branch would materially change Design
+- Scale depth to task complexity
+
+## Step 2: Objective — Codebase/System Reality
+
+Investigate facts the user should not need to answer.
+
+Read as relevant:
+
+- `project.md`, `spec-docs/`, existing change memory files
+- Architecture, integration points, existing patterns
+- Hidden constraints, edge cases, and external API/system behavior
+- Trusted external sources via available tools/skills when current outside reality matters; prefer authoritative source pages and cite them
+- Existing changes via `sspec change list` or `sspec change find <name>`
+
+Rule: if code/docs/system state can answer a question, investigate instead of asking. Ask the user for intent, priorities, external constraints, and judgments the system cannot reveal.
+
+Feed findings into dialogue: "You said X; the system shows Y. Does that change the framing?"
+
+## Step 3: Synthesis
+
+When intent and reality have collided enough, sketch:
+
+1. **Problem Statement** — actual problem, not surface symptom
+2. **Direction** — approach that fits intent + reality
+3. **Open questions** — classified by Branch Severity
+
+Evidence map:
+
+- User-confirmed intent
+- Codebase/system evidence
+- Trusted external-source evidence when used
+- User-supplied external constraints
+- Explicit assumptions
+
+Design should formalize this sketch, not discover it from scratch.
+
+## Adversarial Audit
+
+Before Design for non-trivial work, challenge the framing.
+
+| Probe | Question |
+|---|---|
+| Alternative framing | If this is the wrong problem, what is the real one? |
+| Counter-evidence | What fact would contradict this direction? Can it be checked now? |
+| Smaller solution | What narrower change could satisfy the outcome? |
+| Failure forecast | What later failure would prove Clarify missed something? |
+| Boundary/term attack | Which terms, actors, states, or responsibilities are ambiguous? |
+
+If the audit opens a blocker, continue Clarify.
+
+## Optional Subagent Review
+
+Use for complex, vague, high-impact, or anchoring-prone Clarify when the environment supports a subagent: an isolated secondary agent/context that receives a limited brief.
+
+Brief the subagent with only: working model, confirmed facts, stable file/doc pointers, and request to find missing branches, alternative framings, contradictions, or premature-exit risks. Subagent critiques; main agent verifies claims and decides.
+
+## Minimal Few-shot: Incomplete Clarify
+
+Schematic only; replace placeholders with task facts.
+
+Bad:
+
+```text
+Clarify Round 1:
+Questions:
+- Which label should the result use?
+- Which optional behavior should be included?
+- Which result format should be used?
+
+User answers → Agent enters Design.
+```
+
+Why bad: surface choices only; no working model, decision tree, adversarial check, or open-question classification.
+
+Better:
+
+```text
+Clarify Round 1:
+Model: desired outcome / proposed change / known reality / possible mismatch
+Tree: closed / opened / revised / classified branches
+Questions:
+- Framing group — my bet: ...; impact: ...; confirm/correct?
+- Boundary group — my bet: ...; impact: ...; confirm/correct?
+```
+
+## Memory Management
+
+- Short Clarify (≤5 exchanges): no artifact needed; carry result into Design.
+- Long Clarify (>10 exchanges or research-heavy): create notes with `sspec tmp new clarify_<topic>`; the command adds the timestamp prefix.
+- After change creation, move relevant materials to `change/reference/`.
+- Key decisions/turning points → memory.md Knowledge during Design.
+- Capture reasoning before Design; context compression can erase it.
+
+## Exit Gate
+
+Enter Design only when all are true:
+
+- Problem, boundaries, direction, and open questions are articulable by both sides
+- Working model cites intent, system evidence, constraints, and assumptions
+- No blocker remains unresolved or implicit
+- Remaining questions are classified: blocker / assumption / deferred / irrelevant
+- Adversarial audit has not exposed a design-changing branch
+- Notes record assumptions and open decisions
+
+Usually exit with `Clarify Round <n> — Audit`, then transition to `sspec-design`.

{sspec-2.4.2/src/sspec/templates → sspec-2.6.0/.agents}/skills/sspec-design/SKILL.md

@@ -3,7 +3,7 @@ name: sspec-design
 description: "Assess scale, create change, fill spec.md + design.md, align with user. Use after clarify when ready to define the solution."
 metadata:
   author: frostime
-  version: 5.0.0
+  version: 5.1.0
 ---
 
 # SSPEC Design
@@ -68,9 +68,7 @@ sspec change scaffold design <change>  # create design.md from template
 
 ### Writing design.md — Prediction Contract
 
-spec + design is a **prediction contract**: the user reads it and predicts what the code will look like. Your job is to think carefully about which dimensions to cover so the user feels in control of this change.
-
-**Guiding question**: What does the user need to predict to feel in control? Answer this for the specific change, then choose dimensions accordingly.
+spec + design is a **prediction contract**: the user reads it and predicts the resulting code. Choose the dimensions that make that prediction possible for this specific change.
 
 **Common dimensions** (examples, not checklist — pick what serves prediction):
 
@@ -84,11 +82,9 @@ spec + design is a **prediction contract**: the user reads it and predicts what
 | Content Outline | "What's the content structure?" | Documents, templates, specs | Heading tree / outline |
 | Migration Path | "How do we get from here to there?" | Compatibility, rollback, versioning | Step list + constraints |
 
-Custom dimensions are fine — use whatever makes the prediction clearer.
-
-**Minimum quality bar**: design.md MUST contain at least one structured artifact (code block, diagram, table, or labeled items). Pure prose design is not acceptable.
+Custom dimensions are fine.
 
-**Key principle**: show, don't describe. `def process(x: Input) -> Output` beats "a function that accepts X and returns Y".
+**Minimum quality bar**: design.md MUST contain at least one structured artifact (code block, diagram, table, or labeled items). Show, don't describe — `def process(x: Input) -> Output` beats "a function that accepts X and returns Y".
 
 ### spec.md vs design.md boundary
 

{sspec-2.4.2 → sspec-2.6.0}/.agents/skills/sspec-implement/SKILL.md

@@ -8,8 +8,6 @@ metadata:
 
 # SSPEC Implement
 
-Execute the approved plan. Work through tasks.md systematically.
-
 ---
 
 ## Core Rules
@@ -25,7 +23,7 @@ Execute the approved plan. Work through tasks.md systematically.
 | Situation | Action |
 |-----------|--------|
 | Task is ambiguous | `@align` for clarification |
-| Implementation reveals design issue | See **Post-Gate Design Changes** below |
+| Implementation reveals design issue | See **Design Changes During Implementation** below |
 | Blocker encountered | Record in `memory.md`, `@align` user |
 | Multiple valid approaches | Pick the simpler one, note in memory |
 | Design assumption was wrong | Re-enter Clarify posture: "Design says X but I found Y" → re-sync with user before revising |

{sspec-2.4.2/tmp/readme_sync → sspec-2.6.0}/.agents/skills/sspec-plan/SKILL.md

@@ -1,63 +1,61 @@
----
-name: sspec-plan
-description: "Break design into concrete tasks. Fill tasks.md with file-level execution plan. Use after design alignment."
-metadata:
-  author: frostime
-  version: 3.0.0
----
-
-# SSPEC Plan
-
-Turn the approved design into a concrete, file-level execution plan in tasks.md.
-
----
-
-## Output Contract
-
-When this phase ends, tasks.md MUST contain:
-- Phases with file-level tasks (single/sub) OR milestones (root)
-- Verification criteria for each phase
-- Progress section initialized
-
-## Task Quality Standards
-
-Each task SHOULD be:
-- **Specific**: names exact file path + action
-- **Small**: <2 hours
-- **Independently testable**: has an obvious check
-
-## Reference Spec, Don't Repeat
-
-tasks.md references spec.md / design.md — never re-describe design.
-
-| spec.md / design.md | tasks.md |
-|---|---|
-| Defines interfaces, data model, logic | Lists file-level actions + verification |
-| Explains *how it should work* | Tells agent *what to do next* |
-| `get_cached_user(id) -> Optional[User]` | `Create cache.py — implement interface per spec` |
-
-- ✅ "Implement Fix A per spec"
-- ✅ "Create handler following the data flow in design.md"
-- ❌ Re-listing all function signatures
-- ❌ Re-describing the algorithm
-
-## Single/Sub vs Root
-
-| change-type | tasks.md form |
-|------------|---------------|
-| `single` / `sub` | Phase-based, file-level tasks (<2h each) |
-| `root` | Milestone-based, one entry per sub-change (no file-level detail) |
-
-Root rules: no file-level tasks; each phase has Deliverable + Sub-change link; root stays active until all sub-changes complete.
-
-## Verification
-
-Each phase MUST have explicit verification criteria:
-- What to check (test commands, expected output, manual verification)
-- How to know it's done (not "it works" but specific criteria)
-
-## Exit: @align Report
-
-Present the task breakdown (phases, total tasks, key verification criteria). This is a `report`, not a hard gate — continue to `sspec-implement` unless the user interrupts.
-
-📚 Examples: [examples.md](./examples.md)
+---
+name: sspec-plan
+description: "Break design into concrete tasks. Fill tasks.md with file-level execution plan. Use after design alignment."
+metadata:
+  author: frostime
+  version: 3.0.0
+---
+
+# SSPEC Plan
+
+---
+
+## Output Contract
+
+When this phase ends, tasks.md MUST contain:
+- Phases with file-level tasks (single/sub) OR milestones (root)
+- Verification criteria for each phase
+- Progress section initialized
+
+## Task Quality Standards
+
+Each task SHOULD be:
+- **Specific**: names exact file path + action
+- **Small**: <2 hours
+- **Independently testable**: has an obvious check
+
+## Reference Spec, Don't Repeat
+
+tasks.md references spec.md / design.md — never re-describe design.
+
+| spec.md / design.md | tasks.md |
+|---|---|
+| Defines interfaces, data model, logic | Lists file-level actions + verification |
+| Explains *how it should work* | Tells agent *what to do next* |
+| `get_cached_user(id) -> Optional[User]` | `Create cache.py — implement interface per spec` |
+
+- ✅ "Implement Fix A per spec"
+- ✅ "Create handler following the data flow in design.md"
+- ❌ Re-listing all function signatures
+- ❌ Re-describing the algorithm
+
+## Single/Sub vs Root
+
+| change-type | tasks.md form |
+|------------|---------------|
+| `single` / `sub` | Phase-based, file-level tasks (<2h each) |
+| `root` | Milestone-based, one entry per sub-change (no file-level detail) |
+
+Root rules: no file-level tasks; each phase has Deliverable + Sub-change link; root stays active until all sub-changes complete.
+
+## Verification
+
+Each phase MUST have explicit verification criteria:
+- What to check (test commands, expected output, manual verification)
+- How to know it's done (not "it works" but specific criteria)
+
+## Exit: @align Report
+
+Present the task breakdown (phases, total tasks, key verification criteria). This is a `report`, not a hard gate — continue to `sspec-implement` unless the user interrupts.
+
+📚 Examples: [examples.md](./examples.md)