@ancleto/spec 0.6.5 → 0.6.6

package/commands/cleto-onboard.md

@@ -2,554 +2,6 @@
 description: Guided onboarding - walk through a complete aspec workflow cycle with narration
 ---
 
-Guide the user through their first complete aspec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
+Invoke the `ancleto-onboard` skill with the Skill tool and follow it exactly; do not improvise steps.
 
----
-
-## Preflight
-
-No external binaries are required: the change cycle runs on the aspec skills bundled
-with your agent (`/cleto-*`). Proceed directly.
-
----
-
-## Phase 1: Welcome
-
-Display:
-
-```
-## Welcome to aspec!
-
-I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.
-
-**What we'll do:**
-1. Pick a small, real task in your codebase
-2. Explore the problem briefly
-3. Create a change (the container for our work)
-4. Build the artifacts: proposal → specs → design → tasks
-5. Implement the tasks
-6. Archive the completed change
-
-**Time:** ~15-20 minutes
-
-Let's start by finding something to work on.
-```
-
----
-
-## Phase 2: Task Selection
-
-### Codebase Analysis
-
-Scan the codebase for small improvement opportunities. Look for:
-
-1. **TODO/FIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files
-2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch
-3. **Functions without tests** - Cross-reference `src/` with test directories
-4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)
-5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code
-6. **Missing validation** - User input handlers without validation
-
-Also check recent git activity:
-
-```bash
-# Unix/macOS
-git log --oneline -10 2>/dev/null || echo "No git history"
-# Windows (PowerShell)
-# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" }
-```
-
-### Present Suggestions
-
-From your analysis, present 3-4 specific suggestions:
-
-```
-## Task Suggestions
-
-Based on scanning your codebase, here are some good starter tasks:
-
-**1. [Most promising task]**
-   Location: `src/path/to/file.ts:42`
-   Scope: ~1-2 files, ~20-30 lines
-   Why it's good: [brief reason]
-
-**2. [Second task]**
-   Location: `src/another/file.ts`
-   Scope: ~1 file, ~15 lines
-   Why it's good: [brief reason]
-
-**3. [Third task]**
-   Location: [location]
-   Scope: [estimate]
-   Why it's good: [brief reason]
-
-**4. Something else?**
-   Tell me what you'd like to work on.
-
-Which task interests you? (Pick a number or describe your own)
-```
-
-**If nothing found:** Fall back to asking what the user wants to build:
-
-> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?
-
-### Scope Guardrail
-
-If the user picks or describes something too large (major feature, multi-day work):
-
-```
-That's a valuable task, but it's probably larger than ideal for your first aspec run-through.
-
-For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.
-
-**Options:**
-1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?
-2. **Pick something else** - One of the other suggestions, or a different small task?
-3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.
-
-What would you prefer?
-```
-
-Let the user override if they insist—this is a soft guardrail.
-
----
-
-## Phase 3: Explore Demo
-
-Once a task is selected, briefly demonstrate explore mode:
-
-```
-Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.
-```
-
-Spend 1-2 minutes investigating the relevant code:
-
-- Read the file(s) involved
-- Draw a quick ASCII diagram if it helps
-- Note any considerations
-
-```
-## Quick Exploration
-
-[Your brief analysis—what you found, any considerations]
-
-┌─────────────────────────────────────────┐
-│   [Optional: ASCII diagram if helpful]  │
-└─────────────────────────────────────────┘
-
-Explore mode (`/cleto-explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.
-
-Now let's create a change to hold our work.
-```
-
-**PAUSE** - Wait for user acknowledgment before proceeding.
-
----
-
-## Phase 4: Create the Change
-
-**EXPLAIN:**
-
-```
-## Creating a Change
-
-A "change" in aspec is a container for all the thinking and planning around a piece of work. It lives in `aspec/changes/<name>/` and holds your artifacts—proposal, specs, design, tasks.
-
-Let me create one for our task.
-```
-
-**DO:** Create the change directory with a derived kebab-case name:
-
-```bash
-mkdir -p aspec/changes/<derived-name>
-```
-
-**SHOW:**
-
-```
-Created: `aspec/changes/<name>/`
-
-The folder structure:
-```
-
-aspec/changes/<name>/
-├── proposal.md ← Why we're doing this (empty, we'll fill it)
-├── design.md ← How we'll build it (empty)
-├── specs/ ← Detailed requirements (empty)
-└── tasks.md ← Implementation checklist (empty)
-
-```
-
-Now let's fill in the first artifact—the proposal.
-```
-
----
-
-## Phase 5: Proposal
-
-**EXPLAIN:**
-
-```
-## The Proposal
-
-The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.
-
-I'll draft one based on our task.
-```
-
-**DO:** Draft the proposal content (don't save yet):
-
-```
-Here's a draft proposal:
-
----
-
-## Why
-
-[1-2 sentences explaining the problem/opportunity]
-
-## What Changes
-
-[Bullet points of what will be different]
-
-## Capabilities
-
-### New Capabilities
-- `<capability-name>`: [brief description]
-
-### Modified Capabilities
-<!-- If modifying existing behavior -->
-
-## Impact
-
-- `src/path/to/file.ts`: [what changes]
-- [other files if applicable]
-
----
-
-Does this capture the intent? I can adjust before we save it.
-```
-
-**PAUSE** - Wait for user approval/feedback.
-
-After approval, save the proposal:
-
-```bash
-aspec instructions proposal --change "<name>" --json
-```
-
-Then write the content to `aspec/changes/<name>/proposal.md`.
-
-```
-Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
-
-Next up: specs.
-```
-
----
-
-## Phase 6: Specs
-
-**EXPLAIN:**
-
-```
-## Specs
-
-Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.
-
-For a small task like this, we might only need one spec file.
-```
-
-**DO:** Create the spec file:
-
-```bash
-# Unix/macOS
-mkdir -p aspec/changes/<name>/specs/<capability-name>
-# Windows (PowerShell)
-# New-Item -ItemType Directory -Force -Path "aspec/changes/<name>/specs/<capability-name>"
-```
-
-Draft the spec content:
-
-```
-Here's the spec:
-
----
-
-## ADDED Requirements
-
-### Requirement: <Name>
-
-<Description of what the system should do>
-
-#### Scenario: <Scenario name>
-
-- **WHEN** <trigger condition>
-- **THEN** <expected outcome>
-- **AND** <additional outcome if needed>
-
----
-
-This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.
-```
-
-Save to `aspec/changes/<name>/specs/<capability>/spec.md`.
-
----
-
-## Phase 7: Design
-
-**EXPLAIN:**
-
-```
-## Design
-
-The design captures **how** we'll build it—technical decisions, tradeoffs, approach.
-
-For small changes, this might be brief. That's fine—not every change needs deep design discussion.
-```
-
-**DO:** Draft design.md:
-
-```
-Here's the design:
-
----
-
-## Context
-
-[Brief context about the current state]
-
-## Goals / Non-Goals
-
-**Goals:**
-- [What we're trying to achieve]
-
-**Non-Goals:**
-- [What's explicitly out of scope]
-
-## Decisions
-
-### Decision 1: [Key decision]
-
-[Explanation of approach and rationale]
-
----
-
-For a small task, this captures the key decisions without over-engineering.
-```
-
-Save to `aspec/changes/<name>/design.md`.
-
----
-
-## Phase 8: Tasks
-
-**EXPLAIN:**
-
-```
-## Tasks
-
-Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.
-
-These should be small, clear, and in logical order.
-```
-
-**DO:** Generate tasks based on specs and design:
-
-```
-Here are the implementation tasks:
-
----
-
-## 1. [Category or file]
-
-- [ ] 1.1 [Specific task]
-- [ ] 1.2 [Specific task]
-
-## 2. Verify
-
-- [ ] 2.1 [Verification step]
-
----
-
-Each checkbox becomes a unit of work in the apply phase. Ready to implement?
-```
-
-**PAUSE** - Wait for user to confirm they're ready to implement.
-
-Save to `aspec/changes/<name>/tasks.md`.
-
----
-
-## Phase 9: Apply (Implementation)
-
-**EXPLAIN:**
-
-```
-## Implementation
-
-Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach.
-```
-
-**DO:** For each task:
-
-1. Announce: "Working on task N: [description]"
-2. Implement the change in the codebase
-3. Reference specs/design naturally: "The spec says X, so I'm doing Y"
-4. Mark complete in tasks.md: `- [ ]` → `- [x]`
-5. Brief status: "✓ Task N complete"
-
-Keep narration light—don't over-explain every line of code.
-
-After all tasks:
-
-```
-## Implementation Complete
-
-All tasks done:
-- [x] Task 1
-- [x] Task 2
-- [x] ...
-
-The change is implemented! One more step—let's archive it.
-```
-
----
-
-## Phase 10: Archive
-
-**EXPLAIN:**
-
-```
-## Archiving
-
-When a change is complete, we archive it. This moves it from `aspec/changes/` to `aspec/changes/archive/YYYY-MM-DD-<name>/`.
-
-Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.
-```
-
-**DO:**
-
-```bash
-aspec archive "<name>"
-```
-
-**SHOW:**
-
-```
-Archived to: `aspec/changes/archive/YYYY-MM-DD-<name>/`
-
-The change is now part of your project's history. The code is in your codebase, the decision record is preserved.
-```
-
----
-
-## Phase 11: Recap & Next Steps
-
-```
-## Congratulations!
-
-You just completed a full aspec cycle:
-
-1. **Explore** - Thought through the problem
-2. **New** - Created a change container
-3. **Proposal** - Captured WHY
-4. **Specs** - Defined WHAT in detail
-5. **Design** - Decided HOW
-6. **Tasks** - Broke it into steps
-7. **Apply** - Implemented the work
-8. **Archive** - Preserved the record
-
-This same rhythm works for any size change—a small fix or a major feature.
-
----
-
-## Command Reference
-
-**Core workflow:**
-
-| Command | What it does |
-|---------|--------------|
-| `/cleto-propose` | Create a change and generate all artifacts |
-| `/cleto-explore` | Think through problems before/during work |
-| `/cleto-apply` | Implement tasks from a change |
-| `/cleto-archive` | Archive a completed change |
-
-**Additional commands:**
-
-| Command | What it does |
-|---------|--------------|
-| `/cleto-new` | Start a new change, step through artifacts one at a time |
-| `/cleto-continue` | Continue working on an existing change |
-| `/cleto-ff` | Fast-forward: create all artifacts at once |
-| `/cleto-verify` | Verify implementation matches artifacts |
-
----
-
-## What's Next?
-
-Try `/cleto-propose` on something you actually want to build. You've got the rhythm now!
-```
-
----
-
-## Graceful Exit Handling
-
-### User wants to stop mid-way
-
-If the user says they need to stop, want to pause, or seem disengaged:
-
-```
-No problem! Your change is saved at `aspec/changes/<name>/`.
-
-To pick up where we left off later:
-- `/cleto-continue <name>` - Resume artifact creation
-- `/cleto-apply <name>` - Jump to implementation (if tasks exist)
-
-The work won't be lost. Come back whenever you're ready.
-```
-
-Exit gracefully without pressure.
-
-### User just wants command reference
-
-If the user says they just want to see the commands or skip the tutorial:
-
-```
-## aspec Quick Reference
-
-**Core workflow:**
-
-| Command | What it does |
-|---------|--------------|
-| `/cleto-propose <name>` | Create a change and generate all artifacts |
-| `/cleto-explore` | Think through problems (no code changes) |
-| `/cleto-apply <name>` | Implement tasks |
-| `/cleto-archive <name>` | Archive when done |
-
-**Additional commands:**
-
-| Command | What it does |
-|---------|--------------|
-| `/cleto-new <name>` | Start a new change, step by step |
-| `/cleto-continue <name>` | Continue an existing change |
-| `/cleto-ff <name>` | Fast-forward: all artifacts at once |
-| `/cleto-verify <name>` | Verify implementation |
-
-Try `/cleto-propose` to start your first change.
-```
-
-Exit gracefully.
-
----
-
-## Guardrails
-
-- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)
-- **Keep narration light** during implementation—teach without lecturing
-- **Don't skip phases** even if the change is small—the goal is teaching the workflow
-- **Pause for acknowledgment** at marked points, but don't over-pause
-- **Handle exits gracefully**—never pressure the user to continue
-- **Use real codebase tasks**—don't simulate or use fake examples
-- **Adjust scope gently**—guide toward smaller tasks but respect user choice
+Work Item grounding (when the request references a Work Item) is owned by `@context-resolver`.

package/commands/cleto-propose.md

@@ -2,136 +2,8 @@
 description: Propose a new change - create it and generate all artifacts in one step
 ---
 
-Propose a new change - create the change and generate all artifacts in one step.
-
-I'll create a change with artifacts:
-
-- proposal.md (what & why)
-- design.md (how)
-- tasks.md (implementation steps)
-
-When ready to implement, run /cleto-apply
-
----
+Invoke the `ancleto-propose` skill with the Skill tool and follow it exactly; do not improvise steps.
 
 **Input**: The argument after `/cleto-propose` is the change name (kebab-case), OR a description of what the user wants to build.
 
-**Steps**
-
-1. **Resolve Work Item context and derive change name**
-
-   Resolve Work Item context in this order — stop at the first source that yields data:
-
-   a. **In-session context** — If WI data was already fetched in this session, use it. Proceed to name derivation below.
-   b. **`context.md`** — If a change name was provided as argument and `aspec/changes/<name>/context.md` exists, read it and use its content. Proceed to name derivation.
-   c. **Ask the user** — Use the **AskUserQuestion tool** to ask for the Work Item reference. Two accepted formats:
-
-   - **ID + Project** — e.g., ID `12345` and project `MyProject`
-   - **Full URL** — e.g., `https://dev.azure.com/org/MyProject/_workitems/edit/12345`
-
-   > "Do you have an Azure DevOps Work Item for this change? Provide the Work Item ID and Azure DevOps project name (e.g., ID: `12345`, Project: `MyProject`), or paste the full Work Item URL. Skip to describe the change manually."
-
-   **If WI provided:**
-
-   - If URL provided: extract numeric ID (pattern: `_workitems/edit/{id}`) AND project name (pattern: `/{org}/{project}/_workitems/`)
-   - Use BOTH `id` AND `project` when calling the AzDO MCP (`wit_get_work_item`) — never call with ID alone
-   - Extract from the response: `System.Id`, `System.Title`, `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`, `System.WorkItemType`
-   - Suggest a kebab-case name derived from `System.Title` (e.g., "Add payment gateway" → `add-payment-gateway`)
-   - Let the user accept or modify the suggested name before proceeding
-
-   **If skipped:**
-
-   - Display: "No work item linked — consider linking one for traceability."
-   - If no change name was provided as argument, ask what they want to build:
-     > "What change do you want to work on? Describe what you want to build or fix."
-   - Derive a kebab-case name from the description.
-
-   WI context is held **in-memory** for this flow — no `context.md` is written.
-
-   **IMPORTANT**: Do NOT proceed without a change name.
-
-2. **Create the change directory**
-
-   Create the directory `aspec/changes/<name>/` in the repository.
-
-   This scaffolds the change at `aspec/changes/<name>/` with `.aspec.yaml`.
-
-3. **Get the artifact build order**
-
-   ```bash
-   aspec status --change "<name>" --json
-   ```
-
-   Parse the JSON to get:
-
-   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
-   - `artifacts`: list of all artifacts with their status and dependencies
-
-4. **Create artifacts in sequence until apply-ready**
-
-   Use the **TodoWrite tool** to track progress through the artifacts.
-
-   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
-
-   a. **For each artifact that is `ready` (dependencies satisfied)**:
-
-   - Get instructions:
-     ```bash
-     aspec instructions <artifact-id> --change "<name>" --json
-     ```
-   - The instructions JSON includes:
-     - `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 for this artifact type
-     - `outputPath`: Where to write the artifact
-     - `dependencies`: Completed artifacts to read for context
-   - Read any completed dependency files for context
-   - If creating the first artifact (proposal):
-- If WI context is available (in-memory): use 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}`
-    - Create the artifact file using `template` as the structure
-   - Apply `context` and `rules` as constraints - but do NOT copy them into the file
-   - Show brief progress: "✓ Created <artifact-id>"
-
-   b. **Continue until all `applyRequires` artifacts are complete**
-
-   - After creating each artifact, re-run `aspec status --change "<name>" --json`
-   - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
-   - Stop when all `applyRequires` artifacts are done
-
-   c. **If an artifact requires user input** (unclear context):
-
-   - Use **AskUserQuestion tool** to clarify
-   - Then continue with creation
-
-5. **Show final status**
-   ```bash
-   aspec status --change "<name>"
-   ```
-
-**Output**
-
-After completing all artifacts, summarize:
-
-- Change name and location
-- List of artifacts created with brief descriptions
-- What's ready: "All artifacts created! Ready for implementation."
-- Prompt: "Run `/cleto-apply` to start implementing."
-
-**Artifact Creation Guidelines**
-
-- Follow the `instruction` field from `aspec instructions` for each artifact type
-- The schema defines what each artifact should contain - follow it
-- Read dependency artifacts for context before creating new ones
-- Use `template` as the structure for your output file - fill in its sections
-- **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
-
-**Guardrails**
-
-- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
-- Always read dependency artifacts before creating a new one
-- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
-- If a change with that name already exists, ask if user wants to continue it or create a new one
-- Verify each artifact file exists after writing before proceeding to next
+Work Item grounding (when the request references a Work Item) is owned by `@context-resolver`.