@ancleto/spec 0.6.5 → 0.6.7

package/commands/cleto-bulk-archive.md

@@ -2,254 +2,8 @@
 description: Archive multiple completed changes at once
 ---
 
-Archive multiple completed changes in a single operation.
-
-This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
+Invoke the `ancleto-bulk-archive` skill with the Skill tool and follow it exactly; do not improvise steps.
 
 **Input**: None required (prompts for selection)
 
-**Steps**
-
-1. **Get active changes**
-
-   Run `aspec list --json` to get all active changes.
-
-   If no active changes exist, inform user and stop.
-
-2. **Prompt for change selection**
-
-   Use **AskUserQuestion tool** with multi-select to let user choose changes:
-
-   - Show each change with its schema
-   - Include an option for "All changes"
-   - Allow any number of selections (1+ works, 2+ is the typical use case)
-
-   **IMPORTANT**: Do NOT auto-select. Always let the user choose.
-
-3. **Batch validation - gather status for all selected changes**
-
-   For each selected change, collect:
-
-   a. **Artifact status** - Run `aspec status --change "<name>" --json`
-
-   - Parse `schemaName` and `artifacts` list
-   - Note which artifacts are `done` vs other states
-
-   b. **Task completion** - Read `aspec/changes/<name>/tasks.md`
-
-   - Count `- [ ]` (incomplete) vs `- [x]` (complete)
-   - If no tasks file exists, note as "No tasks"
-
-   c. **Delta specs** - Check `aspec/changes/<name>/specs/` directory
-
-   - List which capability specs exist
-   - For each, extract requirement names (lines matching `### Requirement: <name>`)
-
-4. **Detect spec conflicts**
-
-   Build a map of `capability -> [changes that touch it]`:
-
-   ```
-   auth -> [change-a, change-b]  <- CONFLICT (2+ changes)
-   api  -> [change-c]            <- OK (only 1 change)
-   ```
-
-   A conflict exists when 2+ selected changes have delta specs for the same capability.
-
-5. **Resolve conflicts agentically**
-
-   **For each conflict**, investigate the codebase:
-
-   a. **Read the delta specs** from each conflicting change to understand what each claims to add/modify
-
-   b. **Search the codebase** for implementation evidence:
-
-   - Look for code implementing requirements from each delta spec
-   - Check for related files, functions, or tests
-
-   c. **Determine resolution**:
-
-   - If only one change is actually implemented -> sync that one's specs
-   - If both implemented -> apply in chronological order (older first, newer overwrites)
-   - If neither implemented -> skip spec sync, warn user
-
-   d. **Record resolution** for each conflict:
-
-   - Which change's specs to apply
-   - In what order (if both)
-   - Rationale (what was found in codebase)
-
-6. **Show consolidated status table**
-
-   Display a table summarizing all changes:
-
-   ```
-   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
-   |---------------------|-----------|-------|---------|-----------|--------|
-   | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
-   | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
-   | add-oauth           | Done      | 4/4   | 1 delta | auth (!)  | Ready* |
-   | add-verify-skill    | 1 left    | 2/5   | None    | None      | Warn   |
-   ```
-
-   For conflicts, show the resolution:
-
-   ```
-   * Conflict resolution:
-     - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)
-   ```
-
-   For incomplete changes, show warnings:
-
-   ```
-   Warnings:
-   - add-verify-skill: 1 incomplete artifact, 3 incomplete tasks
-   ```
-
-7. **Confirm batch operation**
-
-   Use **AskUserQuestion tool** with a single confirmation:
-
-   - "Archive N changes?" with options based on status
-   - Options might include:
-     - "Archive all N changes"
-     - "Archive only N ready changes (skip incomplete)"
-     - "Cancel"
-
-   If there are incomplete changes, make clear they'll be archived with warnings.
-
-8. **Execute archive for each confirmed change**
-
-   Process changes in the determined order (respecting conflict resolution):
-
-   a. **Sync specs** if delta specs exist:
-
-   - Use the ancleto-sync-specs approach (agent-driven intelligent merge)
-   - For conflicts, apply in resolved order
-   - Track if sync was done
-
-   b. **Perform the archive**:
-
-   ```bash
-   mkdir -p aspec/changes/archive
-   mv aspec/changes/<name> aspec/changes/archive/YYYY-MM-DD-<name>
-   ```
-
-   c. **Track outcome** for each change:
-
-   - Success: archived successfully
-   - Failed: error during archive (record error)
-   - Skipped: user chose not to archive (if applicable)
-
-9. **Display summary**
-
-   Show final results:
-
-   ```
-   ## Bulk Archive Complete
-
-   Archived 3 changes:
-   - schema-management-cli -> archive/2026-01-19-schema-management-cli/
-   - project-config -> archive/2026-01-19-project-config/
-   - add-oauth -> archive/2026-01-19-add-oauth/
-
-   Skipped 1 change:
-   - add-verify-skill (user chose not to archive incomplete)
-
-   Spec sync summary:
-   - 4 delta specs synced to main specs
-   - 1 conflict resolved (auth: applied both in chronological order)
-   ```
-
-   If any failures:
-
-   ```
-   Failed 1 change:
-   - some-change: Archive directory already exists
-   ```
-
-**Conflict Resolution Examples**
-
-Example 1: Only one implemented
-
-```
-Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]
-
-Checking add-oauth:
-- Delta adds "OAuth Provider Integration" requirement
-- Searching codebase... found src/auth/oauth.ts implementing OAuth flow
-
-Checking add-jwt:
-- Delta adds "JWT Token Handling" requirement
-- Searching codebase... no JWT implementation found
-
-Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.
-```
-
-Example 2: Both implemented
-
-```
-Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]
-
-Checking add-rest-api (created 2026-01-10):
-- Delta adds "REST Endpoints" requirement
-- Searching codebase... found src/api/rest.ts
-
-Checking add-graphql (created 2026-01-15):
-- Delta adds "GraphQL Schema" requirement
-- Searching codebase... found src/api/graphql.ts
-
-Resolution: Both implemented. Will apply add-rest-api specs first,
-then add-graphql specs (chronological order, newer takes precedence).
-```
-
-**Output On Success**
-
-```
-## Bulk Archive Complete
-
-Archived N changes:
-- <change-1> -> archive/YYYY-MM-DD-<change-1>/
-- <change-2> -> archive/YYYY-MM-DD-<change-2>/
-
-Spec sync summary:
-- N delta specs synced to main specs
-- No conflicts (or: M conflicts resolved)
-```
-
-**Output On Partial Success**
-
-```
-## Bulk Archive Complete (partial)
-
-Archived N changes:
-- <change-1> -> archive/YYYY-MM-DD-<change-1>/
-
-Skipped M changes:
-- <change-2> (user chose not to archive incomplete)
-
-Failed K changes:
-- <change-3>: Archive directory already exists
-```
-
-**Output When No Changes**
-
-```
-## No Changes to Archive
-
-No active changes found. Create a new change to get started.
-```
-
-**Guardrails**
-
-- Allow any number of changes (1+ is fine, 2+ is the typical use case)
-- Always prompt for selection, never auto-select
-- Detect spec conflicts early and resolve by checking codebase
-- When both changes are implemented, apply specs in chronological order
-- Skip spec sync only when implementation is missing (warn user)
-- Show clear per-change status before confirming
-- Use single confirmation for entire batch
-- Track and report all outcomes (success/skip/fail)
-- Preserve .aspec.yaml when moving to archive
-- Archive directory target uses current date: YYYY-MM-DD-<name>
-- If archive target exists, fail that change but continue with others
+Work Item grounding (when the request references a Work Item) is owned by `@context-resolver`.

package/commands/cleto-continue.md

@@ -2,132 +2,8 @@
 description: Continue working on a change - create the next artifact (Experimental)
 ---
 
-Continue working on a change by creating the next artifact.
+Invoke the `ancleto-continue` skill with the Skill tool and follow it exactly; do not improvise steps.
 
 **Input**: Optionally specify a change name after `/cleto-continue` (e.g., `/cleto-continue add-auth`). 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 `aspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
-
-   Present the top 3-4 most recently modified changes as options, showing:
-
-   - Change name
-   - Schema (from `schema` field if present, otherwise "spec-driven")
-   - Status (e.g., "0/5 tasks", "complete", "no tasks")
-   - How recently it was modified (from `lastModified` field)
-
-   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to continue.
-
-   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
-
-2. **Check current status**
-
-   ```bash
-   aspec status --change "<name>" --json
-   ```
-
-   Parse the JSON to understand current state. The response includes:
-
-   - `schemaName`: The workflow schema being used (e.g., "spec-driven")
-   - `artifacts`: Array of artifacts with their status ("done", "ready", "blocked")
-   - `isComplete`: Boolean indicating if all artifacts are complete
-
-3. **Load scaffold context files** (if not already loaded this session)
-
-   If `context.md` for this change was already read earlier in the current session, skip this step — it is already in context.
-
-   Otherwise, read it as background context — it is NOT an artifact and must NOT be included in output files, but its contents inform what you write:
-
-   - `aspec/changes/<name>/context.md` — Work Item context (title, description, acceptance criteria)
-
-   If either file is missing, skip silently.
-
-4. **Act based on status**:
-
-   ***
-
-   **If all artifacts are complete (`isComplete: true`)**:
-
-   - Congratulate the user
-   - Show final status including the schema used
-   - Suggest: "All artifacts created! You can now implement this change with `/cleto-apply` or archive it with `/cleto-archive`."
-   - STOP
-
-   ***
-
-   **If artifacts are ready to create** (status shows artifacts with `status: "ready"`):
-
-   - Pick the FIRST artifact with `status: "ready"` from the status output
-   - Get its instructions:
-     ```bash
-     aspec instructions <artifact-id> --change "<name>" --json
-     ```
-   - Parse the JSON. The key fields are:
-     - `context`: Project background (constraints for you - do NOT include in output)
-     - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
-     - `template`: The structure to use for your output file
-     - `instruction`: Schema-specific guidance
-     - `outputPath`: Where to write the artifact
-     - `dependencies`: Completed artifacts to read for context
-   - **Create the artifact file**:
-     - Read any completed dependency files for context
-     - If creating the **first artifact** (proposal):
-- If `context.md` was loaded with WI data (step 3): use the WI title/description as the problem statement, acceptance criteria as the requirements basis, and include a `## Related Work Item` section: `**#{id}** — {System.Title} ({WorkItemType}) · Project: {System.TeamProject}`
-      - Use `template` as the structure - fill in its sections
-     - Apply `context` and `rules` as constraints when writing - but do NOT copy them into the file
-     - Write to the output path specified in instructions
-   - Show what was created and what's now unlocked
-   - STOP after creating ONE artifact
-
-   ***
-
-   **If no artifacts are ready (all blocked)**:
-
-   - This shouldn't happen with a valid schema
-   - Show status and suggest checking for issues
-
-5. **After creating an artifact, show progress**
-   ```bash
-   aspec status --change "<name>"
-   ```
-
-**Output**
-
-After each invocation, show:
-
-- Which artifact was created
-- Schema workflow being used
-- Current progress (N/M complete)
-- What artifacts are now unlocked
-- Prompt: "Run `/cleto-continue` to create the next artifact"
-
-**Artifact Creation Guidelines**
-
-The artifact types and their purpose depend on the schema. Use the `instruction` field from the instructions output to understand what to create.
-
-Common artifact patterns:
-
-**spec-driven schema** (proposal → specs → design → tasks):
-
-- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
-  - The Capabilities section is critical - each capability listed will need a spec file.
-- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
-- **design.md**: Document technical decisions, architecture, and implementation approach.
-- **tasks.md**: Break down implementation into checkboxed tasks.
-
-For other schemas, follow the `instruction` field from the CLI output.
-
-**Guardrails**
-
-- Create ONE artifact per invocation
-- Always read dependency artifacts before creating a new one
-- Never skip artifacts or create out of order
-- If context is unclear, ask the user before creating
-- Verify the artifact file exists after writing before marking progress
-- Use the schema's artifact sequence, don't assume specific artifact names
-- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
-  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
-  - These guide what you write, but should never appear in the output
+Work Item grounding (when the request references a Work Item) is owned by `@context-resolver`.

package/commands/cleto-explore.md

@@ -2,180 +2,8 @@
 description: Enter explore mode - think through ideas, investigate problems, clarify requirements
 ---
 
-Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
-
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create aspec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
-
-**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+Invoke the `ancleto-explore` skill with the Skill tool and follow it exactly; do not improvise steps.
 
 **Input**: The argument after `/cleto-explore` is whatever the user wants to think about. Could be:
 
-- A vague idea: "real-time collaboration"
-- A specific problem: "the auth system is getting unwieldy"
-- A change name: "add-dark-mode" (to explore in context of that change)
-- A comparison: "postgres vs sqlite for this"
-- Nothing (just enter explore mode)
-
----
-
-## The Stance
-
-- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
-- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
-- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
-- **Adaptive** - Follow interesting threads, pivot when new information emerges
-- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
-- **Grounded** - Explore the actual codebase when relevant, don't just theorize
-
----
-
-## What You Might Do
-
-Depending on what the user brings, you might:
-
-**Explore the problem space**
-
-- Ask clarifying questions that emerge from what they said
-- Challenge assumptions
-- Reframe the problem
-- Find analogies
-
-**Investigate the codebase**
-
-- Map existing architecture relevant to the discussion
-- Find integration points
-- Identify patterns already in use
-- Surface hidden complexity
-
-**Compare options**
-
-- Brainstorm multiple approaches
-- Build comparison tables
-- Sketch tradeoffs
-- Recommend a path (if asked)
-
-**Visualize**
-
-```
-┌─────────────────────────────────────────┐
-│     Use ASCII diagrams liberally        │
-├─────────────────────────────────────────┤
-│                                         │
-│   ┌────────┐         ┌────────┐        │
-│   │ State  │────────▶│ State  │        │
-│   │   A    │         │   B    │        │
-│   └────────┘         └────────┘        │
-│                                         │
-│   System diagrams, state machines,      │
-│   data flows, architecture sketches,    │
-│   dependency graphs, comparison tables  │
-│                                         │
-└─────────────────────────────────────────┘
-```
-
-**Surface risks and unknowns**
-
-- Identify what could go wrong
-- Find gaps in understanding
-- Suggest spikes or investigations
-
----
-
-## aspec Awareness
-
-You have full context of the aspec system. Use it naturally, don't force it.
-
-### Check for context
-
-At the start, quickly check what exists:
-
-```bash
-aspec list --json
-```
-
-This tells you:
-
-- If there are active changes
-- Their names, schemas, and status
-- What the user might be working on
-
-If the user mentioned a specific change name, read its artifacts for context.
-
-### When no change exists
-
-Think freely. When insights crystallize, you might offer:
-
-- "This feels solid enough to start a change. Want me to create a proposal?"
-- Or keep exploring - no pressure to formalize
-
-### When a change exists
-
-If the user mentions a change or you detect one is relevant:
-
-1. **Read existing artifacts for context**
-
-   - `aspec/changes/<name>/proposal.md`
-   - `aspec/changes/<name>/design.md`
-   - `aspec/changes/<name>/tasks.md`
-   - etc.
-
-2. **Reference them naturally in conversation**
-
-   - "Your design mentions using Redis, but we just realized SQLite fits better..."
-   - "The proposal scopes this to premium users, but we're now thinking everyone..."
-
-3. **Offer to capture when decisions are made**
-
-   | Insight Type               | Where to Capture             |
-   | -------------------------- | ---------------------------- |
-   | New requirement discovered | `specs/<capability>/spec.md` |
-   | Requirement changed        | `specs/<capability>/spec.md` |
-   | Design decision made       | `design.md`                  |
-   | Scope changed              | `proposal.md`                |
-   | New work identified        | `tasks.md`                   |
-   | Assumption invalidated     | Relevant artifact            |
-
-   Example offers:
-
-   - "That's a design decision. Capture it in design.md?"
-   - "This is a new requirement. Add it to specs?"
-   - "This changes scope. Update the proposal?"
-
-4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
-
----
-
-## What You Don't Have To Do
-
-- Follow a script
-- Ask the same questions every time
-- Produce a specific artifact
-- Reach a conclusion
-- Stay on topic if a tangent is valuable
-- Be brief (this is thinking time)
-
----
-
-## Ending Discovery
-
-There's no required ending. Discovery might:
-
-- **Flow into a proposal**: "Ready to start? I can create a change proposal."
-- **Result in artifact updates**: "Updated design.md with these decisions"
-- **Just provide clarity**: User has what they need, moves on
-- **Continue later**: "We can pick this up anytime"
-
-When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
-
----
-
-## Guardrails
-
-- **Don't implement** - Never write code or implement features. Creating aspec artifacts is fine, writing application code is not.
-- **Don't fake understanding** - If something is unclear, dig deeper
-- **Don't rush** - Discovery is thinking time, not task time
-- **Don't force structure** - Let patterns emerge naturally
-- **Don't auto-capture** - Offer to save insights, don't just do it
-- **Do visualize** - A good diagram is worth many paragraphs
-- **Do explore the codebase** - Ground discussions in reality
-- **Do question assumptions** - Including the user's and your own
+Work Item grounding (when the request references a Work Item) is owned by `@context-resolver`.