@skilly-hand/skilly-hand 0.29.2 → 0.30.0

package/catalog/skills/spec-driven-development/agents/apply.md

@@ -2,25 +2,40 @@
 
 ## Purpose
 
-Implement approved spec tasks in small, verifiable increments.
+Implement approved tasks one at a time and keep the spec synchronized with execution evidence.
 
-## Inputs
+## Procedure
 
-- Spec name/path under `.sdd/active/`.
-- Task range or specific task IDs.
+1. Read `spec.md`, relevant design decisions, and repository instructions.
+2. Confirm the approval policy is satisfied and dependencies are `DONE`.
+3. Resolve required capabilities from available local skills, tools, or structured self-review.
+4. Mark the selected task `IN_PROGRESS`.
+5. Implement only the assigned outcome.
+6. When the task declares test-driven work, follow the available TDD guidance or the portable RED/GREEN/REFACTOR contract described in the task.
+7. Run the task verify step using commands discovered from the project.
+8. Record concise evidence: command or check, result, and relevant output summary.
+9. Mark the task `DONE` only after verification passes; otherwise mark it `BLOCKED` with the cause.
+10. Append a change-log entry only for requirement, scope, or design changes, not routine progress.
 
-## Procedure
+## Scope Change Rule
+
+If implementation reveals new behavior, conflicting constraints, or a wider blast radius, stop the affected task and return it to planning. Do not silently add work or rewrite acceptance criteria to match the implementation.
+
+## Evidence Contract
+
+Evidence must be reproducible and proportionate:
+
+```text
+Check: <command or manual procedure>
+Result: PASS | FAIL | NOT_RUN
+Summary: <short factual result>
+```
 
-1. Read `spec.md` and `design.md` (if present).
-2. Execute one task at a time.
-3. Keep changes scoped to the assigned task.
-4. Run the task verify step before marking done.
-5. Record progress against task IDs.
-6. Stop and report blockers when constraints conflict.
+Do not claim a command ran when it did not. Record unavailable or human-only checks explicitly.
 
 ## Quality Bar
 
-- Behavior matches task intent.
-- Verify steps pass before moving on.
-- No hidden scope creep.
-- Progress summary lists completed tasks and changed files.
+- Changes remain inside task scope.
+- Verification evidence supports the `DONE` state.
+- Optional integrations have a documented local fallback.
+- No automatic commit, issue update, or remote action is assumed.

package/catalog/skills/spec-driven-development/agents/orchestrate.md

@@ -2,24 +2,33 @@
 
 ## Purpose
 
-Coordinate planning, implementation, and verification through explicit checkpoints.
+Coordinate planning, implementation, verification, and archive while remaining usable without delegation or external integrations.
 
-## Inputs
+## Workflow
 
-- High-level request.
-- Context and constraints.
+1. PLAN: create or update the active spec.
+2. APPROVE: apply the spec's checkpoint or self-review policy.
+3. APPLY: execute one ready task at a time.
+4. VERIFY TASK: require evidence before selecting the next task.
+5. REPLAN: return changed requirements or blocked dependencies to planning.
+6. VERIFY FEATURE: run validation and the portable final review gate.
+7. ARCHIVE: enforce archive invariants and move the completed work once.
 
-## Workflow
+## Capability Resolution
+
+- Delegate a phase only when a suitable capability is available and delegation improves the outcome.
+- Otherwise execute the corresponding local mode directly.
+- Never invent resource names, identifiers, issue keys, commands, or service availability.
+- Remote writes, commits, and comments require their own discovered workflow and user authorization.
+
+## Checkpoint Policy
 
-1. PLAN: Produce or update the spec.
-2. REVIEW CHECKPOINT: Confirm the plan is approved.
-3. APPLY: Execute agreed task batch.
-4. VERIFY CHECKPOINT: Validate outputs against the spec and run the required final `review-rangers` gate.
-5. REPEAT: Continue by phase or task batch.
-6. ARCHIVE: Move completed work from `.sdd/active/` to `.sdd/archive/`.
+Pause for explicit user approval when required by the spec, risk, ambiguity, or an irreversible action. For low-risk autonomous work, record a self-review decision and continue.
 
 ## Coordination Rules
 
-- Pause at checkpoints before continuing.
-- Keep phase summaries short and decision-oriented.
-- Surface blockers with options, not ambiguity.
+- Keep `spec.md` authoritative.
+- Keep at most one task `IN_PROGRESS` unless independence is explicit.
+- Do not advance past failed verification.
+- Surface blockers with evidence and the smallest decision needed.
+- Do not declare completion while open tasks or unresolved blockers remain.

package/catalog/skills/spec-driven-development/agents/plan.md

@@ -2,26 +2,28 @@
 
 ## Purpose
 
-Turn a request into an executable, reviewable spec before implementation starts.
-
-## Inputs
-
-- Goal or problem statement.
-- Known constraints.
-- Current state references (files, systems, behaviors).
+Turn a request into an executable spec without assuming a framework, toolchain, or external service.
 
 ## Procedure
 
-1. Clarify scope and success criteria.
-2. Decide full spec vs delta spec.
-3. Fill spec sections: Why, What, Constraints, Current State, Tasks, Validation.
-4. Break tasks into small units with explicit verify commands.
-5. Add `design.md` if architecture decisions or trade-offs are non-obvious.
-6. Return the spec summary for review and approval.
+1. Inspect the repository for applicable instructions, conventions, commands, and existing behavior.
+2. Clarify only missing information that cannot be discovered safely.
+3. Choose a full or delta spec.
+4. Define scope, constraints, non-goals, approval policy, and validation.
+5. Create tasks using the task contract from the parent skill.
+6. Add behavioral scenarios where outcomes can be observed.
+7. Describe required capabilities semantically and use `none` when no special capability is needed.
+8. Initialize one progress row per task with `TODO`.
+9. Self-review with the validation checklist and apply the approval policy.
 
 ## Quality Bar
 
-- Constraints are enforceable, not vague.
-- Every task has files and a verify step.
-- Out-of-scope items are explicit.
-- Another engineer can execute without guessing intent.
+- Another implementer can execute without guessing intent.
+- No task requires a named agent, skill, vendor, framework, or command that has not been discovered locally.
+- Tasks, progress rows, and validation are mutually consistent.
+- Risks and meaningful alternatives live in `design.md`; routine choices stay in the spec.
+- `spec.md` is the only task source of truth.
+
+## Blockers
+
+Mark planning `BLOCKED` only when a required decision or fact cannot be discovered and a reasonable assumption would create material risk. Record the missing input and its impact.

package/catalog/skills/spec-driven-development/agents/verify.md

@@ -2,31 +2,52 @@
 
 ## Purpose
 
-Validate that implementation matches the approved spec and passes quality checks.
+Validate implementation against the approved spec using reproducible evidence and a portable final review.
 
-## Inputs
+## Procedure
 
-- Spec path.
-- Implementation result from apply mode.
+1. Read the complete spec and relevant design decisions.
+2. Confirm every task has a terminal state and `DONE` tasks have evidence.
+3. Run or inspect each task verify step.
+4. Run feature-level validation discovered from the repository and listed in the spec.
+5. Evaluate every `MUST` and `MUST NOT` constraint independently.
+6. Identify manual checks that still require human confirmation.
+7. Perform the final review gate below.
+8. Report blockers, warnings, and evidence separately.
 
-## Procedure
+## Portable Final Review Gate
+
+Use an installed review capability when one is available and applicable. Otherwise perform this local review:
+
+- Correctness: implementation satisfies every scenario and constraint.
+- Regression risk: affected existing behavior has appropriate checks.
+- Scope: no unapproved behavior or dependency was introduced.
+- Maintainability: changes follow discovered project conventions.
+- Safety: security, privacy, accessibility, data, and destructive-operation risks were considered when relevant.
+- Evidence: results are reproducible and unsupported claims are absent.
+
+Any unresolved correctness, constraint, or safety blocker fails verification. Missing optional tooling does not fail verification when this fallback is completed.
+
+## Report Contract
+
+```markdown
+## Verification Report
 
-1. Read acceptance intent from `spec.md` and `design.md` (if present).
-2. Run task-level verification evidence checks.
-3. Run feature-level validation commands.
-4. Confirm constraints (`MUST`, `MUST NOT`) were respected.
-5. Run a final structured `review-rangers` pass over the full change set.
-6. Report pass/fail per area with concrete evidence.
+### Task Evidence
+| Task | Check | Result | Evidence |
 
-### Required Final Gate (`review-rangers`)
+### Constraints
+| Constraint | Result | Evidence |
 
-- Validate selected agent targets vs actual instruction files/symlinks written.
-- Validate stale managed target cleanup after re-install/reselection.
-- Validate backup and restore safety (including uninstall restore behavior).
-- Any unresolved `review-rangers` blocker keeps verification in failed state.
+### Final Review
+- Result: PASS | FAIL
+- Blockers: none | list
+- Warnings: none | list
+- Manual checks: none | list
+```
 
 ## Quality Bar
 
-- End-to-end validation is explicit.
-- Gaps are tied to exact tasks or constraints.
-- Report separates blockers from non-blocking warnings.
+- Results distinguish `PASS`, `FAIL`, and `NOT_RUN`.
+- Manual validation is never reported as automated evidence.
+- Archive readiness is an explicit conclusion, not an implication.

package/catalog/skills/spec-driven-development/assets/delta-spec-template.md

@@ -1,51 +1,86 @@
-# [Feature Name] - Delta Spec
-
-Use this template when changing behavior in an existing feature.
+# [Work Name] - Delta Spec
 
 ## Why
 
-[Why this behavior change is needed now.]
+[Reason for changing established behavior.]
 
-## What
+## Baseline
 
-[Concrete behavior change and expected outcome.]
+[Maintained requirement source or a concise description of current behavior.]
 
 ## ADDED Requirements
 
 ### Requirement: [Name]
 
-[MUST/SHOULD/MAY statement]
+[MUST, SHOULD, or MAY statement.]
 
 #### Scenario: [Name]
 
 - GIVEN [initial state]
 - WHEN [action]
-- THEN [expected outcome]
+- THEN [observable result]
 
 ## MODIFIED Requirements
 
 ### Requirement: [Name]
 
-[New requirement text]
+[Complete replacement requirement.]
 
-(Previously: [old requirement text])
+Previously: [Previous requirement or behavior.]
 
 ## REMOVED Requirements
 
 ### Requirement: [Name]
 
-(Reason: [why removed])
+Reason: [Why it is removed.]
+
+## Constraints
+
+### Must
+
+- [Enforceable requirement]
+
+### Must Not
+
+- [Disallowed behavior]
+
+### Out of Scope
+
+- [Boundary]
+
+## Approval Policy
+
+- Mode: [explicit checkpoint | self-review]
+- Trigger for reapproval: [change condition]
 
 ## Tasks
 
 ### T1: [Title]
 
-**What:** [Specific implementation]
+**What:** [Observable outcome]
+**Required Capabilities:** [Semantic capabilities, or `none`]
+**Files:** [Expected files, or `discover`]
+**Scenario:** [GIVEN / WHEN / THEN, when behavioral]
+**Verify:** [Project-discovered command or concrete manual check]
+**Done:** [One-sentence completion condition]
 
-**Files:** `path/to/file`, `path/to/test`
+## Progress
 
-**Verify:** [Command or manual check]
+| Task | Status | Evidence |
+| --- | --- | --- |
+| T1 | TODO | |
 
 ## Validation
 
-- [Checks that prove the delta behavior is correct]
+- [Checks that prove the behavior delta]
+- [Regression checks for retained behavior]
+
+## Reconciliation
+
+- Baseline update required: [yes | no]
+- Reconciliation result: [pending | complete | not applicable]
+
+## Change Log
+
+| Date | Change | Affected Tasks | Approval |
+| --- | --- | --- | --- |

package/catalog/skills/spec-driven-development/assets/design-template.md

@@ -1,31 +1,37 @@
-# Design: [Feature Name]
+# Design: [Work Name]
 
-Use with `spec.md` when implementation includes meaningful architectural decisions.
+Use this artifact only for decisions whose rationale or trade-offs will matter after implementation.
 
 ## Context
 
-[Current system state, constraints, and why a decision is needed now.]
+[Verified system state and reason a decision is needed.]
 
 ## Goals
 
-- [Primary outcome]
-- [Secondary outcome]
+- [Desired outcome]
 
 ## Non-Goals
 
-- [Explicitly excluded area]
-- [Another excluded area]
+- [Explicit exclusion]
 
-## Decisions
+## Decision
 
-### Decision: [Name]
+### [Decision Name]
 
-[What was chosen and why]
+- Choice: [Selected approach]
+- Rationale: [Why it fits the constraints]
+- Required capabilities: [Semantic capabilities, or `none`]
 
-### Alternatives Considered
+## Alternatives Considered
 
-- [Alternative option and why not chosen]
+| Alternative | Benefit | Cost | Reason Not Selected |
+| --- | --- | --- | --- |
 
-## Risks / Trade-offs
+## Risks and Mitigations
 
-- **[Risk]:** [Impact + mitigation or acceptance rationale]
+| Risk | Impact | Mitigation | Verification |
+| --- | --- | --- | --- |
+
+## Revisit Conditions
+
+- [Evidence or change that should reopen this decision]

package/catalog/skills/spec-driven-development/assets/spec-template.md

@@ -1,56 +1,77 @@
-# [Feature Name]
+# [Work Name]
 
 ## Why
 
-[1-2 sentences on the problem and why it matters now.]
+[Problem, value, and why it matters now.]
 
 ## What
 
-[Concrete, testable deliverable.]
+[Concrete and testable deliverable.]
 
 ## Constraints
 
 ### Must
 
-- [Required patterns, architecture, or conventions]
-- [Required dependency or existing system usage]
+- [Enforceable requirement]
+
+### Should
+
+- [Preferred outcome; deviations require a reason]
 
 ### Must Not
 
-- [Disallowed approaches]
-- [Disallowed dependencies or behavioral changes]
+- [Disallowed behavior or approach]
 
 ### Out of Scope
 
-- [Adjacent but excluded features]
+- [Explicit boundary]
 
 ## Current State
 
-- [Relevant existing files and behavior]
-- [Known dependencies and integration points]
+- [Verified files, behavior, dependencies, and conventions]
+
+## Approval Policy
+
+- Mode: [explicit checkpoint | self-review]
+- Trigger for reapproval: [scope, constraint, risk, or design change]
 
 ## Tasks
 
 ### T1: [Title]
 
-**What:** [Specific implementation change]
+**What:** [Observable outcome]
+
+**Required Capabilities:** [Semantic capabilities, or `none`]
 
-**Files:** `path/to/file`, `path/to/test`
+**Files:** [Expected files, or `discover`]
 
-**Verify:** [Command or manual check]
+**Scenario:**
 
----
+- GIVEN [initial state]
+- WHEN [action]
+- THEN [observable result]
 
-### T2: [Title]
+**Verify:** [Project-discovered command or concrete manual check]
 
-**What:** [Specific implementation change]
+**Done:** [One-sentence completion condition]
 
-**Files:** `path/to/file`
+## Progress
 
-**Verify:** [Command or manual check]
+| Task | Status | Evidence |
+| --- | --- | --- |
+| T1 | TODO | |
+
+Valid states: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
 
 ## Validation
 
 - [Feature-level automated check]
-- [Feature-level manual scenario]
-- [Additional release-specific verification]
+- [Feature-level manual scenario, if needed]
+- [Constraint or regression check]
+
+## Change Log
+
+Record requirement, scope, or design changes. Do not log routine progress.
+
+| Date | Change | Affected Tasks | Approval |
+| --- | --- | --- | --- |

package/catalog/skills/spec-driven-development/assets/validation-checklist.md

@@ -1,33 +1,40 @@
 # Spec Validation Checklist
 
-Use this checklist before implementation and again before archive.
+## Portability
+
+- [ ] The workflow is executable without a named external skill, agent, vendor, service, framework, VCS, package manager, or test runner.
+- [ ] Required capabilities are semantic and can use a local fallback.
+- [ ] Commands were discovered from the target project or are clearly marked as placeholders.
+- [ ] Protocol states use portable ASCII tokens.
 
 ## Spec Quality
 
-- [ ] Title is specific and unambiguous.
-- [ ] `Why` explains urgency and value.
-- [ ] `What` is concrete and testable.
-- [ ] Constraints are enforceable (`Must`, `Must Not`, `Out of Scope`).
-- [ ] `Current State` references real files or systems.
+- [ ] `Why` and `What` are concrete.
+- [ ] Constraints and out-of-scope boundaries are enforceable.
+- [ ] Current-state claims reference verified context.
+- [ ] Approval and reapproval policies are explicit.
+- [ ] Architecture decisions are captured only when their rationale matters.
 
 ## Task Quality
 
-- [ ] Tasks are small and scoped.
-- [ ] Each task has `What`, `Files`, and `Verify`.
-- [ ] Task verification can be completed quickly.
-- [ ] No task mixes unrelated concerns.
+- [ ] Each task has one observable outcome.
+- [ ] Each task declares capabilities, files, verify step, and definition of done.
+- [ ] Behavioral tasks include an acceptance scenario.
+- [ ] Dependencies and blockers are visible.
+- [ ] Tasks exist only in `spec.md`.
 
-## Implementation Readiness
+## Execution Evidence
 
-- [ ] Success criteria are explicit.
-- [ ] No critical ambiguity remains.
-- [ ] Architecture decisions are captured in `design.md` if needed.
+- [ ] Every `DONE` task has reproducible evidence.
+- [ ] Failed or unavailable checks are recorded honestly.
+- [ ] Scope changes updated the spec before implementation continued.
+- [ ] Superseded evidence is identified.
 
-## Pre-Archive Verification
+## Pre-Archive
 
-- [ ] All planned tasks are complete.
-- [ ] Feature-level validation passes.
-- [ ] Constraints were respected.
-- [ ] Final `review-rangers` gate completed with no unresolved blockers.
-- [ ] No unintended scope creep.
-- [ ] Work is moved from `.sdd/active/` to `.sdd/archive/`.
+- [ ] All tasks are `DONE` and no blocker remains.
+- [ ] Feature validation and constraint checks pass.
+- [ ] The portable final review gate passes.
+- [ ] Manual checks are complete or explicitly approved.
+- [ ] Delta reconciliation is complete when applicable.
+- [ ] Archive name uses `<YYYY-MM-DD>-<work-name>`.

package/catalog/skills/spec-driven-development/manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "spec-driven-development",
   "title": "Spec-Driven Development",
-  "description": "Plan, execute, and verify multi-step work through versioned specs with small, testable tasks.",
+  "description": "Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. Trigger: planning or executing feature work, bug fixes, and multi-phase implementation.",
   "portable": true,
   "tags": ["core", "workflow", "planning"],
   "detectors": ["always"],
@@ -10,10 +10,10 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-03",
+    "last-edit": "2026-06-20",
     "license": "Apache-2.0",
-    "version": "1.0.3",
-    "changelog": "Added OpenSpec complementary support routing guidance to spec-driven-development instructions; improves planning continuity and review clarity when local SDD needs reinforcement; affects spec-driven-development SKILL guidance and manifest metadata",
+    "version": "1.1.0",
+    "changelog": "Added a portable SDD lifecycle with capability-based routing, task evidence, change control, and archive invariants; prevents fixed tool dependencies and duplicated task state; affects planning, apply, verify, orchestrate, and spec templates",
     "auto-invoke": "Planning or executing feature work, bug fixes, and multi-phase implementation",
     "allowed-modes": [
       "plan",