@lvlup-sw/exarchos 2.0.1

package/skills/git-worktrees/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: git-worktrees
+description: "Git worktree management for parallel development in agent team workflows. Use when creating worktrees, validating worktree paths, or setting up isolated development environments. Trigger: \"create worktree\", \"worktree setup\", or during /delegate task dispatch. Do NOT use for branch creation without delegation context."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: utility
+  phase-affinity: delegate
+---
+
+# Git Worktrees Skill
+
+## Overview
+
+Create and manage isolated git worktrees for parallel development tasks.
+
+## Triggers
+
+Activate this skill when:
+- Multiple tasks can run in parallel
+- User runs `/exarchos:delegate` with parallelizable tasks
+- Need isolated environment for subagent work
+- User explicitly requests worktree setup
+
+## Worktree Directory Location
+
+**Priority Order:**
+1. `.worktrees/` - If exists and gitignored
+2. `worktrees/` - If exists and gitignored
+3. Check `CLAUDE.md` for project conventions
+4. Ask user if unclear
+
+**Safety Check (REQUIRED):**
+```bash
+# Verify directory is gitignored before creating
+git check-ignore -q .worktrees && echo "Safe" || echo "NOT GITIGNORED"
+```
+
+If not gitignored, add to `.gitignore`:
+```
+.worktrees/
+```
+
+## Worktree Lifecycle
+
+### 1. Create Worktree
+
+```bash
+# Create feature branch
+git branch feature/task-name main
+
+# Create worktree
+git worktree add .worktrees/task-name feature/task-name
+
+# Verify creation
+git worktree list
+```
+
+**Naming Convention:** `.worktrees/<task-id>-<brief-name>`
+- Example: `.worktrees/001-user-auth`
+- Example: `.worktrees/002-api-endpoints`
+
+### 2. Setup Environment
+
+**Auto-detect project type and run setup:**
+
+| Indicator | Setup Command |
+|-----------|---------------|
+| `package.json` | `npm install` or `pnpm install` |
+| `Cargo.toml` | `cargo build` |
+| `requirements.txt` | `pip install -r requirements.txt` |
+| `*.csproj` | `dotnet restore` |
+| `go.mod` | `go mod download` |
+
+**Setup Script:**
+```bash
+cd .worktrees/task-name
+
+# Node.js
+if [ -f "package.json" ]; then
+  npm install
+fi
+
+# .NET
+if ls *.csproj 1> /dev/null 2>&1; then
+  dotnet restore
+fi
+
+# Rust
+if [ -f "Cargo.toml" ]; then
+  cargo build
+fi
+```
+
+### 3. Baseline Verification
+
+Run baseline tests to ensure the worktree is ready:
+
+```bash
+scripts/verify-worktree-baseline.sh --worktree-path .worktrees/task-name
+```
+
+The script auto-detects project type (Node.js, .NET, Rust) and runs the appropriate test command.
+
+**On exit 0:** Baseline tests pass — worktree is ready for implementation.
+**On exit 1:** Baseline tests failed — investigate before proceeding.
+**On exit 2:** Unknown project type — manual verification required.
+
+If baseline fails:
+1. Check if main branch has failing tests
+2. Report issue to user
+3. Do not proceed with implementation
+
+### 4. Work in Worktree
+
+Subagents work in worktree directory:
+- Full isolation from other tasks
+- Commits go to feature branch
+- Can run tests independently
+
+### 5. Cleanup After Merge
+
+```bash
+# After PR merged, remove worktree
+git worktree remove .worktrees/task-name
+
+# Optionally delete branch
+git branch -d feature/task-name
+
+# Prune stale worktree refs
+git worktree prune
+```
+
+## Parallel Worktree Management
+
+### Creating Multiple Worktrees
+
+For parallel task groups from implementation plan:
+
+```bash
+# Group 1 tasks
+git worktree add .worktrees/001-types feature/001-types
+git worktree add .worktrees/002-tests feature/002-tests
+
+# Group 2 tasks (parallel to Group 1)
+git worktree add .worktrees/003-api feature/003-api
+git worktree add .worktrees/004-handlers feature/004-handlers
+```
+
+### Tracking Active Worktrees
+
+Maintain awareness of active worktrees:
+```bash
+git worktree list
+```
+
+Report format:
+```markdown
+## Active Worktrees
+
+| Task | Branch | Status |
+|------|--------|--------|
+| 001-types | feature/001-types | In Progress |
+| 002-tests | feature/002-tests | Complete |
+| 003-api | feature/003-api | In Progress |
+```
+
+## Worktree Commands Reference
+
+| Action | Command |
+|--------|---------|
+| List worktrees | `git worktree list` |
+| Add worktree | `git worktree add <path> <branch>` |
+| Remove worktree | `git worktree remove <path>` |
+| Prune stale refs | `git worktree prune` |
+| Lock (prevent removal) | `git worktree lock <path>` |
+| Unlock | `git worktree unlock <path>` |
+
+## Worktree Validation
+
+### Why Validate?
+
+Subagents MUST verify they're in a worktree before making changes. Working in the main project root causes:
+- Merge conflicts between parallel tasks
+- Accidental changes to shared state
+- Build/test interference
+
+### Worktree Verification
+
+Run the worktree verification script before any file modifications:
+
+```bash
+scripts/verify-worktree.sh
+```
+
+To check a specific path instead of the current directory:
+
+```bash
+scripts/verify-worktree.sh --cwd /path/to/.worktrees/task-name
+```
+
+**On exit 0:** In a valid worktree — proceed with implementation.
+**On exit 1:** NOT in a worktree — STOP immediately, do not modify files.
+
+### Subagent Instructions
+
+Include in all implementer prompts:
+
+```markdown
+## CRITICAL: Worktree Verification (MANDATORY)
+
+Before making ANY file changes, run:
+
+    scripts/verify-worktree.sh
+
+If exit code is non-zero: STOP and report error.
+DO NOT proceed with any modifications outside a worktree.
+```
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Create worktrees in tracked directory | Use gitignored `.worktrees/` |
+| Skip baseline test verification | Always verify tests pass first |
+| Leave stale worktrees | Clean up after merge |
+| Forget dependency installation | Run project setup in each worktree |
+| Mix work across worktrees | One task per worktree |
+
+## Integration with Delegation
+
+When delegation skill spawns parallel tasks:
+1. Create worktree for each parallel group
+2. Set up environment
+3. Verify baseline tests
+4. Dispatch subagent with worktree path
+5. Track progress
+6. Merge branches in dependency order
+7. Clean up worktrees
+
+## Completion Criteria
+
+For worktree setup:
+- [ ] Directory is gitignored
+- [ ] Worktree created successfully
+- [ ] Environment dependencies installed
+- [ ] Baseline tests pass
+- [ ] Ready for subagent work
+
+For worktree cleanup:
+- [ ] Feature branch merged to main
+- [ ] Worktree removed
+- [ ] Branch deleted (if merged)
+- [ ] Stale refs pruned

package/skills/implementation-planning/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: implementation-planning
+description: "Transform design documents into TDD-based implementation plans with granular, parallelizable tasks. Use when the user says 'plan implementation', 'create tasks from design', 'break down the design', or runs /plan. Enforces the Iron Law: no production code without a failing test first. Do NOT use for brainstorming, debugging, or code review. Requires an existing design document as input. Do NOT use if no design document exists — use /ideate first."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: plan
+---
+
+# Implementation Planning Skill
+
+## Overview
+
+Transform design documents into TDD-based implementation plans with granular, parallelizable tasks. Ensures complete spec coverage through explicit traceability.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/plan` command
+- User wants to break down a design into tasks
+- A design document exists and needs implementation steps
+- User says "plan the implementation" or similar
+- Auto-chained from `/exarchos:ideate` after design completion
+- Auto-chained from plan-review with `--revise` flag (gaps found)
+
+## Revision Mode (--revise flag)
+
+When invoked with `--revise`, plan-review found gaps. Read `.planReview.gaps` from state, re-read the design, add tasks to address each gap, update the plan file, then clear gaps via `mcp__exarchos__exarchos_workflow` `action: "set"`.
+
+### Revision Loop Guard
+
+Max revisions: 3 per plan.
+
+After 3 failed revisions:
+1. Set `planReview.revisionsExhausted = true`
+2. Output: "Plan revision failed after 3 attempts. Design may be incomplete."
+3. Escalate: Suggest `/exarchos:ideate --redesign` to revisit design
+
+## The Iron Law
+
+> **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**
+
+Every implementation task MUST:
+1. Start with writing a failing test
+2. Specify the expected failure reason
+3. Only then implement minimum code to pass
+
+**Verify TDD compliance** in git history after implementation:
+
+```bash
+scripts/check-tdd-compliance.sh \
+  --repo-root . \
+  --branch feature/<name> \
+  --base-branch main
+```
+
+- **exit 0** — All commits have test files before or alongside implementation
+- **exit 1** — Violations found; commits have implementation without corresponding tests
+- **exit 2** — Usage error; check arguments
+
+## Planning Process
+
+### Step 1: Analyze Design Document
+
+Read the design document thoroughly. For each major section, extract:
+- **Problem Statement** — Context (no tasks, but informs scope)
+- **Chosen Approach** — Architectural decisions to implement
+- **Technical Design** — Core implementation requirements
+- **Integration Points** — Integration and glue code tasks
+- **Testing Strategy** — Test coverage requirements
+- **Open Questions** — Decisions to resolve or explicitly defer
+
+### Step 1.5: Spec Tracing (Required)
+
+Create a traceability matrix mapping design sections to planned tasks.
+Consult `references/spec-tracing-guide.md` for the methodology and template.
+
+**Pre-populate the matrix** using the traceability generator script:
+
+```bash
+scripts/generate-traceability.sh \
+  --design-file docs/designs/<feature>.md \
+  --plan-file docs/plans/<date>-<feature>.md \
+  --output docs/plans/<date>-<feature>-traceability.md
+```
+
+- **exit 0** — Matrix generated; review and fill in "Key Requirements" column
+- **exit 1** — Parse error; design document may lack expected `##`/`###` headers
+- **exit 2** — Usage error; check arguments
+
+### Step 2: Decompose into Tasks
+
+Each task follows the TDD format in `references/task-template.md`.
+
+**Granularity Guidelines:**
+- Each task: 2-5 minutes of focused work
+- One test = one behavior
+- Prefer many small tasks over few large ones
+
+Assign a `testingStrategy` to each task using `references/testing-strategy-guide.md` to control which verification techniques agents apply. Auto-determine `propertyTests` and `benchmarks` flags by matching each task's description and file paths against the category tables — do not leave these for the implementer to decide.
+
+**Task Ordering:**
+1. Foundation first (types, interfaces, data structures)
+2. Core behaviors second
+3. Edge cases and error handling third
+4. Integration and glue code last
+
+### Step 3: Identify Parallelization
+
+Analyze dependencies to find sequential chains and parallel-safe groups that can run simultaneously in worktrees.
+
+### Step 4: Generate Plan Document
+
+Save to: `docs/plans/YYYY-MM-DD-<feature>.md`
+Use the template from `references/plan-document-template.md`.
+
+### Step 5: Plan Verification
+
+Run deterministic verification scripts instead of manual checklist review.
+
+**5a. Design-to-plan coverage** — verify every Technical Design subsection maps to a task:
+
+```bash
+scripts/verify-plan-coverage.sh \
+  --design-file docs/designs/<feature>.md \
+  --plan-file docs/plans/<date>-<feature>.md
+```
+
+- **exit 0** — All design sections covered; proceed to 5b
+- **exit 1** — Gaps found; add tasks for uncovered sections or defer with rationale
+- **exit 2** — Usage error or empty design; check arguments
+
+**5b. Spec coverage check** — verify planned test files exist and pass:
+
+```bash
+scripts/spec-coverage-check.sh \
+  --plan-file docs/plans/<date>-<feature>.md \
+  --repo-root . \
+  --threshold 80
+```
+
+- **exit 0** — All planned tests found and passing; plan verification complete
+- **exit 1** — Missing test files or test failures; create missing tests or fix failures
+- **exit 2** — Usage error; check arguments
+
+For reference, consult `references/spec-tracing-guide.md` for the underlying methodology.
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Write implementation first | Write failing test first |
+| Create large tasks | Break into 2-5 min chunks |
+| Skip dependency analysis | Identify parallel opportunities |
+| Vague test descriptions | Specific: Method_Scenario_Outcome |
+| Assume tests pass | Verify each test fails first |
+| Add "nice to have" code | Only what the test requires |
+
+## Rationalization Debunking
+
+| Excuse | Reality |
+|--------|---------|
+| "This is too simple for tests" | Simple code breaks too. Test it. |
+| "I'll add tests after" | You won't. Or they'll be weak. |
+| "Tests slow me down" | Debugging without tests is slower. |
+| "The design is obvious" | Obvious to you now. Not in 3 months. |
+
+## State Management
+
+On plan save:
+```
+action: "set", featureId: "<id>", phase: "plan-review", updates: {
+  "artifacts": { "plan": "<plan-file-path>" },
+  "tasks": [{ "id": "001", "title": "...", "status": "pending", "branch": "...", "blockedBy": [] }, ...]
+}
+```
+
+## Completion Criteria
+
+- [ ] Design document read and understood
+- [ ] Spec traceability table created (`scripts/generate-traceability.sh`)
+- [ ] Scope declared (full or partial with rationale)
+- [ ] Tasks decomposed to 2-5 min granularity
+- [ ] Each task starts with failing test
+- [ ] Dependencies mapped
+- [ ] Parallel groups identified
+- [ ] Plan verification passed — `scripts/verify-plan-coverage.sh` exit 0
+- [ ] Spec coverage check passed — `scripts/spec-coverage-check.sh` exit 0
+- [ ] Coverage thresholds met — `scripts/check-coverage-thresholds.sh` exit 0:
+
+```bash
+scripts/check-coverage-thresholds.sh \
+  --coverage-file coverage/coverage-summary.json \
+  --line-threshold 80 \
+  --branch-threshold 70 \
+  --function-threshold 100
+```
+
+- [ ] Plan saved to `docs/plans/`
+- [ ] State file updated with plan path and tasks
+
+## Transition
+
+After planning completes, **auto-continue to plan-review** (delta analysis):
+
+1. Set `.phase = "plan-review"` and populate tasks in state
+2. Run plan-review: compare design sections against planned tasks
+   - Gaps found: set `.planReview.gaps`, auto-loop back to `/exarchos:plan --revise`
+   - No gaps: present to user for approval (human checkpoint)
+   - On approval: set `.planReview.approved = true`, invoke `/exarchos:delegate`
+
+**REQUIRED:** Run `scripts/verify-plan-coverage.sh --design-file <design> --plan-file <plan>`. If exit code 1: auto-invoke `Skill({ skill: "exarchos:plan", args: "--revise <design>" })`. If exit code 0: proceed to delegation.
+
+## Exarchos Integration
+
+On plan completion, auto-emitted by `exarchos_workflow` `set` when phase transitions — emits `workflow.transition` from plan to plan-review. No manual `exarchos_event` append needed.
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| `verify-plan-coverage.sh` exit 1 | Design sections not mapped to tasks | Add tasks for uncovered sections or add explicit deferral rationale |
+| `spec-coverage-check.sh` exit 1 | Planned test files missing or failing | Create missing test stubs, verify file paths in plan match actual paths |
+| `generate-traceability.sh` exit 1 | Design doc missing expected `##`/`###` headers | Verify design uses standard Markdown headings |
+| Revision loop (3+ attempts) | Persistent gaps between design and plan | Set `planReview.revisionsExhausted = true`, suggest `/ideate --redesign` |
+
+## Performance Notes
+
+- Complete each step fully before advancing — quality over speed
+- Do not skip validation checks even when the change appears trivial
+- Trace every design section to at least one task. Do not leave uncovered sections without explicit rationale.

package/skills/implementation-planning/references/plan-document-template.md

@@ -0,0 +1,42 @@
+# Plan Document Template
+
+Save to: `docs/plans/YYYY-MM-DD-<feature>.md`
+
+```markdown
+# Implementation Plan: [Feature Name]
+
+## Source Design
+Link: `docs/designs/YYYY-MM-DD-<feature>.md`
+
+## Scope
+**Target:** [Full design | Partial: <specific components>]
+**Excluded:** [None | List excluded sections with rationale]
+
+## Summary
+- Total tasks: [N]
+- Parallel groups: [N]
+- Estimated test count: [N]
+- Design coverage: [X of Y sections covered]
+
+## Spec Traceability
+
+[Traceability matrix from Step 1.5]
+
+## Task Breakdown
+
+[Tasks in execution order]
+
+## Parallelization Strategy
+
+[Which tasks can run in parallel worktrees]
+
+## Deferred Items
+
+[Open questions or design sections not addressed, with rationale]
+
+## Completion Checklist
+- [ ] All tests written before implementation
+- [ ] All tests pass
+- [ ] Code coverage meets standards
+- [ ] Ready for review
+```

package/skills/implementation-planning/references/spec-tracing-guide.md

@@ -0,0 +1,51 @@
+# Spec Tracing Guide
+
+## Traceability Matrix
+
+Create a traceability table mapping design sections to planned tasks. This ensures complete coverage.
+
+```markdown
+## Spec Traceability
+
+### Scope Declaration
+
+**Target:** [Full design | Partial: <specific components>]
+**Excluded:** [List any intentionally excluded sections with rationale]
+
+### Traceability Matrix
+
+| Design Section | Key Requirements | Task ID(s) | Status |
+|----------------|-----------------|------------|--------|
+| Technical Design > Component A | - Requirement 1<br>- Requirement 2 | 001, 002 | Covered |
+| Technical Design > Component B | - Requirement 3 | 003 | Covered |
+| Integration Points > X | - Connection to Y | 004 | Covered |
+| Testing Strategy | - Unit tests<br>- Integration tests | 005, 006 | Covered |
+| Open Questions > Q1 | Decision needed | — | Deferred: [reason] |
+```
+
+### Rules
+
+- Every sub-section of Technical Design MUST map to at least one task
+- Every file in "Files Changed" table MUST be touched by at least one task
+- Open Questions MUST be resolved OR explicitly deferred with rationale
+- For partial plans, declare scope upfront and only trace in-scope sections
+
+## Plan Verification
+
+Before saving, verify completeness against the design document.
+
+### Coverage Checklist
+
+- [ ] Every sub-section of "Technical Design" has at least one task
+- [ ] All files in "Files Changed" table are touched by tasks
+- [ ] Testing strategy items have corresponding test tasks
+- [ ] Open questions are resolved OR explicitly deferred with rationale
+- [ ] For partial plans: scope declaration is clear and justified
+
+### Delta Analysis
+
+Compare design sections against task list. For each gap:
+1. Create a task to address it, OR
+2. Add to "Deferred Items" with explicit rationale
+
+If significant gaps remain that cannot be justified, **do not proceed** — return to design phase for clarification.

package/skills/implementation-planning/references/task-template.md

@@ -0,0 +1,43 @@
+# TDD Task Template
+
+## Task Format
+
+Each task follows this structure:
+
+```markdown
+### Task [N]: [Brief Description]
+
+**Phase:** [RED | GREEN | REFACTOR]
+
+**TDD Steps:**
+1. [RED] Write test: `TestName_Scenario_ExpectedOutcome`
+   - File: `path/to/test.ts`
+   - Expected failure: [Specific failure reason]
+   - Run: `npm run test:run` - MUST FAIL
+
+2. [GREEN] Implement minimum code
+   - File: `path/to/implementation.ts`
+   - Changes: [Brief description]
+   - Run: `npm run test:run` - MUST PASS
+
+3. [REFACTOR] Clean up (optional)
+   - Apply: [SOLID principle or improvement]
+   - Run: `npm run test:run` - MUST STAY GREEN
+
+**Verification:**
+- [ ] Witnessed test fail for the right reason
+- [ ] Test passes after implementation
+- [ ] No extra code beyond test requirements
+
+**Dependencies:** [Task IDs this depends on, or "None"]
+**Parallelizable:** [Yes/No]
+```
+
+## Test Naming Convention
+
+Follow: `MethodName_Scenario_ExpectedOutcome`
+
+**Examples:**
+- `CreateUser_ValidInput_ReturnsUserId`
+- `CreateUser_EmptyEmail_ThrowsValidationError`
+- `GetUser_NonExistentId_ReturnsNull`