@ancleto/spec 0.1.1 → 0.2.1

package/skills/openspec-sync-specs/SKILL.md

@@ -1,150 +1,150 @@
----
-name: openspec-sync-specs
-description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
-license: MIT
-compatibility: Requires openspec CLI.
-metadata:
-  author: ancleto
-  version: '1.0'
----
-
-Sync delta specs from a change to main specs.
-
-This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
-
-**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
-
-**Steps**
-
-1. **If no change name provided, prompt for selection**
-
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
-
-   Show changes that have delta specs (under `specs/` directory).
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Find delta specs**
-
-   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
-
-   Each delta spec file contains sections like:
-
-   - `## ADDED Requirements` - New requirements to add
-   - `## MODIFIED Requirements` - Changes to existing requirements
-   - `## REMOVED Requirements` - Requirements to remove
-   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
-
-   If no delta specs found, inform user and stop.
-
-3. **For each delta spec, apply changes to main specs**
-
-   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
-
-   a. **Read the delta spec** to understand the intended changes
-
-   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
-
-   c. **Apply changes intelligently**:
-
-   **ADDED Requirements:**
-
-   - If requirement doesn't exist in main spec → add it
-   - If requirement already exists → update it to match (treat as implicit MODIFIED)
-
-   **MODIFIED Requirements:**
-
-   - Find the requirement in main spec
-   - Apply the changes - this can be:
-     - Adding new scenarios (don't need to copy existing ones)
-     - Modifying existing scenarios
-     - Changing the requirement description
-   - Preserve scenarios/content not mentioned in the delta
-
-   **REMOVED Requirements:**
-
-   - Remove the entire requirement block from main spec
-
-   **RENAMED Requirements:**
-
-   - Find the FROM requirement, rename to TO
-
-   d. **Create new main spec** if capability doesn't exist yet:
-
-   - Create `openspec/specs/<capability>/spec.md`
-   - Add Purpose section (can be brief, mark as TBD)
-   - Add Requirements section with the ADDED requirements
-
-4. **Show summary**
-
-   After applying all changes, summarize:
-
-   - Which capabilities were updated
-   - What changes were made (requirements added/modified/removed/renamed)
-
-**Delta Spec Format Reference**
-
-```markdown
-## ADDED Requirements
-
-### Requirement: New Feature
-
-The system SHALL do something new.
-
-#### Scenario: Basic case
-
-- **WHEN** user does X
-- **THEN** system does Y
-
-## MODIFIED Requirements
-
-### Requirement: Existing Feature
-
-#### Scenario: New scenario to add
-
-- **WHEN** user does A
-- **THEN** system does B
-
-## REMOVED Requirements
-
-### Requirement: Deprecated Feature
-
-## RENAMED Requirements
-
-- FROM: `### Requirement: Old Name`
-- TO: `### Requirement: New Name`
-```
-
-**Key Principle: Intelligent Merging**
-
-Unlike programmatic merging, you can apply **partial updates**:
-
-- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
-- The delta represents _intent_, not a wholesale replacement
-- Use your judgment to merge changes sensibly
-
-**Output On Success**
-
-```
-## Specs Synced: <change-name>
-
-Updated main specs:
-
-**<capability-1>**:
-- Added requirement: "New Feature"
-- Modified requirement: "Existing Feature" (added 1 scenario)
-
-**<capability-2>**:
-- Created new spec file
-- Added requirement: "Another Feature"
-
-Main specs are now updated. The change remains active - archive when implementation is complete.
-```
-
-**Guardrails**
-
-- Read both delta and main specs before making changes
-- Preserve existing content not mentioned in delta
-- If something is unclear, ask for clarification
-- Show what you're changing as you go
+---
+name: openspec-sync-specs
+description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: ancleto
+  version: '1.0'
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Find delta specs**
+
+   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
+
+   Each delta spec file contains sections like:
+
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+3. **For each delta spec, apply changes to main specs**
+
+   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+   **ADDED Requirements:**
+
+   - If requirement doesn't exist in main spec → add it
+   - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+   **MODIFIED Requirements:**
+
+   - Find the requirement in main spec
+   - Apply the changes - this can be:
+     - Adding new scenarios (don't need to copy existing ones)
+     - Modifying existing scenarios
+     - Changing the requirement description
+   - Preserve scenarios/content not mentioned in the delta
+
+   **REMOVED Requirements:**
+
+   - Remove the entire requirement block from main spec
+
+   **RENAMED Requirements:**
+
+   - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+
+   - Create `openspec/specs/<capability>/spec.md`
+   - Add Purpose section (can be brief, mark as TBD)
+   - Add Requirements section with the ADDED requirements
+
+4. **Show summary**
+
+   After applying all changes, summarize:
+
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+
+The system SHALL do something new.
+
+#### Scenario: Basic case
+
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+
+#### Scenario: New scenario to add
+
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents _intent_, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
 - The operation should be idempotent - running twice should give same result

package/skills/triage-clarifier/SKILL.md

@@ -1,101 +1,101 @@
----
-name: triage-clarifier
-description: Clarification-needed triage helper. Use when the request sits between direct-implementation, direct-test-only, and spec-required, or when visible behavior impact is unclear.
----
-
-# Triage Clarifier
-
-## Goal
-
-Reduce ambiguity during triage without replacing the orchestrator or starting a spec workflow.
-
-## Use only when
-
-- the request is not clearly `direct-implementation`, `direct-test-only`, or `spec-required`
-- it is unclear whether the change affects visible behavior, acceptance criteria, or product code
-- a single high-value clarification can materially improve classification confidence
-
-## Do not use when
-
-- the request already fits one category clearly
-- the request is already clearly large enough for `spec-required`
-- the user explicitly asked to open the structured/spec path
-
-## Inputs to preserve
-
-- the user's original wording
-- any repo-specific context already gathered by the orchestrator
-- any existing constraints, references, or acceptance criteria already present in the request
-
-## Repository-context boundary
-
-Triage classifies the request; it does not reconstruct the repository.
-
-If repository context is needed to classify safely, do not sweep source files, broaden a
-search, or inspect the implementation yourself. Ask the orchestrator to delegate one focused
-question to `@technical-discovery`. That subagent reads the repository's technical-discovery
-documents and returns the relevant, cited context for triage.
-
-Never replace unavailable technical-discovery documents with a manual repository scan. Use the
-context already provided, ask the one permitted clarification question when it resolves the
-dominant ambiguity, or favor `spec-required` when material uncertainty remains.
-
-## Internal evaluation
-
-Before asking anything, evaluate these questions silently:
-
-1. Is the request strictly about tests, or is product code likely to change?
-2. Is the expected behavior already clear, or would implementation require assumptions?
-3. Could the change alter visible behavior, business rules, contracts, shared types, architecture, or integrations?
-4. Is the request small and local, or does it risk expanding once implementation starts?
-5. If the team guessed wrong and under-classified it, would that create rework or architecture risk?
-6. Is the change low-risk, or does its small size hide a behavior change or high-stakes logic (auth, payments, data integrity, security, shared contracts)? If small but high-risk, prefer `spec-required`.
-
-## Classification rules
-
-Classify without asking a question whenever possible:
-
-- choose `direct-test-only` when the request is clearly limited to tests for existing behavior
-- choose `direct-implementation` when the change is small, local, and the expected result is already clear
-- choose `spec-required` when the request affects visible behavior, business rules, shared contracts, architecture, or scope is already meaningfully broad
-
-## Single-question policy
-
-Ask at most one question.
-
-That question must:
-
-- target the highest-value ambiguity only
-- be short and concrete
-- help separate exactly one boundary, such as:
-  - test-only vs product change
-  - local bugfix vs behavior change
-  - small direct change vs structured/spec change
-
-Do not ask multi-part questions.
-Do not ask for implementation details unless they are required to classify safely.
-Do not start an interview.
-
-## Fallback policy
-
-If one clarification still leaves meaningful ambiguity or risk, favor `spec-required`.
-
-When in doubt, prefer the safer classification over an under-scoped direct path.
-
-## Expected outcome
-
-After applying this skill, the orchestrator should do exactly one of these:
-
-1. classify directly as `direct-test-only`
-2. classify directly as `direct-implementation`
-3. classify directly as `spec-required`
-4. ask one concise clarification question
-
-If option 4 happened and the answer still does not remove the main ambiguity, classify as `spec-required`.
-
-## What not to do
-
-- do not create specs, design, tasks, or proposals
-- do not trigger opsx or any workflow handoff
-- do not ask more than one clarification question
+---
+name: triage-clarifier
+description: Clarification-needed triage helper. Use when the request sits between direct-implementation, direct-test-only, and spec-required, or when visible behavior impact is unclear.
+---
+
+# Triage Clarifier
+
+## Goal
+
+Reduce ambiguity during triage without replacing the orchestrator or starting a spec workflow.
+
+## Use only when
+
+- the request is not clearly `direct-implementation`, `direct-test-only`, or `spec-required`
+- it is unclear whether the change affects visible behavior, acceptance criteria, or product code
+- a single high-value clarification can materially improve classification confidence
+
+## Do not use when
+
+- the request already fits one category clearly
+- the request is already clearly large enough for `spec-required`
+- the user explicitly asked to open the structured/spec path
+
+## Inputs to preserve
+
+- the user's original wording
+- any repo-specific context already gathered by the orchestrator
+- any existing constraints, references, or acceptance criteria already present in the request
+
+## Repository-context boundary
+
+Triage classifies the request; it does not reconstruct the repository.
+
+If repository context is needed to classify safely, do not sweep source files, broaden a
+search, or inspect the implementation yourself. Ask the orchestrator to delegate one focused
+question to `@technical-discovery`. That subagent reads the repository's technical-discovery
+documents and returns the relevant, cited context for triage.
+
+Never replace unavailable technical-discovery documents with a manual repository scan. Use the
+context already provided, ask the one permitted clarification question when it resolves the
+dominant ambiguity, or favor `spec-required` when material uncertainty remains.
+
+## Internal evaluation
+
+Before asking anything, evaluate these questions silently:
+
+1. Is the request strictly about tests, or is product code likely to change?
+2. Is the expected behavior already clear, or would implementation require assumptions?
+3. Could the change alter visible behavior, business rules, contracts, shared types, architecture, or integrations?
+4. Is the request small and local, or does it risk expanding once implementation starts?
+5. If the team guessed wrong and under-classified it, would that create rework or architecture risk?
+6. Is the change low-risk, or does its small size hide a behavior change or high-stakes logic (auth, payments, data integrity, security, shared contracts)? If small but high-risk, prefer `spec-required`.
+
+## Classification rules
+
+Classify without asking a question whenever possible:
+
+- choose `direct-test-only` when the request is clearly limited to tests for existing behavior
+- choose `direct-implementation` when the change is small, local, and the expected result is already clear
+- choose `spec-required` when the request affects visible behavior, business rules, shared contracts, architecture, or scope is already meaningfully broad
+
+## Single-question policy
+
+Ask at most one question.
+
+That question must:
+
+- target the highest-value ambiguity only
+- be short and concrete
+- help separate exactly one boundary, such as:
+  - test-only vs product change
+  - local bugfix vs behavior change
+  - small direct change vs structured/spec change
+
+Do not ask multi-part questions.
+Do not ask for implementation details unless they are required to classify safely.
+Do not start an interview.
+
+## Fallback policy
+
+If one clarification still leaves meaningful ambiguity or risk, favor `spec-required`.
+
+When in doubt, prefer the safer classification over an under-scoped direct path.
+
+## Expected outcome
+
+After applying this skill, the orchestrator should do exactly one of these:
+
+1. classify directly as `direct-test-only`
+2. classify directly as `direct-implementation`
+3. classify directly as `spec-required`
+4. ask one concise clarification question
+
+If option 4 happened and the answer still does not remove the main ambiguity, classify as `spec-required`.
+
+## What not to do
+
+- do not create specs, design, tasks, or proposals
+- do not trigger opsx or any workflow handoff
+- do not ask more than one clarification question
 - do not replace the orchestrator's final responsibility for classification