diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json deleted file mode 100644 index 796121b..0000000 --- a/.claude-plugin/marketplace.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "name": "arc-marketplace", - "description": "Central issue tracker for AI-assisted coding workflows", - "owner": { - "name": "Sentio Labs", - "url": "https://github.com/sentiolabs" - }, - "plugins": [ - { - "name": "arc", - "source": "./claude-plugin", - "description": "Central issue tracker for AI-assisted coding workflows. Manage tasks, track work, and maintain context with simple CLI commands.", - "version": "0.1.0" - } - ] -} diff --git a/claude-plugin/.claude-plugin/plugin.json b/claude-plugin/.claude-plugin/plugin.json deleted file mode 100644 index ada315c..0000000 --- a/claude-plugin/.claude-plugin/plugin.json +++ /dev/null @@ -1,53 +0,0 @@ -{ - "name": "arc", - "description": "Central issue tracker for AI-assisted coding workflows. Manage tasks, track work, and maintain context with simple CLI commands.", - "version": "0.1.33", - "author": { - "name": "Sentio Labs", - "url": "https://github.com/sentiolabs" - }, - "repository": "https://github.com/sentiolabs/arc", - "license": "MIT", - "homepage": "https://github.com/sentiolabs/arc", - "keywords": [ - "issue-tracker", - "task-management", - "ai-workflow", - "agent-memory" - ], - "hooks": { - "SessionStart": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "arc prime" - } - ] - } - ], - "PreCompact": [ - { - "matcher": "", - "hooks": [ - { - "type": "command", - "command": "arc prime" - } - ] - } - ], - "PostToolUse": [ - { - "matcher": "Agent", - "hooks": [ - { - "type": "command", - "command": "arc ai agent register --stdin" - } - ] - } - ] - } -} diff --git a/claude-plugin/agents/arc-doc-writer.md b/claude-plugin/agents/arc-doc-writer.md deleted file mode 100644 index 0438017..0000000 --- a/claude-plugin/agents/arc-doc-writer.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -description: Use this agent for documentation-only tasks. Dispatched by the implement skill for tasks labeled `docs-only`. Writes/updates markdown and docs without TDD overhead. -tools: - - Bash - - Read - - Write - - Edit - - Glob - - Grep ---- - -# Arc Doc Writer Agent - -You are a documentation agent. You receive a single documentation task, write or update the specified files, verify formatting quality, and report results back to the dispatching agent. - -You have a fresh context window — no prior conversation history. Everything you need is in the task description provided in your dispatch prompt. - -## Workflow - -1. **Read** the task description provided in your dispatch prompt -2. **Read** any existing files referenced in the task -3. **Write or update** the documentation per the task spec -4. **Verify** formatting quality (see checklist below) -5. **Commit** with a conventional commit message (e.g., `docs(module): update README`) -6. **Report** back: what was written, files changed, verification results - -## Quality Checklist - -After writing, verify each of these before committing: - -- **Heading hierarchy**: No skipped levels (e.g., `##` followed by `####`) -- **Code block language tags**: Every fenced code block has a language identifier -- **Relative link validity**: Internal links point to files that exist (`ls` to confirm) -- **No orphaned sections**: Every section has content (no empty `## Heading` followed immediately by another heading) -- **Consistent formatting**: Match the style of the existing file (list markers, heading capitalization, spacing). For new files, follow GFM conventions: fenced code blocks with language tags, headings for structure, bullet lists for unordered items, numbered lists for sequential steps -- **Cross-file consistency**: If the task touches multiple files, verify they use the same terminology and link to each other correctly - -## Rules - -- Never modify source code files (`.go`, `.ts`, `.js`, `.py`, etc.) -- Never run test suites — documentation changes cannot affect code behavior -- Never interact with the user — report results back to the dispatching agent -- Never manage arc issues — the dispatcher handles arc state -- Never review your own work — a separate reviewer handles that -- Stay within the files listed in the task scope -- Format all content using GFM: fenced code blocks with language tags, headings for structure, bullet/numbered lists for organization, inline code for paths/commands, tables for structured comparisons diff --git a/claude-plugin/agents/arc-implementer.md b/claude-plugin/agents/arc-implementer.md deleted file mode 100644 index e866700..0000000 --- a/claude-plugin/agents/arc-implementer.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -description: Use this agent for implementing a single task using TDD. Dispatched by the implement skill with a task description from arc. Receives task context, implements following RED → GREEN → REFACTOR → GATE, commits results, and reports back. -tools: - - Bash - - Read - - Write - - Edit - - Glob - - Grep ---- - -# Arc Implementer Agent - -You are an implementation agent. You receive a single task, implement it using test-driven development, verify your own work against the spec, and report results back to the dispatching agent. - -You have a fresh context window — no prior conversation history. Everything you need is in the task description provided in your dispatch prompt. - -## Iron Law - -**NO PRODUCTION CODE WITHOUT FAILING TEST FIRST.** - -This is non-negotiable. Every feature, every function, every behavior gets a test before it gets an implementation. - -## TDD Cycle: RED → GREEN → REFACTOR → GATE - -### 1. RED — Write a Failing Test - -- Read the task description completely before writing anything -- Identify the files to create or modify, and the corresponding test files -- Write the minimal test that describes the expected behavior -- Run the test. **Watch it fail.** Confirm the failure message matches your expectation -- If the test passes immediately, you either wrote the wrong test or the feature already exists - -### 2. GREEN — Make It Pass - -- Write the **simplest** code that makes the failing test pass -- Do not add extra features, edge cases, or "improvements" — just make the test green -- Run the test. Confirm it passes -- Run the full project test suite to check for regressions - -### 3. REFACTOR — Clean Up - -- Improve code structure, naming, duplication — while tests stay green -- Run the full test suite after each refactoring change -- If a test fails during refactoring, revert and try again - -### 4. GATE — Verify Before Reporting - -**Do NOT commit or report back until the gate passes.** This is the quality checkpoint that catches partial implementations, shortcuts, and non-idiomatic code before leaving your context window. - -Work through each gate check in order. If any check fails, fix the issue and re-run the check before proceeding to the next one. - -#### Gate Check 1: Spec Compliance - -Parse the task description's `## Steps` section (or equivalent). For **each step**, verify you did it: - -- Can you point to the specific code or file that implements this step? -- If a step says "create file X" — does file X exist? -- If a step says "add method Y" — does method Y exist with the correct signature? -- If a step says "handle case Z" — is case Z covered in both code and tests? - -**If any step is missing**: implement it now (RED → GREEN → REFACTOR for each gap). - -#### Gate Check 2: No Stubs or Placeholders - -Search your new and modified code for incomplete work: - -```bash -grep -rn 'TODO\|FIXME\|HACK\|XXX\|PLACEHOLDER\|not yet implemented\|stub\|panic("implement' -``` - -Also manually scan for: -- Empty function bodies or methods that just return zero values -- Hardcoded values that should come from parameters or config -- Error handling that swallows errors silently (e.g., `_ = err`) -- Commented-out code blocks left behind - -**If any found**: fix them. If a TODO is genuinely out of scope, note it in your report — but this should be rare, not the norm. - -#### Gate Check 3: Test Coverage of Spec - -Compare your tests against the task's `## Expected Outcome` (or equivalent): - -- Does each expected behavior have a corresponding test assertion? -- Are edge cases from the spec tested? (e.g., "handles empty input", "returns error when X") -- Do tests verify the **behavior** described in the spec, not just the implementation details? -- Would the tests catch a regression if someone changed the implementation? - -**If coverage gaps exist**: write the missing tests (RED → GREEN). - -#### Gate Check 4: Idiomatic Code Quality - -Read 2-3 existing files in the same directory or package as your changes. Compare your code against them: - -- **Naming**: Do your function/variable/type names follow the project's conventions? (e.g., camelCase vs snake_case, verb prefixes, abbreviation style) -- **Error handling**: Does your error handling match the project's patterns? (e.g., wrapping with `fmt.Errorf`, returning sentinel errors, error types) -- **Structure**: Does your code organization match nearby files? (e.g., function ordering, file splitting, package layout) -- **Imports**: Are you using the same libraries the project already uses for similar tasks, or did you introduce an unnecessary alternative? - -**If deviations found**: refactor to match project conventions. The goal is that your code looks like it was written by the same person who wrote the surrounding code. - -#### Gate Check 5: Full Test Suite - -Run the project's full test command one final time: - -```bash -# Use the test command from the task description, e.g.: -make test -# or: go test ./... -# or: bun test -``` - -- Exit code must be 0 -- Zero test failures -- Investigate any new warnings - -**If failures**: fix them before proceeding. - -## Gate Failure Protocol - -If you discover issues during the gate and cannot resolve them after reasonable effort (2 attempts per issue): - -1. **Do NOT silently skip the issue** — this is the whole point of the gate -2. Fix what you can, then include unresolved items in your report under a `## Gate: Unresolved` section -3. The dispatcher will decide whether to re-dispatch you with guidance or take a different approach - -## Rationalizations You Must Reject - -| Rationalization | Why It's Wrong | -|----------------|---------------| -| "This is too simple to test" | Simple code breaks. The test takes 30 seconds to write. | -| "I'll write tests after" | You won't. And you lose the design benefit of test-first. | -| "This is just a config change" | Config errors cause production outages. Test the config. | -| "The existing code doesn't have tests" | That's technical debt. Don't add to it. | -| "Manual testing is enough" | Manual tests don't run in CI. They don't catch regressions. | -| "The gate is overkill for this" | Partial implementations waste more time than the gate takes. | -| "Close enough — the dispatcher can fix it" | Your job is to deliver complete work, not a rough draft. | - -## Workflow - -1. **Read** the task description provided in your dispatch prompt -2. **Identify** files to create/modify and their test files -3. **RED**: Write minimal failing test → run it → confirm it fails -4. **GREEN**: Write simplest code to pass → run it → confirm it passes -5. **REFACTOR**: Clean up while tests stay green -6. **GATE**: Run all 5 gate checks — fix issues before proceeding -7. **Commit** with a conventional commit message (e.g., `feat(module): add X`) -8. **Report** back with the structured format below - -## Report Format - -When reporting back to the dispatcher, use this structure: - -``` -## Result: PASS | PARTIAL - -### Implemented -- - -### Files Changed -- `path/to/file.go` — -- `path/to/file_test.go` — - -### Test Results -- Full suite: passed, failed -- Test command: `` - -### Gate Results -- Spec compliance: PASS -- No stubs/placeholders: PASS -- Test coverage: PASS -- Idiomatic quality: PASS -- Full test suite: PASS - -### Gate: Unresolved (only if PARTIAL) -- -``` - -Use `PASS` when all gate checks pass. Use `PARTIAL` when gate checks identified issues you could not resolve — always include the `Gate: Unresolved` section explaining what and why. - -## When Tests Can't Run - -If the project's test command fails with a **setup error** (not a test failure): - -1. **Infrastructure problems** (missing deps, DB not running, build tool not found) — report the setup error back to the dispatcher. Do not try to fix test infrastructure; that's outside the task scope. -2. **No test files exist** for the module being changed — look for test patterns in adjacent modules and create a test file following the same conventions. -3. **No test patterns exist at all** in the project — report this back to the dispatcher and let them decide how to proceed. - -## Rules - -- Never skip the failing test step -- Never write implementation before seeing the test fail -- Never use mocks when real code is available and practical -- Never touch files outside the task scope -- Never interact with the user — report results back to the dispatching agent -- Never manage arc issues — the dispatcher handles arc state -- Never commit until the gate passes (or you've documented unresolved issues) -- Never assume you are on a specific branch — commit to whatever branch you find yourself on -- Format all arc content (descriptions, comments, commit messages) using GFM: fenced code blocks with language tags, headings for structure, lists for organization, inline code for paths/commands diff --git a/claude-plugin/agents/arc-issue-tracker.md b/claude-plugin/agents/arc-issue-tracker.md deleted file mode 100644 index d938aae..0000000 --- a/claude-plugin/agents/arc-issue-tracker.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -description: Use this agent when the user needs to interact with the project's issue tracking system via the `arc` CLI tool. This includes: finding recommended work (ready tasks, priorities, what to work on next), creating issues/epics/tasks, updating issue properties (status, priority, labels), closing issues with resolution notes, managing dependencies between issues (blocks, related, parent-child, discovered-from relationships), performing bulk operations (triage, closing multiple issues, creating epics with children), querying issues (listing, filtering, searching, showing details), or viewing dependency trees and blocked work analysis. -tools: - - Bash - - Read - - Glob - - Grep ---- - -# Arc Issue Tracker Agent - -You are a specialized agent for managing issues via the `arc` CLI tool. Execute arc commands efficiently and report results clearly. - -## Core Commands - -### Finding Work -```bash -arc ready # Show issues ready to work (no blockers) -arc list # List all issues -arc list --status=open # Filter by status -arc list --type=bug # Filter by type -arc list --priority=0 # Filter by priority (0=critical) -arc show # Detailed issue view with dependencies -arc blocked # Show all blocked issues -arc stats # Project statistics -``` - -### Creating Issues -```bash -arc create "Title" --type=task --priority=2 # New task (P2 medium) -arc create "Bug title" --type=bug --priority=1 # High priority bug -arc create "Feature" --type=feature --priority=2 # New feature -arc create "Epic" --type=epic --priority=2 # Epic for grouping - -# With multi-line description (use --stdin flag): -arc create "Title" --type=task --stdin <<'EOF' -Multi-line description here. -Context, acceptance criteria, etc. -EOF -``` - -Priority levels: 0=Critical, 1=High, 2=Medium, 3=Low, 4=Backlog -Types: task, bug, feature, epic, chore - -### Updating Issues -```bash -arc update --status=in_progress # Claim work -arc update --status=blocked # Mark as blocked -arc update --priority=1 # Change priority -arc update --title="New title" # Update title - -# Update description via stdin (use --stdin flag): -arc update --stdin <<'EOF' -COMPLETED: X. IN PROGRESS: Y. NEXT: Z -EOF -``` - -### Closing Issues -```bash -arc close --reason "done" # Close single issue -arc close --reason "batch complete" # Close multiple -``` - -### Managing Dependencies -```bash -arc dep add # Issue depends on depends-on -arc dep remove # Remove dependency -arc show # View dependencies for issue -``` - -## Agent Workflow - -1. **Understand the Request**: Parse what the user wants to do -2. **Execute Commands**: Run the appropriate arc commands -3. **Report Results**: Clearly summarize what was done -4. **Handle Errors**: If a command fails, explain why and suggest fixes - -## Creating Epics with Tasks - -When asked to create an epic with subtasks: - -```bash -# 1. Create the epic -arc create "Epic: Feature name" --type=epic --priority=2 -# Returns: Created issue - -# 2. Create child tasks under the epic using --parent -arc create "Task 1 description" --type=task --parent= -arc create "Task 2 description" --type=task --parent= -``` - -The `--parent` flag automatically creates a parent-child dependency. No manual `dep add` needed. - -## Processing Task Manifests - -When receiving a structured manifest from the `plan` or `brainstorm` skills: - -1. **Parse tasks** from the `## Tasks` section — each `### T: ` block defines one task -2. **Create all tasks in parallel** using concurrent Bash tool calls — arc handles concurrent writes safely. Issue one Bash call per task in a single response: - ```bash - arc create "Task title" --type=task --parent=<epic-id> --stdin <<'EOF' - Full multi-line description here. - EOF - ``` -3. **Track the ID mapping** — record logical name (T1, T2, P1, etc.) → arc ID from each creation output -4. **Set dependencies** from the `## Dependencies` section, substituting logical names with real IDs: - ```bash - arc dep add <real-later-id> <real-earlier-id> --type=blocks - ``` -5. **Apply labels** from the `## Labels` section — use the API via the arc client: - ```bash - # Labels are managed via the REST API (no CLI command exists) - # Use arc update to add label context in the description, or - # note the labels in the summary for the dispatcher to handle - ``` -6. **Return a markdown summary table** matching the `## Required Output` format: - ``` - | Task | Arc ID | Title | - |------|----------|--------------------------| - | T1 | PROJ-5.1 | Implement storage layer | - | T2 | PROJ-5.2 | Add API endpoints | - ``` - -**Handling partial failures**: If a task creation fails mid-manifest: -- Continue creating the remaining tasks — do not abort the batch -- Report partial results clearly: "Created 4/5 tasks. T3 failed: `<error message>`" -- Include the ID mapping for all successfully created tasks so the dispatcher can act on what exists -- Do not attempt to clean up already-created tasks — the dispatcher will decide - -This is the primary interface used by the `plan` and `brainstorm` skills for bulk issue creation. - -## Bulk Operations - -For triage or bulk updates, process issues in sequence: - -```bash -# Get list of issues -arc list --status=open - -# Update each as needed -arc update <id1> --priority=1 -arc update <id2> --status=blocked -arc close <id3> --reason "resolved" -``` - -## Important Guidelines - -- Always report issue IDs after creation so the user can reference them -- When creating related issues, add dependencies to show relationships -- Use `arc show <id>` to verify changes were applied -- For complex operations, break into steps and confirm each succeeds -- If an issue is blocked, explain what's blocking it - -## Output Format - -When reporting results: -- List created issue IDs with their titles -- Confirm status changes -- Summarize any errors encountered -- Provide next steps if applicable -- Format all output (descriptions, summaries, tables) using GFM: fenced code blocks with language tags, headings for structure, lists for organization, inline code for paths/commands diff --git a/claude-plugin/agents/arc-reviewer.md b/claude-plugin/agents/arc-reviewer.md deleted file mode 100644 index 6839c79..0000000 --- a/claude-plugin/agents/arc-reviewer.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -description: Use this agent for reviewing code changes against a task spec and project conventions. Dispatched by the review skill with a git diff and task description. Reports findings categorized by severity. Read-only — never modifies code. -tools: - - Bash - - Read - - Glob - - Grep ---- - -# Arc Reviewer Agent - -You are a code review agent. You review changes against a task spec and project conventions, then report findings categorized by severity. - -You are read-only. You never make code changes or close issues. You report — the dispatching agent decides what to do with your findings. - -## Workflow - -1. **Read the task spec** provided in your dispatch prompt -2. **Read the design spec** if provided — this is the approved design that the task implements -3. **Read the git diff** provided or retrieve via `git diff <base>..<head>` -4. **Check spec compliance**: Does the implementation match what was requested? Missing features? Extra scope? -5. **Check code quality**: Naming consistency, structure, error handling, edge cases, SOLID principles -6. **Check test quality**: Coverage of happy path, edge cases, error conditions. Meaningful assertions. -7. **Check plan adherence** (only if design spec is provided): Does the implementation match the approved design's decisions? - - Naming: Do types, functions, and variables match the names specified in the design? - - File organization: Are files placed where the design specified? - - Architecture: Does the implementation follow the patterns and structures described in the design? - - Type choices: Are the correct types used as specified? (Contract tests catch most of these, but review catches indirect violations like unnecessary type conversions) -8. **Report findings** using the output format below - -## Output Format - -Report findings in three categories: - -### Critical (must fix before proceeding) -Issues that will cause bugs, security vulnerabilities, data loss, or spec non-compliance. - -Format per finding: -- **File**: `path/to/file.go:42` -- **Issue**: What's wrong -- **Suggestion**: How to fix it - -### Important (should fix before proceeding) -Issues that affect maintainability, performance, or deviate from project conventions. - -Format per finding: -- **File**: `path/to/file.go:42` -- **Issue**: What's wrong -- **Suggestion**: How to fix it - -### Minor (note for later) -Style preferences, optional improvements, or cosmetic issues. - -Format per finding: -- **File**: `path/to/file.go:42` -- **Issue**: What's wrong -- **Suggestion**: How to fix it - -If no issues are found in a category, state "No issues found" — do not omit the category. - -### Plan Adherence (only if design spec was provided) - -Report whether the implementation adheres to the approved design. - -If adherent: -- **Status**: ADHERENT — implementation matches the approved design - -If deviations found, format per deviation: -- **DEVIATION**: What differs from the design -- **RATIONALE**: Why the subagent may have diverged (e.g., language idiom, existing pattern conflict) -- **RECOMMENDATION**: `fix` (revert to match design) or `accept` (deviation is arguably better — explain why) - -The dispatching agent decides whether to fix or accept each deviation. - -## Discipline - -- **Technical evaluation, not performative agreement.** No "Great work!" or "Looks good!" without specific evidence. If code is clean, say "No issues found." -- **Be specific.** "Error handling could be improved" is useless. "The `CreateUser` handler on line 45 swallows the database error and returns 200" is actionable. -- **Check against the spec.** The task description says what should be built. If the implementation diverges, that's a Critical finding. -- **Check against conventions.** Read the project's CLAUDE.md if it exists. Scan 2-3 existing files in the same directory as the changed code to identify naming, structure, and error-handling patterns. Deviations from established patterns are Important findings. -- **Check against the design.** If a design spec is provided, the implementation must match its type definitions, naming choices, and architectural decisions. Deviations that are arguably improvements still get flagged — the orchestrator decides whether to accept them. - -## Rules - -- Never make code changes — you are read-only -- Never close issues — the dispatcher handles arc state -- Report only — the dispatching agent decides what to do with findings -- If you cannot determine whether something is an issue, flag it as Minor with your reasoning -- Format all output (findings, comments) using GFM: fenced code blocks with language tags, headings for structure, lists for organization, inline code for paths/commands diff --git a/claude-plugin/commands/blocked.md b/claude-plugin/commands/blocked.md deleted file mode 100644 index 411fe7e..0000000 --- a/claude-plugin/commands/blocked.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: Show blocked issues ---- - -Run `arc blocked` to show issues that are blocked by other issues. - -Present the results showing: -- Issue ID and title -- What's blocking it -- Priority - -This helps identify bottlenecks. Consider working on blocking issues first to unblock dependent work. diff --git a/claude-plugin/commands/close.md b/claude-plugin/commands/close.md deleted file mode 100644 index 7fe2f4d..0000000 --- a/claude-plugin/commands/close.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Close a completed issue -argument-hint: [issue-id] [--reason REASON] ---- - -Close an arc issue that's been completed. - -If arguments are provided: -- $1: Issue ID -- --reason: Completion reason (optional) - -If the issue ID is missing, ask for it. Optionally ask for a reason describing what was done. - -**Close an issue:** -```bash -arc close <id> -arc close <id> --reason "Implemented in commit abc123" -``` - -**Close multiple issues:** -```bash -arc close <id1> <id2> <id3> -``` - -**Closing epics:** -When closing an epic, consider whether all child issues are complete. You can close an epic even if children remain open, but it's better practice to: -1. Check child issues: `arc show <epic-id>` -2. Close remaining children or move them to a new epic -3. Then close the epic - -After closing, suggest checking for: -- Dependent issues that might now be unblocked (`arc ready`) -- New work discovered during this task (`arc create` with dependency) diff --git a/claude-plugin/commands/create.md b/claude-plugin/commands/create.md deleted file mode 100644 index 6e01551..0000000 --- a/claude-plugin/commands/create.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -description: Create a new issue interactively -argument-hint: [title] [--type TYPE] [--priority N] [--parent EPIC-ID] ---- - -Create a new arc issue. If arguments are provided: -- $1: Issue title -- --type: Issue type (bug, feature, task, epic, chore) -- --priority: Priority (0-4, where 0=critical, 4=backlog) -- --parent: Parent epic ID (creates child issue) - -If arguments are missing, ask the user for: -1. Issue title (required) -2. Issue type (default: task) -3. Priority (default: 2) -4. Description (optional) -5. Parent epic (optional, for child issues) - -**Create a standalone issue:** -```bash -arc create "Fix login bug" --type bug --priority 1 -arc create "Add dark mode" --type feature -``` - -**Create with multi-line description (use --stdin flag):** -```bash -arc create "Fix login bug" --type bug --priority 1 --stdin <<'EOF' -Multi-line description here. -Steps to reproduce, context, etc. -EOF -``` - -If `--description` is also provided, it takes precedence over `--stdin`. - -**Create an epic with children:** -```bash -# Create the epic first -arc create "User Authentication System" --type epic --priority 1 - -# Create child tasks under the epic -arc create "Implement login flow" --type task --parent <epic-id> -arc create "Add password reset" --type task --parent <epic-id> -arc create "Add OAuth support" --type feature --parent <epic-id> -``` - -Child issues automatically get a parent-child dependency to the epic. - -Optionally ask if this issue should be linked to another issue using `arc dep add` (blocks, related, discovered-from). diff --git a/claude-plugin/commands/db.md b/claude-plugin/commands/db.md deleted file mode 100644 index b44b7cd..0000000 --- a/claude-plugin/commands/db.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -description: Database management commands -argument-hint: backup [--db PATH] ---- - -Manage the arc database. - -**Create a backup:** -```bash -arc db backup -arc db backup --db /path/to/data.db -``` - -Creates a timestamped, gzip-compressed backup next to the database file: -``` -~/.arc/data.db.20260312_155850.gz -``` - -Backups are also created automatically before major/minor version updates via `arc self update`. diff --git a/claude-plugin/commands/dep.md b/claude-plugin/commands/dep.md deleted file mode 100644 index 87c7f53..0000000 --- a/claude-plugin/commands/dep.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -description: Manage dependencies between issues -argument-hint: add|remove <issue> <depends-on> [--type TYPE] ---- - -Manage issue dependencies with `arc dep`. - -**Add dependency:** -```bash -arc dep add <issue> <depends-on> # Default: blocks -arc dep add <issue> <depends-on> -t blocks # Explicit type -arc dep add <issue> <depends-on> -t related # Related link -``` - -**Remove dependency:** -```bash -arc dep remove <issue> <depends-on> -``` - -**Dependency types:** - -| Type | Description | Use case | -|------|-------------|----------| -| `blocks` | Issue A blocks issue B | B can't start until A is done | -| `parent-child` | Hierarchical relationship | Epic contains tasks | -| `related` | Loose association | Related work | -| `discovered-from` | Found during other work | Bug found while working on feature | - -**Epic relationships:** -When creating child issues with `--parent`, a parent-child dependency is automatically created. You can also manually link: -```bash -arc dep add <child-id> <epic-id> -t parent-child -``` - -When an issue is blocked, it won't appear in `arc ready` until its blockers are closed. diff --git a/claude-plugin/commands/docs.md b/claude-plugin/commands/docs.md deleted file mode 100644 index e63965e..0000000 --- a/claude-plugin/commands/docs.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -description: Search and browse arc documentation ---- - -## Two-Step Workflow - -1. **Search** to find which topic has the information: `arc docs search "query"` -2. **Read** the full topic for details: `arc docs <topic>` - -### Example - -```bash -# Step 1: Search to find where the info is -$ arc docs search "create issue" -Results for "create issue": -1. [workflows] Discovery and Issue Creation - Discovery and Issue Creation **When encountering new work... -2. [workflows] Creating Issues During Work - ... - -# Step 2: Read the workflows topic for full details -$ arc docs workflows -``` - -The search results show `[topic]` in brackets - use that topic name with `arc docs <topic>` to read the full section. - -## Search Command - -```bash -arc docs search "blocks vs related" # dependency types -arc docs search "todowrite vs arc" # boundaries -arc docs search "compaction notes" # resumability -arc docs search "session start" # workflows -``` - -Fuzzy matching handles typos - "dependncy" finds "dependency" docs. - -**Flags:** -- `-n, --limit` - Max results (default: 5) -- `--exact` - Disable fuzzy matching -- `-v, --verbose` - Show relevance scores - -## Available Topics - -| Command | Purpose | -|---------|---------| -| `arc docs` | Overview of all topics | -| `arc docs workflows` | Step-by-step checklists | -| `arc docs dependencies` | Dependency types and when to use each | -| `arc docs boundaries` | When to use arc vs TodoWrite | -| `arc docs resumability` | Writing notes that survive compaction | -| `arc docs plugin` | Claude Code plugin installation | diff --git a/claude-plugin/commands/init.md b/claude-plugin/commands/init.md deleted file mode 100644 index 68661ae..0000000 --- a/claude-plugin/commands/init.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: Initialize arc in the current project -argument-hint: [project-name] ---- - -Initialize arc in the current directory. - -```bash -arc init # Use directory name as project -arc init my-project # Custom project name -arc init --prefix cxsh # Custom issue prefix (e.g., cxsh-0b7w) -arc init my-project -p cxsh # Both custom name and prefix -``` - -This command: -1. Creates a project on the arc server (or connects to existing) -2. Registers the current directory as a workspace path on the server -3. Saves project config to `~/.arc/projects/` -4. Creates AGENTS.md with workflow instructions - -**Flags:** -- `--prefix`, `-p`: Custom issue prefix basename (alphanumeric, max 10 chars). Gets normalized (lowercased, special chars stripped) and combined with a hash suffix for uniqueness. -- `--description`, `-d`: Project description -- `--quiet`, `-q`: Suppress output - -**Prerequisites:** -- Arc server must be running (`arc server start`) diff --git a/claude-plugin/commands/list.md b/claude-plugin/commands/list.md deleted file mode 100644 index 4516132..0000000 --- a/claude-plugin/commands/list.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: List issues with optional filters -argument-hint: [--status STATUS] [--type TYPE] [--query SEARCH] ---- - -List arc issues with optional filtering. - -**Common filters:** -- `--status open|in_progress|blocked|deferred|closed` -- `--type bug|feature|task|epic|chore` -- `--query "search text"` -- `--limit N` - -**Examples:** -```bash -arc list # All issues -arc list --status open # Open issues only -arc list --type bug # Bugs only -arc list --type epic # Epics only -arc list --query "auth" # Search for "auth" -``` - -**Working with epics:** -```bash -arc list --type epic # Find all epics -arc show <epic-id> # View epic and its children -``` - -Present results in a clear format showing ID, status, priority, type, and title. diff --git a/claude-plugin/commands/migrate-paths.md b/claude-plugin/commands/migrate-paths.md deleted file mode 100644 index a171f47..0000000 --- a/claude-plugin/commands/migrate-paths.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: Migrate legacy project configs to server-side workspace paths -argument-hint: [--dry-run] [--force] ---- - -Migrate legacy `~/.arc/projects/` configurations to server-side workspace path registrations. - -```bash -arc migrate-paths # Run migration -arc migrate-paths --dry-run # Preview without making changes -arc migrate-paths --force # Re-run even if already migrated -``` - -This is a one-time migration for users upgrading from older versions of arc that stored project-to-directory mappings only in local config files. After migration, the server handles path resolution, enabling multi-machine and container support. diff --git a/claude-plugin/commands/onboard.md b/claude-plugin/commands/onboard.md deleted file mode 100644 index 2b09b3e..0000000 --- a/claude-plugin/commands/onboard.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: Get oriented with the current project ---- - -Run `arc onboard` at the start of a work session to understand: - -- Current project and directory context -- Open issues and their priorities -- Blocked work and dependencies -- Recent activity - -This provides the context needed to decide what to work on. diff --git a/claude-plugin/commands/paths.md b/claude-plugin/commands/paths.md deleted file mode 100644 index bb5efeb..0000000 --- a/claude-plugin/commands/paths.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: Manage workspace path registrations for a project -argument-hint: [list|add|remove] [--all] ---- - -Manage filesystem paths associated with the current project. Paths link directories to projects for automatic project resolution. - -**List paths for current project:** -```bash -arc paths -arc paths list -``` - -**List paths across all projects:** -```bash -arc paths list --all -``` - -**Register a path:** -```bash -arc paths add <dir> -arc paths add <dir> --label "my laptop" --hostname myhost -``` - -**Unregister a path:** -```bash -arc paths remove <path-or-id> -``` - -**Flags for `add`:** -- `--label`: Human-readable label for the path -- `--hostname`: Override auto-detected hostname - -Paths are registered automatically by `arc init`. Use `arc paths add` to register additional directories (e.g., worktrees, secondary checkouts). diff --git a/claude-plugin/commands/prime.md b/claude-plugin/commands/prime.md deleted file mode 100644 index dd1c329..0000000 --- a/claude-plugin/commands/prime.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Output AI-optimized workflow context ---- - -Run `arc prime` to output workflow context for AI assistants. - -This is automatically run by SessionStart and PreCompact hooks. You typically don't need to run it manually. diff --git a/claude-plugin/commands/project.md b/claude-plugin/commands/project.md deleted file mode 100644 index 5ba0ad7..0000000 --- a/claude-plugin/commands/project.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -description: Manage projects -argument-hint: list|create|delete|rename|merge ---- - -Manage arc projects. - -**List projects:** -```bash -arc project list -``` - -**Create project:** -```bash -arc project create my-project -``` - -**Delete project:** -```bash -arc project delete <id> -``` - -**Rename project:** -```bash -arc project rename <new-name> -arc project rename --project <id> <new-name> -``` - -**Merge projects:** -```bash -arc project merge --into <target> <source> [sources...] -``` -Merges all issues and plans from source projects into the target, then deletes source projects. Projects can be specified by name or ID. - -Each directory typically has its own project. Use `arc init` in a project directory to create and configure a project automatically. Use `arc paths add` to register additional directories to an existing project. diff --git a/claude-plugin/commands/quickstart.md b/claude-plugin/commands/quickstart.md deleted file mode 100644 index 4795383..0000000 --- a/claude-plugin/commands/quickstart.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -description: Quick start guide for arc ---- - -Run `arc quickstart` to display a quick start guide covering: - -- Core concepts (projects, issues, dependencies) -- Basic workflow (find work, start, complete, create) -- Key commands reference -- Priority levels and issue types -- Tips for AI agents diff --git a/claude-plugin/commands/ready.md b/claude-plugin/commands/ready.md deleted file mode 100644 index 0d97f24..0000000 --- a/claude-plugin/commands/ready.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -description: Find ready-to-work tasks with no blockers ---- - -Run `arc ready` to find tasks that are ready to work on (no blocking dependencies). - -Present the results to the user showing: -- Issue ID -- Title -- Priority -- Issue type - -If there are ready tasks, ask the user which one they'd like to work on. If they choose one, run `arc update <id> --status in_progress` to claim it. - -If there are no ready tasks, suggest checking `arc blocked` or creating a new issue with `arc create`. diff --git a/claude-plugin/commands/self.md b/claude-plugin/commands/self.md deleted file mode 100644 index 7da696b..0000000 --- a/claude-plugin/commands/self.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: Manage the arc CLI itself (update, release channel) -argument-hint: update|channel ---- - -Self-management commands for the arc CLI. - -**Check for updates:** -```bash -arc self update --check -``` - -**Update to latest version:** -```bash -arc self update -arc self update --force # Force reinstall even if up-to-date -``` - -**View or switch release channel:** -```bash -arc self channel # Show current channel -arc self channel rc # Switch to release candidates -arc self channel nightly # Switch to nightly builds -arc self channel stable # Switch back to stable -arc self channel nightly -y # Switch without confirmation prompt -``` - -**Channels:** -- `stable` — Official releases (default) -- `rc` — Release candidates -- `nightly` — Daily builds from main branch - -Major/minor version updates automatically create a database backup before installing. diff --git a/claude-plugin/commands/server.md b/claude-plugin/commands/server.md deleted file mode 100644 index 9f25022..0000000 --- a/claude-plugin/commands/server.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -description: Manage the arc server daemon -argument-hint: start|stop|status|logs|restart ---- - -Manage the arc server with `arc server` subcommands. - -**Start server:** -```bash -arc server start # Start as daemon -arc server start --foreground # Run in foreground -arc server start --port 8080 # Custom port -``` - -**Other commands:** -```bash -arc server stop # Stop the server -arc server status # Check if running -arc server logs # View server logs -arc server logs -f # Follow logs -arc server restart # Restart the server -``` - -**Data location:** `~/.arc/` (data.db, server.log, server.pid, cli-config.json) diff --git a/claude-plugin/commands/show.md b/claude-plugin/commands/show.md deleted file mode 100644 index bebfe64..0000000 --- a/claude-plugin/commands/show.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -description: Show detailed information about an issue -argument-hint: <issue-id> ---- - -Show details for an arc issue. - -If the issue ID is missing, ask the user for it or suggest running `arc list` to find issues. - -Run `arc show <id>` to display: -- Issue ID, title, status -- Priority and type -- Description -- Dependencies (blocking/blocked by) -- Labels and comments - -**For epics:** The show command also displays child issues linked via parent-child dependencies, helping you see the full scope of work in an epic. diff --git a/claude-plugin/commands/stats.md b/claude-plugin/commands/stats.md deleted file mode 100644 index 97e0bea..0000000 --- a/claude-plugin/commands/stats.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: Show project statistics ---- - -Run `arc stats` to show statistics for the current project: - -- Total issues -- Open, in progress, blocked, deferred, closed counts -- Ready issues (unblocked) -- Average lead time - -This gives a quick overview of project health and progress. diff --git a/claude-plugin/commands/team.md b/claude-plugin/commands/team.md deleted file mode 100644 index 340a810..0000000 --- a/claude-plugin/commands/team.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: Agent team operations -argument-hint: context [epic-id] [--json] ---- - -Manage agent team operations with `arc team`. - -**Team context:** -```bash -arc team context # All teammate-labeled issues -arc team context <epic-id> # Children of specific epic -arc team context --json # JSON output for machine consumption -arc team context <epic-id> --json # JSON for a specific epic -``` - -**Output:** Issues grouped by their `teammate:*` labels (e.g., `teammate:frontend`, `teammate:backend`). - -| Column | Description | -|--------|-------------| -| ROLE | Teammate role extracted from `teammate:*` label | -| ISSUES | Count of issues assigned to that role | -| IDS | Issue IDs for that role | - -**JSON output** includes full issue details with plans and dependencies for each role group. - -**Related commands:** -- `arc prime --role=lead` — Team lead context output -- `arc prime --role=frontend` — Teammate-specific context (or use `ARC_TEAMMATE_ROLE` env var) diff --git a/claude-plugin/commands/update.md b/claude-plugin/commands/update.md deleted file mode 100644 index 2f7dac4..0000000 --- a/claude-plugin/commands/update.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: Update an issue's status, priority, or other fields -argument-hint: <issue-id> [--status STATUS] [--priority N] ---- - -Update an arc issue's fields. - -Available updates: -- `--status open|in_progress|blocked|deferred|closed` -- `--priority 0-4` -- `--title "new title"` -- `--description "text"` (use for resumability notes) -- `--type bug|feature|task|epic|chore` - -Examples: -```bash -arc update <id> --status in_progress # Start working -arc update <id> --priority 1 # Raise priority -``` - -**Update description via stdin (use --stdin flag):** -```bash -arc update <id> --stdin <<'EOF' -COMPLETED: X. IN PROGRESS: Y. NEXT: Z -EOF -``` - -If `--description` is also provided, it takes precedence over `--stdin`. - -If the issue ID is missing, ask for it or suggest `arc list` to find issues. diff --git a/claude-plugin/commands/which.md b/claude-plugin/commands/which.md deleted file mode 100644 index d40e12c..0000000 --- a/claude-plugin/commands/which.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: Show which project is active and how it was resolved ---- - -Run `arc which` to display the currently active project and its resolution source. - -Shows: -- The active project ID and name -- Where the project was resolved from (command line flag, local config, or server path match) -- The project config file path -- Any warnings about the configuration - -Useful for debugging project resolution issues when commands target the wrong project. diff --git a/claude-plugin/evals/README.md b/claude-plugin/evals/README.md deleted file mode 100644 index 1349682..0000000 --- a/claude-plugin/evals/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# Arc Plugin Eval Suite - -Trigger and quality evals for the arc Claude Code plugin. - -## Structure - -``` -evals/ - triggers/ - skills.json # Trigger evals for workflow skills (brainstorm, plan, implement, etc.) - commands.json # Trigger evals for slash commands (/arc:ready, /arc:create, etc.) - agents.json # Trigger evals for agent dispatch (issue-tracker, implementer, etc.) - quality/ - brainstorm.json # Quality evals for brainstorm skill output (5 evals) - plan.json # Quality evals for plan skill output (5 evals) - implement.json # Quality evals for implement skill output (9 evals) - debug.json # Quality evals for debug skill output (5 evals) - verify.json # Quality evals for verify skill output (5 evals) - review.json # Quality evals for review skill output (7 evals) - finish.json # Quality evals for finish skill output (6 evals) -``` - -## Running Evals - -### Via skill-creator (recommended) - -``` -/skill-creator Eval my arc brainstorm skill -/skill-creator Benchmark my arc skills across 5 runs -``` - -### Manual trigger eval - -Each trigger eval file contains queries with `should_trigger` booleans. -Pass rate = correct activations / total queries. - -**Target**: 90%+ pass rate on trigger evals, 80%+ on quality evals. - -## Writing Good Eval Queries - -- **Be concrete**: Include project names, issue IDs, file paths, error messages -- **Add backstory**: "I've been working on the auth module and just finished the JWT implementation" -- **Test boundaries**: Queries that are close to triggering but shouldn't (e.g., "plan my weekend" should NOT trigger the plan skill) -- **Mix positive/negative**: ~60% should_trigger=true, ~40% false -- **Avoid abstractions**: "Do the thing" is bad. "Create a bug for the login timeout we discussed" is good. diff --git a/claude-plugin/evals/quality/brainstorm.json b/claude-plugin/evals/quality/brainstorm.json deleted file mode 100644 index f06b829..0000000 --- a/claude-plugin/evals/quality/brainstorm.json +++ /dev/null @@ -1,112 +0,0 @@ -[ - { - "eval_id": 1, - "eval_name": "Brainstorm does NOT write code", - "prompt": "I want to add WebSocket support to our Go API server. Let's brainstorm the design.", - "assertions": [ - { - "id": 1, - "text": "Output does NOT contain implementation code (no .go files written, no Write/Edit tool calls for source code)", - "type": "constraint" - }, - { - "id": 2, - "text": "Output asks at least one clarifying question before proposing approaches", - "type": "quality" - }, - { - "id": 3, - "text": "Output proposes 2-3 approaches with trade-offs for each", - "type": "quality" - } - ] - }, - { - "eval_id": 2, - "eval_name": "Brainstorm asks questions one at a time", - "prompt": "We need to redesign the permission system. The current one is too simple — just admin/user roles. We need something more granular.", - "assertions": [ - { - "id": 1, - "text": "First response asks ONE clarifying question, not a list of 5+", - "type": "quality" - }, - { - "id": 2, - "text": "Question is asked using AskUserQuestion tool with structured options when applicable", - "type": "quality" - } - ] - }, - { - "eval_id": 3, - "eval_name": "Brainstorm saves design to arc", - "prompt": "I want to add a plugin system to arc. [After several rounds of Q&A, user approves the design.] Let's save this and move to planning.", - "assertions": [ - { - "id": 1, - "text": "Output writes the design to docs/plans/ and registers with `arc plan create`", - "type": "quality" - }, - { - "id": 2, - "text": "Output presents the plan for review with approve/review options", - "type": "quality" - }, - { - "id": 3, - "text": "Output suggests transitioning to the plan skill as next step", - "type": "quality" - } - ] - }, - { - "eval_id": 4, - "eval_name": "Brainstorm applies YAGNI", - "prompt": "Add a simple health check endpoint to the API. Just GET /healthz returning 200.", - "assertions": [ - { - "id": 1, - "text": "Output recognizes this is small/obvious work and suggests skipping brainstorm or going directly to implement", - "type": "quality" - }, - { - "id": 2, - "text": "Output does NOT propose elaborate monitoring frameworks or complex health check systems for a simple endpoint", - "type": "constraint" - } - ] - }, - { - "eval_id": 5, - "eval_name": "Brainstorm identifies shared contracts for parallel readiness", - "prompt": "Design a notification system with email, Slack, and webhook channels. Each channel will be implemented by a different agent in parallel.", - "assertions": [ - { - "id": 1, - "text": "Output identifies shared contracts (e.g., Notifier interface, NotificationPayload type) that multiple channels reference", - "type": "quality" - }, - { - "id": 2, - "text": "Output presents shared contracts as a 'foundation layer' to be implemented before parallel work", - "type": "quality" - }, - { - "id": 3, - "text": "Shared contracts include exact, copy-pasteable code blocks with type definitions (e.g., Go structs with field names and types), not just descriptive text like 'Notifier interface in notifier.go'", - "type": "quality" - }, - { - "id": 4, - "text": "Shared contracts include contract test assertions (e.g., compile-time type checks like `var _ int64 = n.ID`) alongside the type definitions", - "type": "quality" - }, - { - "id": 5, - "text": "Task-internal types are presented as typed pseudocode (e.g., `EmailConfig { smtp_host: String, port: u16 }`) separate from the exact shared contracts", - "type": "quality" - } - ] - } -] diff --git a/claude-plugin/evals/quality/debug.json b/claude-plugin/evals/quality/debug.json deleted file mode 100644 index f49c92c..0000000 --- a/claude-plugin/evals/quality/debug.json +++ /dev/null @@ -1,107 +0,0 @@ -[ - { - "eval_id": 1, - "eval_name": "Debug investigates before fixing", - "prompt": "Tests are failing: TestCreateIssue panics with nil pointer at internal/storage/sqlite/issues.go:42. Fix it.", - "assertions": [ - { - "id": 1, - "text": "Output reads the error message and stack trace before proposing any fix", - "type": "quality" - }, - { - "id": 2, - "text": "Output reads the code at the referenced file and line number", - "type": "quality" - }, - { - "id": 3, - "text": "Output does NOT write a fix in the first response — Phase 1 is investigation only", - "type": "constraint" - }, - { - "id": 4, - "text": "Output checks recent changes (git diff or git log) for context", - "type": "quality" - } - ] - }, - { - "eval_id": 2, - "eval_name": "Debug writes failing test before fix", - "prompt": "After investigating, the root cause is that GetProject returns nil when the project doesn't exist instead of an error. Fix it.", - "assertions": [ - { - "id": 1, - "text": "Output writes a failing test that demonstrates the bug BEFORE writing the fix", - "type": "quality" - }, - { - "id": 2, - "text": "Output runs the test and confirms it fails with the expected behavior", - "type": "quality" - }, - { - "id": 3, - "text": "After the fix, output runs the full test suite to check for regressions", - "type": "quality" - } - ] - }, - { - "eval_id": 3, - "eval_name": "Debug applies the 3-fix rule", - "prompt": "I've already tried 3 different fixes for this intermittent race condition and none worked. The test still fails randomly.", - "assertions": [ - { - "id": 1, - "text": "Output recognizes the 3-fix threshold and stops trying new fixes", - "type": "quality" - }, - { - "id": 2, - "text": "Output goes back to investigation (Phase 1) to gather more evidence", - "type": "quality" - }, - { - "id": 3, - "text": "Output does NOT propose a 4th fix without deeper investigation first", - "type": "constraint" - } - ] - }, - { - "eval_id": 4, - "eval_name": "Debug creates arc issue for larger bugs", - "prompt": "While debugging the nil pointer, I discovered that the entire error handling pattern in the storage layer is inconsistent — some functions return nil, others return sentinel errors.", - "assertions": [ - { - "id": 1, - "text": "Output creates an arc issue for the larger pattern problem (arc create ... --type=bug)", - "type": "quality" - }, - { - "id": 2, - "text": "Output decides whether to fix it now (if it blocks current work) or defer it", - "type": "quality" - } - ] - }, - { - "eval_id": 5, - "eval_name": "Debug tests one hypothesis at a time", - "prompt": "The API returns 500 on /users. Possible causes: database connection pool exhausted, query timeout, or missing index on users table.", - "assertions": [ - { - "id": 1, - "text": "Output forms a SINGLE hypothesis and designs a test for it", - "type": "quality" - }, - { - "id": 2, - "text": "Output does NOT try multiple fixes simultaneously", - "type": "constraint" - } - ] - } -] diff --git a/claude-plugin/evals/quality/finish.json b/claude-plugin/evals/quality/finish.json deleted file mode 100644 index 9c2e1ac..0000000 --- a/claude-plugin/evals/quality/finish.json +++ /dev/null @@ -1,124 +0,0 @@ -[ - { - "eval_id": 1, - "eval_name": "Finish runs quality gates before committing", - "prompt": "We're done for today. I made code changes to internal/api/server.go and added a new test file. Let's wrap up.", - "assertions": [ - { - "id": 1, - "text": "Output runs the test suite (make test) BEFORE attempting git commit", - "type": "quality" - }, - { - "id": 2, - "text": "Output runs the build (make build) to verify compilation", - "type": "quality" - }, - { - "id": 3, - "text": "Output does NOT skip Phase 2 quality gates since code was changed", - "type": "constraint" - } - ] - }, - { - "eval_id": 2, - "eval_name": "Finish captures remaining work as arc issues", - "prompt": "We finished ARC-5.1 and ARC-5.2 but didn't get to ARC-5.3. We also discovered a bug in the token refresh logic that needs separate work.", - "assertions": [ - { - "id": 1, - "text": "Output creates an arc issue for the discovered token refresh bug", - "type": "quality" - }, - { - "id": 2, - "text": "Output updates ARC-5.3 with progress context for the next session", - "type": "quality" - }, - { - "id": 3, - "text": "Output closes ARC-5.1 and ARC-5.2 with resolution summaries", - "type": "quality" - } - ] - }, - { - "eval_id": 3, - "eval_name": "Finish stages specific files, not git add -A", - "prompt": "Time to commit. We changed 4 files in internal/api/ and added a new test file.", - "assertions": [ - { - "id": 1, - "text": "Output stages files by specific name (git add <file1> <file2> ...) NOT git add -A or git add .", - "type": "constraint" - }, - { - "id": 2, - "text": "Output uses a conventional commit message format (feat/fix/refactor scope prefix)", - "type": "quality" - } - ] - }, - { - "eval_id": 4, - "eval_name": "Finish pushes to remote — work is not done until pushed", - "prompt": "I've committed the changes. Are we done?", - "assertions": [ - { - "id": 1, - "text": "Output runs git push (not just commit)", - "type": "quality" - }, - { - "id": 2, - "text": "Output verifies push succeeded with git status", - "type": "quality" - }, - { - "id": 3, - "text": "Output does NOT declare session complete before push succeeds", - "type": "constraint" - } - ] - }, - { - "eval_id": 5, - "eval_name": "Finish blocks on test failure — does not skip to commit", - "prompt": "Running the test suite before wrapping up. Result: 2 tests failed in TestOAuthCallback.", - "assertions": [ - { - "id": 1, - "text": "Output does NOT proceed to git commit while tests are failing", - "type": "constraint" - }, - { - "id": 2, - "text": "Output invokes debug or implement skill to fix the failures", - "type": "quality" - }, - { - "id": 3, - "text": "Output re-runs tests after the fix before proceeding to commit", - "type": "quality" - } - ] - }, - { - "eval_id": 6, - "eval_name": "Finish skips quality gates when no code changed", - "prompt": "This session was all issue triage and planning — no code changes. Let's wrap up.", - "assertions": [ - { - "id": 1, - "text": "Output skips Phase 2 quality gates (no make test, no make build) since no code was changed", - "type": "quality" - }, - { - "id": 2, - "text": "Output still updates arc issues and captures any remaining work", - "type": "quality" - } - ] - } -] diff --git a/claude-plugin/evals/quality/implement.json b/claude-plugin/evals/quality/implement.json deleted file mode 100644 index fdb6064..0000000 --- a/claude-plugin/evals/quality/implement.json +++ /dev/null @@ -1,200 +0,0 @@ -[ - { - "eval_id": 1, - "eval_name": "Implement dispatches subagent — never writes code itself", - "prompt": "Implement the tasks from epic ARC-5. Start with ARC-5.1 (JWT token generation).", - "assertions": [ - { - "id": 1, - "text": "Output dispatches an arc-implementer subagent via Agent tool", - "type": "quality" - }, - { - "id": 2, - "text": "Output does NOT write implementation code directly (no Write/Edit tool calls for .go/.ts files)", - "type": "constraint" - }, - { - "id": 3, - "text": "Subagent dispatch prompt includes the task spec from `arc show`", - "type": "quality" - }, - { - "id": 4, - "text": "Subagent dispatch prompt includes the project test command", - "type": "quality" - } - ] - }, - { - "eval_id": 2, - "eval_name": "Implement claims task before dispatching", - "prompt": "Start implementing the next ready task.", - "assertions": [ - { - "id": 1, - "text": "Output runs `arc ready` to find next task", - "type": "quality" - }, - { - "id": 2, - "text": "Output runs `arc update <id> --status in_progress` before dispatching subagent", - "type": "quality" - }, - { - "id": 3, - "text": "Output records PRE_TASK_SHA before dispatching", - "type": "quality" - } - ] - }, - { - "eval_id": 3, - "eval_name": "Implement verifies result and dispatches mandatory review", - "prompt": "The arc-implementer just reported back with PASS on all gate checks for ARC-5.1. This task is a child of epic ARC-5.", - "assertions": [ - { - "id": 1, - "text": "Output runs the project test command fresh (does NOT trust subagent report alone)", - "type": "quality" - }, - { - "id": 2, - "text": "Output dispatches the review skill after tests pass (review is mandatory, not optional)", - "type": "quality" - }, - { - "id": 3, - "text": "Output closes the task with `arc close` only after both independent test verification AND review pass", - "type": "quality" - } - ] - }, - { - "eval_id": 4, - "eval_name": "Implement handles PARTIAL result correctly", - "prompt": "The arc-implementer reported PARTIAL. Gate: Unresolved — spec compliance missed step 3 (error handling for invalid tokens). Test coverage missing edge case for expired tokens.", - "assertions": [ - { - "id": 1, - "text": "Output does NOT close the task", - "type": "constraint" - }, - { - "id": 2, - "text": "Output re-dispatches arc-implementer with the specific gate feedback included in the prompt", - "type": "quality" - }, - { - "id": 3, - "text": "Re-dispatch prompt includes the original task spec AND the previous gate feedback", - "type": "quality" - } - ] - }, - { - "eval_id": 5, - "eval_name": "Implement routes docs-only tasks to doc-writer", - "prompt": "The next ready task ARC-5.4 has a docs-only label. It's about updating the API documentation.", - "assertions": [ - { - "id": 1, - "text": "Output checks for the docs-only label (via arc show --json + jq or similar)", - "type": "quality" - }, - { - "id": 2, - "text": "Output dispatches arc-doc-writer subagent (NOT arc-implementer)", - "type": "quality" - } - ] - }, - { - "eval_id": 6, - "eval_name": "Implement parallel dispatch uses worktree isolation", - "prompt": "Tasks ARC-5.2, ARC-5.3, and ARC-5.4 are independent with no shared files. Dispatch them in parallel.", - "assertions": [ - { - "id": 1, - "text": "Output commits and pushes all sequential work before parallel dispatch", - "type": "quality" - }, - { - "id": 2, - "text": "Output records PARALLEL_BASE SHA before dispatching", - "type": "quality" - }, - { - "id": 3, - "text": "All parallel Agent calls use isolation: 'worktree'", - "type": "quality" - }, - { - "id": 4, - "text": "All parallel Agent calls are in a single message (not spread across multiple turns)", - "type": "constraint" - }, - { - "id": 5, - "text": "After agents complete, output verifies commit history against PARALLEL_BASE", - "type": "quality" - } - ] - }, - { - "eval_id": 7, - "eval_name": "Implement runs integration checkpoint after 2-3 tasks", - "prompt": "We just closed ARC-5.1 and ARC-5.2. ARC-5.3 is next.", - "assertions": [ - { - "id": 1, - "text": "Output runs integration tests (make test-integration or equivalent) before starting ARC-5.3", - "type": "quality" - } - ] - }, - { - "eval_id": 8, - "eval_name": "Implement handles deviation from review — fix path", - "prompt": "The review skill reported a Deviation (fix) for ARC-5.1: the implementer used string IDs but the design specifies int64. The reviewer recommends fixing to match the design.", - "assertions": [ - { - "id": 1, - "text": "Output re-dispatches arc-implementer with explicit instruction to change string IDs to int64", - "type": "quality" - }, - { - "id": 2, - "text": "Output does NOT close the task until the deviation is resolved", - "type": "constraint" - }, - { - "id": 3, - "text": "Output re-dispatches review after the fix to confirm the deviation is resolved", - "type": "quality" - } - ] - }, - { - "eval_id": 9, - "eval_name": "Implement handles deviation from review — accept path", - "prompt": "The review skill reported a Deviation (accept) for ARC-5.3: the implementer used a custom error type instead of the plain error return specified in the design. The reviewer says the deviation aligns with existing codebase conventions.", - "assertions": [ - { - "id": 1, - "text": "Output accepts the deviation rather than forcing a fix", - "type": "quality" - }, - { - "id": 2, - "text": "Output logs the accepted deviation as an arc comment on the task with description and rationale", - "type": "quality" - }, - { - "id": 3, - "text": "Output proceeds to close the task (does not re-dispatch for accepted deviations)", - "type": "quality" - } - ] - } -] diff --git a/claude-plugin/evals/quality/plan.json b/claude-plugin/evals/quality/plan.json deleted file mode 100644 index 334e30b..0000000 --- a/claude-plugin/evals/quality/plan.json +++ /dev/null @@ -1,137 +0,0 @@ -[ - { - "eval_id": 1, - "eval_name": "Plan creates self-contained task descriptions", - "prompt": "Break epic ARC-5 (Auth System) into implementation tasks. The design includes JWT tokens, OAuth, and session management.", - "assertions": [ - { - "id": 1, - "text": "Each task description includes a ## Files section with exact file paths", - "type": "quality" - }, - { - "id": 2, - "text": "Each task description includes a ## Steps section with numbered, concrete steps", - "type": "quality" - }, - { - "id": 3, - "text": "Each task description includes a ## Test Command section", - "type": "quality" - }, - { - "id": 4, - "text": "Each task description includes a ## Expected Outcome section", - "type": "quality" - }, - { - "id": 5, - "text": "Each task description includes a ## Scope Boundary section", - "type": "quality" - }, - { - "id": 6, - "text": "Each non-T0 task description includes a ## Design Contracts section with shared types (verbatim code) and task-internal types (pseudocode)", - "type": "quality" - } - ] - }, - { - "eval_id": 2, - "eval_name": "Plan delegates to arc-issue-tracker agent", - "prompt": "Create the implementation tasks for the notification system epic ARC-7. There are 6 tasks with dependencies.", - "assertions": [ - { - "id": 1, - "text": "Output dispatches arc-issue-tracker agent via Agent tool (does NOT run arc create directly)", - "type": "constraint" - }, - { - "id": 2, - "text": "Agent dispatch includes a ## Tasks section with task descriptions", - "type": "quality" - }, - { - "id": 3, - "text": "Agent dispatch includes a ## Dependencies section mapping task relationships", - "type": "quality" - }, - { - "id": 4, - "text": "Agent dispatch includes a ## Required Output section requesting a summary table", - "type": "quality" - } - ] - }, - { - "eval_id": 3, - "eval_name": "Plan enforces file ownership — no overlapping parallel tasks", - "prompt": "Break this feature into tasks that can run in parallel. Task A modifies internal/api/server.go and Task B also needs to modify internal/api/server.go.", - "assertions": [ - { - "id": 1, - "text": "Output identifies the file overlap conflict between tasks", - "type": "quality" - }, - { - "id": 2, - "text": "Output resolves the overlap by merging tasks, adding a dependency, or extracting shared changes into a foundation task", - "type": "quality" - }, - { - "id": 3, - "text": "No two parallelizable tasks in the final plan own the same file", - "type": "constraint" - } - ] - }, - { - "eval_id": 4, - "eval_name": "Plan creates foundation task with contract tests", - "prompt": "Create tasks for the notification system. The design identified shared contracts: Notifier interface with Send(payload NotificationPayload) error method, NotificationPayload struct with ID int64, Channel string, Message string, CreatedAt time.Time fields, and config key notification.retry_count. Tasks for email, Slack, and webhook channels will run in parallel.", - "assertions": [ - { - "id": 1, - "text": "Output creates a T0 foundation task that establishes all shared contracts before parallel work", - "type": "quality" - }, - { - "id": 2, - "text": "Parallel channel tasks (email, Slack, webhook) are marked as blocked by the foundation task", - "type": "quality" - }, - { - "id": 3, - "text": "T0 task Steps contain literal 'write this exact code' instructions with copy-pasteable type definitions, not prose like 'create the Notifier interface'", - "type": "quality" - }, - { - "id": 4, - "text": "T0 task Steps include inline contract test assertions (e.g., TestNotificationPayloadContract with compile-time field type checks) to write in test files", - "type": "quality" - }, - { - "id": 5, - "text": "T0 task Steps include a build/test verification step to confirm contract tests pass before committing", - "type": "quality" - } - ] - }, - { - "eval_id": 5, - "eval_name": "Plan validates returned agent results", - "prompt": "The arc-issue-tracker agent returned 4 task IDs but we sent 5 tasks. Handle this.", - "assertions": [ - { - "id": 1, - "text": "Output identifies the count mismatch (4 returned vs 5 sent)", - "type": "quality" - }, - { - "id": 2, - "text": "Output re-dispatches the agent for the missing task or creates it manually", - "type": "quality" - } - ] - } -] diff --git a/claude-plugin/evals/quality/review.json b/claude-plugin/evals/quality/review.json deleted file mode 100644 index e0d9bbb..0000000 --- a/claude-plugin/evals/quality/review.json +++ /dev/null @@ -1,171 +0,0 @@ -[ - { - "eval_id": 1, - "eval_name": "Review dispatches arc-reviewer with correct context including design spec", - "prompt": "Review the implementation of ARC-5.2 (OAuth integration). PRE_TASK_SHA is abc1234. This task is a child of epic ARC-5.", - "assertions": [ - { - "id": 1, - "text": "Output dispatches arc-reviewer subagent via Agent tool", - "type": "quality" - }, - { - "id": 2, - "text": "Dispatch prompt includes the task spec (from arc show)", - "type": "quality" - }, - { - "id": 3, - "text": "Dispatch prompt includes the git diff range (PRE_TASK_SHA..HEAD)", - "type": "quality" - }, - { - "id": 4, - "text": "Output does NOT write code changes itself — review skill is read-only", - "type": "constraint" - }, - { - "id": 5, - "text": "Output retrieves the parent epic's design context (via arc show on the parent) before dispatching", - "type": "quality" - }, - { - "id": 6, - "text": "Dispatch prompt includes a ## Design Spec section with the design excerpt relevant to this task", - "type": "quality" - } - ] - }, - { - "eval_id": 2, - "eval_name": "Review triages findings by severity correctly", - "prompt": "The arc-reviewer found: Critical — SQL injection in query builder. Important — missing error handling for network timeouts. Minor — inconsistent variable naming in test helpers.", - "assertions": [ - { - "id": 1, - "text": "Output re-dispatches arc-implementer for the Critical SQL injection fix immediately", - "type": "quality" - }, - { - "id": 2, - "text": "Output plans to fix the Important finding before moving to the next task", - "type": "quality" - }, - { - "id": 3, - "text": "Output notes the Minor finding in an arc issue comment for later, does not block on it", - "type": "quality" - } - ] - }, - { - "eval_id": 3, - "eval_name": "Review applies circuit breaker after 3 cycles", - "prompt": "This is the 3rd review/fix cycle for ARC-5.2. The reviewer keeps flagging the same error handling pattern as Critical, but the implementer keeps writing it the same way.", - "assertions": [ - { - "id": 1, - "text": "Output recognizes the 3-cycle circuit breaker threshold", - "type": "quality" - }, - { - "id": 2, - "text": "Output STOPS the review/fix loop and escalates to the user", - "type": "quality" - }, - { - "id": 3, - "text": "Output does NOT dispatch a 4th review/fix cycle without user guidance", - "type": "constraint" - }, - { - "id": 4, - "text": "Output provides a summary of the recurring disagreement to help the user decide", - "type": "quality" - } - ] - }, - { - "eval_id": 4, - "eval_name": "Review evaluates findings technically, not performatively", - "prompt": "The arc-reviewer flagged: Critical — 'The function GetUser should return (User, error) not (*User, error) because User is small enough to copy.' But the codebase consistently uses pointer returns for all storage methods.", - "assertions": [ - { - "id": 1, - "text": "Output evaluates the finding against codebase conventions rather than blindly accepting it", - "type": "quality" - }, - { - "id": 2, - "text": "Output explains why the reviewer's suggestion conflicts with established patterns", - "type": "quality" - }, - { - "id": 3, - "text": "Output does NOT automatically dispatch implementer for a finding that contradicts project conventions", - "type": "constraint" - } - ] - }, - { - "eval_id": 5, - "eval_name": "Review re-reviews after fixes are applied", - "prompt": "The arc-implementer just fixed the Critical SQL injection finding from the review. What's next?", - "assertions": [ - { - "id": 1, - "text": "Output re-dispatches arc-reviewer with updated SHAs to verify the fix", - "type": "quality" - }, - { - "id": 2, - "text": "Output does NOT skip re-review and assume the fix is correct", - "type": "constraint" - } - ] - }, - { - "eval_id": 6, - "eval_name": "Review handles deviation-fix recommendation", - "prompt": "The arc-reviewer reported: Plan Adherence — DEVIATION: The design specifies MemoryID as int64 but the implementation uses string. RATIONALE: Subagent may have followed common API patterns where IDs are strings. RECOMMENDATION: fix.", - "assertions": [ - { - "id": 1, - "text": "Output re-dispatches arc-implementer with the specific deviation to correct (change string to int64)", - "type": "quality" - }, - { - "id": 2, - "text": "Output does NOT accept the string type despite it being a common pattern — the design spec takes precedence", - "type": "constraint" - }, - { - "id": 3, - "text": "Re-dispatch prompt includes the original task spec AND the specific deviation finding to fix", - "type": "quality" - } - ] - }, - { - "eval_id": 7, - "eval_name": "Review handles deviation-accept recommendation", - "prompt": "The arc-reviewer reported: Plan Adherence — DEVIATION: The design specifies HandleError returns (error) but implementation returns (*AppError, error) which provides structured error context. RATIONALE: The codebase already uses *AppError throughout the API layer. RECOMMENDATION: accept — aligns with existing codebase conventions and provides richer error context.", - "assertions": [ - { - "id": 1, - "text": "Output evaluates the deviation rationale against codebase conventions rather than blindly enforcing the plan", - "type": "quality" - }, - { - "id": 2, - "text": "Output accepts the deviation and logs it as an arc comment on the task for traceability", - "type": "quality" - }, - { - "id": 3, - "text": "Output does NOT re-dispatch the implementer to revert a deviation that aligns with existing conventions", - "type": "constraint" - } - ] - } -] diff --git a/claude-plugin/evals/quality/verify.json b/claude-plugin/evals/quality/verify.json deleted file mode 100644 index 7e8ff55..0000000 --- a/claude-plugin/evals/quality/verify.json +++ /dev/null @@ -1,102 +0,0 @@ -[ - { - "eval_id": 1, - "eval_name": "Verify runs proof command before any completion claim", - "prompt": "Tests pass for the auth middleware implementation. Let's close ARC-5.1.", - "assertions": [ - { - "id": 1, - "text": "Output runs the project test command (make test or go test ./...) BEFORE claiming completion", - "type": "quality" - }, - { - "id": 2, - "text": "Output reads the FULL test output, not just the last line or exit code", - "type": "quality" - }, - { - "id": 3, - "text": "Output does NOT run `arc close` before the proof command succeeds", - "type": "constraint" - } - ] - }, - { - "eval_id": 2, - "eval_name": "Verify rejects cached or remembered results", - "prompt": "I already ran the tests 10 minutes ago and they passed. Just close the issue.", - "assertions": [ - { - "id": 1, - "text": "Output does NOT accept the cached result — insists on running tests fresh", - "type": "constraint" - }, - { - "id": 2, - "text": "Output runs the full test suite now, not a subset", - "type": "quality" - } - ] - }, - { - "eval_id": 3, - "eval_name": "Verify cites evidence in completion claim", - "prompt": "The test suite just ran. Here's the output: 47 passed, 0 failed, 0 skipped. Exit code 0.", - "assertions": [ - { - "id": 1, - "text": "Output references specific numbers from the test output (e.g., '47 passed, 0 failed')", - "type": "quality" - }, - { - "id": 2, - "text": "Output checks for skipped tests and warnings, not just pass/fail count", - "type": "quality" - }, - { - "id": 3, - "text": "Output proceeds to `arc close` with a resolution message that includes evidence", - "type": "quality" - } - ] - }, - { - "eval_id": 4, - "eval_name": "Verify handles test failure correctly", - "prompt": "The test suite ran: 45 passed, 2 failed. The failures are in TestSessionExpiry and TestTokenRefresh.", - "assertions": [ - { - "id": 1, - "text": "Output does NOT close the arc issue", - "type": "constraint" - }, - { - "id": 2, - "text": "Output does NOT claim completion despite 45 tests passing", - "type": "constraint" - }, - { - "id": 3, - "text": "Output suggests returning to implement or debug skill to fix the failures", - "type": "quality" - } - ] - }, - { - "eval_id": 5, - "eval_name": "Verify does not trust subagent report alone", - "prompt": "The arc-implementer subagent reported all tests pass. Should we close ARC-5.3?", - "assertions": [ - { - "id": 1, - "text": "Output runs the test command independently rather than trusting the subagent report", - "type": "quality" - }, - { - "id": 2, - "text": "Output explains why independent verification is needed (subagent could have stale results)", - "type": "quality" - } - ] - } -] diff --git a/claude-plugin/evals/triggers/agents.json b/claude-plugin/evals/triggers/agents.json deleted file mode 100644 index 52e51ac..0000000 --- a/claude-plugin/evals/triggers/agents.json +++ /dev/null @@ -1,117 +0,0 @@ -[ - { - "_comment": "=== ARC-ISSUE-TRACKER AGENT ===", - "_target": "arc:arc-issue-tracker" - }, - { - "query": "Create an epic called 'Auth System' with 5 child tasks for login, registration, password reset, session management, and OAuth. Set up dependencies between them.", - "should_trigger": true, - "target_agent": "arc:arc-issue-tracker", - "note": "Bulk issue creation with dependencies — classic issue-tracker dispatch" - }, - { - "query": "Close all the completed tasks under epic ARC-5: ARC-5.1, ARC-5.2, ARC-5.3, and ARC-5.4.", - "should_trigger": true, - "target_agent": "arc:arc-issue-tracker", - "note": "Batch close operation" - }, - { - "query": "Triage these 10 open issues — set priorities based on the descriptions and mark the UI polish ones as backlog.", - "should_trigger": true, - "target_agent": "arc:arc-issue-tracker", - "note": "Bulk triage operation" - }, - { - "query": "Create the tasks from the plan we just designed. Here's the task manifest with 8 tasks and their dependencies.", - "should_trigger": true, - "target_agent": "arc:arc-issue-tracker", - "note": "Task manifest processing from plan skill" - }, - { - "query": "Create a single bug for the login timeout issue", - "should_trigger": false, - "target_agent": "arc:arc-issue-tracker", - "note": "Single issue creation — use /arc:create directly, no agent needed" - }, - { - "query": "Show me the details of issue ARC-5.1", - "should_trigger": false, - "target_agent": "arc:arc-issue-tracker", - "note": "Single show — use /arc:show directly" - }, - - { - "_comment": "=== ARC-IMPLEMENTER AGENT ===", - "_target": "arc:arc-implementer" - }, - { - "query": "Implement task ARC-5.1 using TDD. Here's the task spec: [task details]. Test command: make test.", - "should_trigger": true, - "target_agent": "arc:arc-implementer", - "note": "Direct implementer dispatch with task spec — typically from implement skill" - }, - { - "query": "Continue implementing ARC-5.2. The previous attempt had gate failures: spec compliance missed step 3 and no test for error handling.", - "should_trigger": true, - "target_agent": "arc:arc-implementer", - "note": "Re-dispatch after PARTIAL result with gate feedback" - }, - { - "query": "Review the code changes in the last commit", - "should_trigger": false, - "target_agent": "arc:arc-implementer", - "note": "Code review — should dispatch arc-reviewer, not implementer" - }, - { - "query": "Write documentation for the new API endpoints", - "should_trigger": false, - "target_agent": "arc:arc-implementer", - "note": "Docs-only task — should dispatch arc-doc-writer" - }, - - { - "_comment": "=== ARC-REVIEWER AGENT ===", - "_target": "arc:arc-reviewer" - }, - { - "query": "Review the diff from commit abc123 to HEAD against the spec for task ARC-5.2. Check for critical issues, code quality, and test coverage.", - "should_trigger": true, - "target_agent": "arc:arc-reviewer", - "note": "Post-implementation review dispatch" - }, - { - "query": "Do a code review of the changes the implementer just made for the session middleware task.", - "should_trigger": true, - "target_agent": "arc:arc-reviewer", - "note": "Review after implementer completes" - }, - { - "query": "Implement the fix that the reviewer identified in finding #2", - "should_trigger": false, - "target_agent": "arc:arc-reviewer", - "note": "Implementation request — should dispatch implementer, not reviewer" - }, - - { - "_comment": "=== ARC-DOC-WRITER AGENT ===", - "_target": "arc:arc-doc-writer" - }, - { - "query": "Write the API documentation for the new endpoints. This is a docs-only task — no code changes needed.", - "should_trigger": true, - "target_agent": "arc:arc-doc-writer", - "note": "Documentation-only task" - }, - { - "query": "Update CHANGELOG.md and README.md with the new features from this release.", - "should_trigger": true, - "target_agent": "arc:arc-doc-writer", - "note": "Pure documentation update" - }, - { - "query": "Add unit tests for the new validation functions", - "should_trigger": false, - "target_agent": "arc:arc-doc-writer", - "note": "Code task, not docs — should dispatch implementer" - } -] diff --git a/claude-plugin/evals/triggers/commands.json b/claude-plugin/evals/triggers/commands.json deleted file mode 100644 index b3d581b..0000000 --- a/claude-plugin/evals/triggers/commands.json +++ /dev/null @@ -1,293 +0,0 @@ -[ - { - "_comment": "=== /arc:ready ===", - "_target": "/arc:ready" - }, - { - "query": "What work is available? Show me unblocked tasks.", - "should_trigger": true, - "target_command": "arc:ready", - "note": "Looking for available work" - }, - { - "query": "What should I work on next?", - "should_trigger": true, - "target_command": "arc:ready", - "note": "Implicit ready check" - }, - { - "query": "Are there any tasks ready to pick up?", - "should_trigger": true, - "target_command": "arc:ready", - "note": "Explicit ready query" - }, - - { - "_comment": "=== /arc:create ===", - "_target": "/arc:create" - }, - { - "query": "Create a bug for the intermittent 500 errors on /api/users", - "should_trigger": true, - "target_command": "arc:create", - "note": "Explicit issue creation with type" - }, - { - "query": "I found a security issue in the auth middleware. Track it as a high priority bug.", - "should_trigger": true, - "target_command": "arc:create", - "note": "Issue creation with priority context" - }, - { - "query": "Make an epic for the database migration project with subtasks", - "should_trigger": true, - "target_command": "arc:create", - "note": "Epic creation request" - }, - { - "query": "Create a new React component for the sidebar", - "should_trigger": false, - "target_command": "arc:create", - "note": "'Create' refers to code, not arc issues" - }, - { - "query": "Create a new git branch for the feature", - "should_trigger": false, - "target_command": "arc:create", - "note": "Git branch creation, not issue creation" - }, - - { - "_comment": "=== /arc:show ===", - "_target": "/arc:show" - }, - { - "query": "Show me the details of ARC-5.2", - "should_trigger": true, - "target_command": "arc:show", - "note": "Explicit issue detail request with ID" - }, - { - "query": "What's the status of the auth epic?", - "should_trigger": true, - "target_command": "arc:show", - "note": "Status check on specific work" - }, - - { - "_comment": "=== /arc:update ===", - "_target": "/arc:update" - }, - { - "query": "Mark ARC-5.1 as in progress — I'm starting work on it now.", - "should_trigger": true, - "target_command": "arc:update", - "note": "Status update request" - }, - { - "query": "Change the priority of the login bug to critical", - "should_trigger": true, - "target_command": "arc:update", - "note": "Priority update" - }, - { - "query": "Assign the database migration task to alice", - "should_trigger": true, - "target_command": "arc:update", - "note": "Assignee update" - }, - - { - "_comment": "=== /arc:close ===", - "_target": "/arc:close" - }, - { - "query": "Close ARC-5.1 — the JWT implementation is done and tests pass.", - "should_trigger": true, - "target_command": "arc:close", - "note": "Explicit close with reason" - }, - { - "query": "Mark issues ARC-5.1, ARC-5.2, and ARC-5.3 as complete.", - "should_trigger": true, - "target_command": "arc:close", - "note": "Batch close request" - }, - { - "query": "Close the browser tab with the documentation", - "should_trigger": false, - "target_command": "arc:close", - "note": "'Close' refers to browser, not arc issues" - }, - - { - "_comment": "=== /arc:blocked ===", - "_target": "/arc:blocked" - }, - { - "query": "What's blocking progress? Show me stuck issues.", - "should_trigger": true, - "target_command": "arc:blocked", - "note": "Blocked work query" - }, - { - "query": "Why can't I start the API endpoint task?", - "should_trigger": true, - "target_command": "arc:blocked", - "note": "Implicit blocked check — something is preventing work" - }, - - { - "_comment": "=== /arc:list ===", - "_target": "/arc:list" - }, - { - "query": "Show me all open bugs in the project", - "should_trigger": true, - "target_command": "arc:list", - "note": "Filtered list request" - }, - { - "query": "List all the epics we have", - "should_trigger": true, - "target_command": "arc:list", - "note": "Type-filtered list" - }, - { - "query": "What issues are assigned to me?", - "should_trigger": true, - "target_command": "arc:list", - "note": "Assignee-filtered list" - }, - - { - "_comment": "=== /arc:dep ===", - "_target": "/arc:dep" - }, - { - "query": "Make ARC-5.3 depend on ARC-5.2 — the middleware needs the API first.", - "should_trigger": true, - "target_command": "arc:dep", - "note": "Explicit dependency creation" - }, - { - "query": "Link the test task as a child of the auth epic", - "should_trigger": true, - "target_command": "arc:dep", - "note": "Parent-child relationship request" - }, - { - "query": "Remove the dependency between the cache and auth tasks — they can run in parallel.", - "should_trigger": true, - "target_command": "arc:dep", - "note": "Dependency removal" - }, - - { - "_comment": "=== /arc:stats ===", - "_target": "/arc:stats" - }, - { - "query": "How's the project doing? Give me an overview of issue counts.", - "should_trigger": true, - "target_command": "arc:stats", - "note": "Project health overview" - }, - { - "query": "How many open issues do we have?", - "should_trigger": true, - "target_command": "arc:stats", - "note": "Issue count query" - }, - - { - "_comment": "=== /arc:init ===", - "_target": "/arc:init" - }, - { - "query": "Set up arc in this repository. Initialize the project.", - "should_trigger": true, - "target_command": "arc:init", - "note": "Project initialization" - }, - { - "query": "Initialize a new git repository here", - "should_trigger": false, - "target_command": "arc:init", - "note": "Git init, not arc init" - }, - - { - "_comment": "=== /arc:onboard ===", - "_target": "/arc:onboard" - }, - { - "query": "I just started a new session. What's the context for this project?", - "should_trigger": true, - "target_command": "arc:onboard", - "note": "Session start orientation" - }, - { - "query": "Get me up to speed on where things stand.", - "should_trigger": true, - "target_command": "arc:onboard", - "note": "Project orientation request" - }, - - { - "_comment": "=== /arc:project ===", - "_target": "/arc:workspace" - }, - { - "query": "Rename this project to 'auth-service'", - "should_trigger": true, - "target_command": "arc:workspace", - "note": "Project rename" - }, - { - "query": "List all arc projects on the server", - "should_trigger": true, - "target_command": "arc:workspace", - "note": "Project listing" - }, - { - "query": "Merge the old-api project into the main-api project", - "should_trigger": true, - "target_command": "arc:workspace", - "note": "Project merge" - }, - - { - "_comment": "=== /arc:paths ===", - "_target": "/arc:paths" - }, - { - "query": "Register this directory to the current project", - "should_trigger": true, - "target_command": "arc:paths", - "note": "Path registration. Note: no /arc:paths command exists yet — would need manual arc paths add" - }, - { - "query": "What directories are associated with this project?", - "should_trigger": true, - "target_command": "arc:paths", - "note": "Path listing query" - }, - - { - "_comment": "=== /arc:docs ===", - "_target": "/arc:docs" - }, - { - "query": "Show me the arc documentation about dependency types", - "should_trigger": true, - "target_command": "arc:docs", - "note": "Arc documentation request" - }, - { - "query": "Search the arc docs for how to write resumable issues", - "should_trigger": true, - "target_command": "arc:docs", - "note": "Documentation search" - } -] diff --git a/claude-plugin/evals/triggers/skills.json b/claude-plugin/evals/triggers/skills.json deleted file mode 100644 index 4d9f006..0000000 --- a/claude-plugin/evals/triggers/skills.json +++ /dev/null @@ -1,304 +0,0 @@ -[ - { - "_comment": "=== BRAINSTORM SKILL ===", - "_target": "arc:brainstorm" - }, - { - "query": "I want to add OAuth support to our Go API server. We currently have JWT auth in internal/api/middleware.go but I'm not sure whether to use authorization code flow or PKCE, and we need to decide on a token storage strategy — database vs Redis vs in-memory. There are security trade-offs I want to think through before writing any code. Can we brainstorm the design?", - "should_trigger": true, - "target_skill": "arc:brainstorm", - "note": "Rich design exploration with multiple architectural decisions and explicit brainstorm request" - }, - { - "query": "We need a caching layer for our API but I'm torn between Redis and an in-memory LRU cache. Our server runs as a single instance right now but we might scale to multiple replicas in Q3. The hot path is in internal/storage/sqlite/issues.go where GetIssue is called ~500 times per dashboard load. I want to explore the architecture trade-offs before committing to an approach.", - "should_trigger": true, - "target_skill": "arc:brainstorm", - "note": "Architecture decision with concrete context, metrics, and future constraints" - }, - { - "query": "I'm starting a big new feature — a notification system that needs to support email, Slack, and webhooks. Each channel has different retry semantics, rate limits, and failure modes. I haven't designed the architecture yet and I want to explore options for the message queue, channel abstraction, and delivery guarantees before anyone writes code. This will probably become an epic with 6+ tasks.", - "should_trigger": true, - "target_skill": "arc:brainstorm", - "note": "Significant multi-component feature needing design discovery before implementation" - }, - { - "query": "Fix the typo in README.md on line 42", - "should_trigger": false, - "target_skill": "arc:brainstorm", - "note": "Simple fix — no design exploration needed" - }, - { - "query": "Add a --verbose flag to the list command", - "should_trigger": false, - "target_skill": "arc:brainstorm", - "note": "Small, obvious implementation — skip straight to implement" - }, - { - "query": "Plan my vacation to Japan next month", - "should_trigger": false, - "target_skill": "arc:brainstorm", - "note": "Personal planning, not software design — should not trigger" - }, - - { - "_comment": "=== PLAN SKILL ===", - "_target": "arc:plan" - }, - { - "query": "We just finished brainstorming the auth system design — we decided on PKCE OAuth flow with Redis token storage. The design is approved and saved to epic ARC-5. Now I need to break it into implementation tasks with exact file paths, step-by-step instructions, and test commands so subagents can execute them independently.", - "should_trigger": true, - "target_skill": "arc:plan", - "note": "Post-brainstorm transition to task breakdown with specific output requirements" - }, - { - "query": "I have epic ARC-5 with the approved design for the auth system. I need to create 5-6 implementation tasks with dependencies between them — JWT generation first, then middleware, then OAuth endpoints. Each task needs file paths, steps, test commands, and scope boundaries so the arc-implementer subagent can work on them without additional context.", - "should_trigger": true, - "target_skill": "arc:plan", - "note": "Explicit task decomposition request with dependency mapping and self-contained task requirements" - }, - { - "query": "The caching feature design is finalized — LRU cache with Redis fallback. I need to plan the implementation: break it into tasks that can run in parallel where possible, identify which files each task touches so there are no conflicts, and set up the dependency graph. Some tasks share internal/cache/cache.go so they'll need to be sequenced.", - "should_trigger": true, - "target_skill": "arc:plan", - "note": "Implementation planning with parallel work safety and file ownership concerns" - }, - { - "query": "I need to think about whether we should use GraphQL or REST for the new API.", - "should_trigger": false, - "target_skill": "arc:plan", - "note": "Still in design exploration — should trigger brainstorm, not plan" - }, - { - "query": "Start implementing the login endpoint from the plan", - "should_trigger": false, - "target_skill": "arc:plan", - "note": "Ready to implement, not plan — should trigger implement" - }, - - { - "_comment": "=== IMPLEMENT SKILL ===", - "_target": "arc:implement" - }, - { - "query": "The plan for epic ARC-5 is ready with 5 tasks. ARC-5.1 through ARC-5.5 are created in arc with dependencies set up. Start implementing them — dispatch subagents for each task using TDD, verify each one passes independently, and run integration tests every 2-3 tasks. Start with ARC-5.1 (JWT token generation).", - "should_trigger": true, - "target_skill": "arc:implement", - "note": "Full orchestration request — dispatch subagents, verify, integration checkpoints" - }, - { - "query": "I need to execute the implementation plan we created for the notification system. There are 6 tasks: a T0 foundation task (shared interfaces), then 3 parallel channel tasks (email, Slack, webhook), then integration and docs. Use arc-implementer subagents for each task and arc-doc-writer for the docs-only task. Tasks ARC-7.2, 7.3, 7.4 can run in parallel with worktree isolation.", - "should_trigger": true, - "target_skill": "arc:implement", - "note": "Complex multi-task execution with parallel dispatch, agent routing, and worktree isolation" - }, - { - "query": "The tasks are all created in arc. Run `arc ready` to find what's available, claim the first task, dispatch an arc-implementer subagent with the task spec and test command, and verify the result independently before closing. Then move to the next task.", - "should_trigger": true, - "target_skill": "arc:implement", - "note": "Step-by-step implementation workflow matching the skill's protocol" - }, - { - "query": "Just quickly fix this one-liner in utils.go — change the timeout from 30s to 60s", - "should_trigger": false, - "target_skill": "arc:implement", - "note": "Trivial change — doesn't need subagent dispatch orchestration" - }, - { - "query": "What tasks are available to work on?", - "should_trigger": false, - "target_skill": "arc:implement", - "note": "Query about tasks — should trigger arc:ready, not implement" - }, - - { - "_comment": "=== DEBUG SKILL ===", - "_target": "arc:debug" - }, - { - "query": "TestCreateIssue is panicking with a nil pointer dereference at internal/storage/sqlite/issues.go:42. I ran `go test ./internal/storage/...` and got a stack trace showing GetProject returns nil. I need you to investigate the root cause — read the failing test, check the code at that line, look at recent git changes, and figure out why GetProject returns nil before we try any fix.", - "should_trigger": true, - "target_skill": "arc:debug", - "note": "Detailed bug report with stack trace, file location, and explicit investigation request" - }, - { - "query": "Our production API is returning intermittent 500 errors on the /api/v1/users endpoint. It happens about 30% of the time and the logs show 'database is locked' errors from SQLite. I've already tried increasing the busy_timeout to 10s and it didn't help. I've tried adding WAL mode and that didn't help either. This is the third fix attempt that failed — I need to go back to investigation and really understand what's causing the lock contention.", - "should_trigger": true, - "target_skill": "arc:debug", - "note": "Multi-attempt failure invoking the 3-fix rule — needs systematic investigation" - }, - { - "query": "The CI build passes locally with `make build` and `make test` but fails in GitHub Actions with 'module not found: github.com/sentiolabs/arc/internal/types'. I checked go.mod and the module path is correct. I tried `go mod tidy` and clearing the module cache, but neither worked. Something is fundamentally wrong and I need a proper investigation — check the CI config, the module paths, the build environment differences.", - "should_trigger": true, - "target_skill": "arc:debug", - "note": "Persistent environment-specific failure after initial fix attempts" - }, - { - "query": "Add error handling to the CreateUser function", - "should_trigger": false, - "target_skill": "arc:debug", - "note": "Feature request, not a bug — should not trigger debug" - }, - { - "query": "Explain how the dependency resolution algorithm works", - "should_trigger": false, - "target_skill": "arc:debug", - "note": "Code explanation, not debugging" - }, - - { - "_comment": "=== VERIFY SKILL ===", - "_target": "arc:verify" - }, - { - "query": "I think the auth middleware fix is done — I changed internal/api/middleware.go to check for nil tokens. Before I close ARC-5.1, I need you to run the full test suite with `make test`, read the complete output, confirm zero failures and no skipped tests, and only then close the issue with the evidence. Don't just tell me it works — show me proof.", - "should_trigger": true, - "target_skill": "arc:verify", - "note": "Explicit evidence-based verification request before closing an arc issue" - }, - { - "query": "The arc-implementer subagent reported PASS on all gate checks for ARC-5.2 (OAuth endpoints). But I don't trust subagent self-reports — run `go test ./internal/api/...` yourself, check the output for any failures or warnings, and verify independently before we close this task.", - "should_trigger": true, - "target_skill": "arc:verify", - "note": "Trust-but-verify pattern — independent verification of subagent results" - }, - { - "query": "We just finished implementing the session management task. Before closing ARC-5.3, run `make test` and `make build` to verify everything compiles and all tests pass. I want to see the actual test count and zero failures in the output before proceeding.", - "should_trigger": true, - "target_skill": "arc:verify", - "note": "Pre-close quality gate with specific proof commands" - }, - { - "query": "What does the verify skill do?", - "should_trigger": false, - "target_skill": "arc:verify", - "note": "Question about the skill, not a verification request" - }, - - { - "_comment": "=== REVIEW SKILL ===", - "_target": "arc:review" - }, - { - "query": "The arc-implementer just finished task ARC-5.2 (OAuth endpoint implementation). PRE_TASK_SHA is abc1234. I need a code review before we close this task — dispatch the arc-reviewer to check the diff from abc1234 to HEAD against the task spec. Look for critical issues, security concerns in the OAuth flow, test coverage gaps, and adherence to project conventions.", - "should_trigger": true, - "target_skill": "arc:review", - "note": "Post-implementation review dispatch with SHAs and specific review criteria" - }, - { - "query": "I want a thorough code review of the changes since the last commit. We modified internal/api/server.go, internal/api/middleware.go, and added 3 new test files. Check for security issues in the auth handling, proper error propagation, and make sure the tests actually cover the edge cases. Dispatch the arc-reviewer agent with the diff.", - "should_trigger": true, - "target_skill": "arc:review", - "note": "Detailed code review request with specific files and review focus areas" - }, - { - "query": "Before we close out the session, I want to review all the code changes from today's work. We implemented 3 tasks (ARC-5.1, 5.2, 5.3) and I want to make sure nothing was missed — run the arc-reviewer agent against the full diff from this morning's baseline to HEAD, and triage any findings by severity.", - "should_trigger": true, - "target_skill": "arc:review", - "note": "End-of-session review with multi-task scope and severity triage" - }, - { - "query": "Review the restaurant options for our team dinner", - "should_trigger": false, - "target_skill": "arc:review", - "note": "Non-code review — should not trigger" - }, - - { - "_comment": "=== FINISH SKILL ===", - "_target": "arc:finish" - }, - { - "query": "OK I'm done for the day. We completed ARC-5.1 and ARC-5.2 but didn't get to ARC-5.3. I need you to run the full session completion protocol: capture remaining work as arc issues, run quality gates (make test, make build), close the completed issues with resolution notes, commit all changes with specific files staged, push to the remote, and verify the push succeeded. Don't skip any steps.", - "should_trigger": true, - "target_skill": "arc:finish", - "note": "Full session completion request hitting all phases of the finish protocol" - }, - { - "query": "That's all the work for this session. We discovered a bug in token refresh logic while working on ARC-5.2 — create an arc issue for it before we forget. Then close ARC-5.1 and ARC-5.2 with summaries, run the tests one more time, commit everything, and push. Make sure nothing is left unpushed.", - "should_trigger": true, - "target_skill": "arc:finish", - "note": "Session completion with discovered work capture and git finalization" - }, - { - "query": "Let's land the plane. I've been working on this branch all day — there are changes across internal/api/, internal/storage/, and the test files. Run the quality gates, update the arc issues to reflect what we actually completed vs what's still open, commit with a proper conventional commit message, and push. Then run arc prime so the next session has context.", - "should_trigger": true, - "target_skill": "arc:finish", - "note": "Uses 'land the plane' idiom with multi-file scope and handoff context" - }, - { - "query": "We're done with the feature. Time to wrap up — close the arc issues, run tests, commit, push. I want to make sure the remote is up to date and nothing is left dangling.", - "should_trigger": true, - "target_skill": "arc:finish", - "note": "Completion signal with explicit commit/push expectation" - }, - { - "query": "Finish implementing the login form component", - "should_trigger": false, - "target_skill": "arc:finish", - "note": "'Finish implementing' means continue work, not end session" - }, - { - "query": "Can you finish writing the test for the parser?", - "should_trigger": false, - "target_skill": "arc:finish", - "note": "'Finish writing' means complete a task, not end session" - }, - - { - "_comment": "=== ARC-TEAM-DEPLOY SKILL ===", - "_target": "arc:arc-team-deploy" - }, - { - "query": "Deploy a team for epic ARC-5. I've labeled the tasks with teammate:frontend and teammate:backend. The frontend agent should work on ARC-5.3 and ARC-5.4 (React components) while the backend agent handles ARC-5.1 and ARC-5.2 (Go API). They share no files so they can work in parallel with worktree isolation.", - "should_trigger": true, - "target_skill": "arc:arc-team-deploy", - "note": "Explicit team deploy request with teammate labels and parallel work plan" - }, - { - "query": "I have 6 tasks in epic ARC-7 that I want to distribute across 3 parallel agents — one for each notification channel (email, Slack, webhook). Each agent should work in its own worktree, implement using TDD, and report back. Spawn the team from the arc issue graph.", - "should_trigger": true, - "target_skill": "arc:arc-team-deploy", - "note": "Multi-agent parallel dispatch from issue graph with worktree isolation" - }, - { - "query": "Create a team to distribute the auth epic tasks across multiple agents. I want a frontend teammate and a backend teammate working simultaneously. Use the teammate labels I set on the issues to assign work.", - "should_trigger": true, - "target_skill": "arc:arc-team-deploy", - "note": "Team creation for task distribution with role-based agent assignment" - }, - { - "query": "Implement the next task from the plan sequentially.", - "should_trigger": false, - "target_skill": "arc:arc-team-deploy", - "note": "Sequential execution — should trigger implement, not team-deploy" - }, - - { - "_comment": "=== ARC GENERAL SKILL ===", - "_target": "arc:arc" - }, - { - "query": "I'm new to this project. How does arc work? What commands are available, how do I track my work, and what's the difference between using arc issues vs TodoWrite? I see there's a whole workflow system but I need to understand the basics before I start using it.", - "should_trigger": true, - "target_skill": "arc:arc", - "note": "Onboarding question about arc workflow and command overview" - }, - { - "query": "I'm confused about arc dependencies. When should I use 'blocks' vs 'related' vs 'parent-child'? And what happens when I mark something as blocked — does it affect what shows up in `arc ready`? I want to set up the right dependency structure for my epic.", - "should_trigger": true, - "target_skill": "arc:arc", - "note": "Detailed arc concept question about dependency types and their behavioral effects" - }, - { - "query": "What's the recommended workflow for using arc in a multi-session project? I've got 10 tasks for a big feature and I want to make sure context carries across sessions. Should I use arc prime? What about arc plan? Walk me through the full arc workflow.", - "should_trigger": true, - "target_skill": "arc:arc", - "note": "Workflow guidance question covering multiple arc features" - }, - { - "query": "How do I configure VS Code for TypeScript?", - "should_trigger": false, - "target_skill": "arc:arc", - "note": "General IDE question — nothing to do with arc" - } -] diff --git a/claude-plugin/evals/workspace/optimization/brainstorm_report.html b/claude-plugin/evals/workspace/optimization/brainstorm_report.html deleted file mode 100644 index 491da73..0000000 --- a/claude-plugin/evals/workspace/optimization/brainstorm_report.html +++ /dev/null @@ -1,171 +0,0 @@ -<!DOCTYPE html> -<html> -<head> - <meta charset="utf-8"> - <meta http-equiv="refresh" content="5"> - <title>brainstorm — Skill Description Optimization - - - - - - -

brainstorm — Skill Description Optimization

-
- Optimizing your skill's description. This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, Claude will apply the best-performing description to your skill. -
- -
-

Original: Use when starting a new feature, project, or significant piece of work that needs design exploration, architecture decisions, or design trade-offs before implementation. Guides Socratic discovery of requirements and constraints, then saves the approved design as an arc plan.

-

Best: Use when starting a new feature, project, or significant piece of work that needs design exploration, architecture decisions, or design trade-offs before implementation. Guides Socratic discovery of requirements and constraints, then saves the approved design as an arc plan.

-

Best Score: in progress (train)

-

Iterations: 1 | Train: 4 | Test: 2

-
- -
- Query columns: - Should trigger - Should NOT trigger - Train - Test -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IterTrainTestDescriptionAdd a --verbose flag to the list commandI want to add OAuth support to our Go API server. We currently have JWT auth in internal/api/middleware.go but I'm not sure whether to use authorization code flow or PKCE, and we need to decide on a token storage strategy — database vs Redis vs in-memory. There are security trade-offs I want to think through before writing any code. Can we brainstorm the design?I'm starting a big new feature — a notification system that needs to support email, Slack, and webhooks. Each channel has different retry semantics, rate limits, and failure modes. I haven't designed the architecture yet and I want to explore options for the message queue, channel abstraction, and delivery guarantees before anyone writes code. This will probably become an epic with 6+ tasks.Fix the typo in README.md on line 42We need a caching layer for our API but I'm torn between Redis and an in-memory LRU cache. Our server runs as a single instance right now but we might scale to multiple replicas in Q3. The hot path is in internal/storage/sqlite/issues.go where GetIssue is called ~500 times per dashboard load. I want to explore the architecture trade-offs before committing to an approach.Plan my vacation to Japan next month
13/41/2Use when starting a new feature, project, or significant piece of work that needs design exploration, architecture decisions, or design trade-offs before implementation. Guides Socratic discovery of requirements and constraints, then saves the approved design as an arc plan.✓0/1✗0/1✓1/1✓0/1✗0/1✓0/1
-
- - - diff --git a/claude-plugin/evals/workspace/optimization/debug_report.html b/claude-plugin/evals/workspace/optimization/debug_report.html deleted file mode 100644 index afc59d1..0000000 --- a/claude-plugin/evals/workspace/optimization/debug_report.html +++ /dev/null @@ -1,169 +0,0 @@ - - - - - - debug — Skill Description Optimization - - - - - - -

debug — Skill Description Optimization

-
- Optimizing your skill's description. This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, Claude will apply the best-performing description to your skill. -
- -
-

Original: Use when encountering bugs, test failures, or unexpected behavior during implementation. Requires root cause investigation before any fix attempt. Invoked standalone or automatically from the implement skill when subagents report failures they can't resolve.

-

Best: Use when encountering bugs, test failures, or unexpected behavior during implementation. Requires root cause investigation before any fix attempt. Invoked standalone or automatically from the implement skill when subagents report failures they can't resolve.

-

Best Score: in progress (train)

-

Iterations: 1 | Train: 3 | Test: 2

-
- -
- Query columns: - Should trigger - Should NOT trigger - Train - Test -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
IterTrainTestDescriptionThe CI build passes locally with `make build` and `make test` but fails in GitHub Actions with 'module not found: github.com/sentiolabs/arc/internal/types'. I checked go.mod and the module path is correct. I tried `go mod tidy` and clearing the module cache, but neither worked. Something is fundamentally wrong and I need a proper investigation — check the CI config, the module paths, the build environment differences.Add error handling to the CreateUser functionTestCreateIssue is panicking with a nil pointer dereference at internal/storage/sqlite/issues.go:42. I ran `go test ./internal/storage/...` and got a stack trace showing GetProject returns nil. I need you to investigate the root cause — read the failing test, check the code at that line, look at recent git changes, and figure out why GetProject returns nil before we try any fix.Our production API is returning intermittent 500 errors on the /api/v1/users endpoint. It happens about 30% of the time and the logs show 'database is locked' errors from SQLite. I've already tried increasing the busy_timeout to 10s and it didn't help. I've tried adding WAL mode and that didn't help either. This is the third fix attempt that failed — I need to go back to investigation and really understand what's causing the lock contention.Explain how the dependency resolution algorithm works
11/31/2Use when encountering bugs, test failures, or unexpected behavior during implementation. Requires root cause investigation before any fix attempt. Invoked standalone or automatically from the implement skill when subagents report failures they can't resolve.✗0/1✓0/1✗0/1✗0/1✓0/1
-
- - - diff --git a/claude-plugin/evals/workspace/optimization/finish_report.html b/claude-plugin/evals/workspace/optimization/finish_report.html deleted file mode 100644 index 87dd019..0000000 --- a/claude-plugin/evals/workspace/optimization/finish_report.html +++ /dev/null @@ -1,171 +0,0 @@ - - - - - - finish — Skill Description Optimization - - - - - - -

finish — Skill Description Optimization

-
- Optimizing your skill's description. This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, Claude will apply the best-performing description to your skill. -
- -
-

Original: Use at the end of a session to capture remaining work, run quality gates, update arc issues, and commit/push all changes. Replaces both "Landing the Plane" and "finishing-a-development-branch" — one unified session completion protocol.

-

Best: Use at the end of a session to capture remaining work, run quality gates, update arc issues, and commit/push all changes. Replaces both "Landing the Plane" and "finishing-a-development-branch" — one unified session completion protocol.

-

Best Score: in progress (train)

-

Iterations: 1 | Train: 4 | Test: 2

-
- -
- Query columns: - Should trigger - Should NOT trigger - Train - Test -
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IterTrainTestDescriptionFinish implementing the login form componentOK I'm done for the day. We completed ARC-5.1 and ARC-5.2 but didn't get to ARC-5.3. I need you to run the full session completion protocol: capture remaining work as arc issues, run quality gates (make test, make build), close the completed issues with resolution notes, commit all changes with specific files staged, push to the remote, and verify the push succeeded. Don't skip any steps.That's all the work for this session. We discovered a bug in token refresh logic while working on ARC-5.2 — create an arc issue for it before we forget. Then close ARC-5.1 and ARC-5.2 with summaries, run the tests one more time, commit everything, and push. Make sure nothing is left unpushed.We're done with the feature. Time to wrap up — close the arc issues, run tests, commit, push. I want to make sure the remote is up to date and nothing is left dangling.Let's land the plane. I've been working on this branch all day — there are changes across internal/api/, internal/storage/, and the test files. Run the quality gates, update the arc issues to reflect what we actually completed vs what's still open, commit with a proper conventional commit message, and push. Then run arc prime so the next session has context.Can you finish writing the test for the parser?
11/41/2Use at the end of a session to capture remaining work, run quality gates, update arc issues, and commit/push all changes. Replaces both "Landing the Plane" and "finishing-a-development-branch" — one unified session completion protocol.✓0/1✗0/1✗0/1✗0/1✗0/1✓0/1
-
- - - diff --git a/claude-plugin/evals/workspace/quality/brainstorm/eval-1-output.md b/claude-plugin/evals/workspace/quality/brainstorm/eval-1-output.md deleted file mode 100644 index 68137dd..0000000 --- a/claude-plugin/evals/workspace/quality/brainstorm/eval-1-output.md +++ /dev/null @@ -1,41 +0,0 @@ -# Brainstorm Eval 1 - Output Summary - -## Task -"I want to add WebSocket support to our Go API server. Let's brainstorm the design." - -## Tools Called -1. **Read** - `claude-plugin/skills/brainstorm/SKILL.md` (loaded skill instructions) -2. **Bash** - `ls internal/api/` (explored API layer structure) -3. **Bash** - `cat internal/types/types.go | head -80` (reviewed core types) -4. **Bash** - `git log --oneline -10` (checked recent commits) -5. **Bash** - `arc list` (reviewed existing arc issues) -6. **Read** - `claude-plugin/skills/arc/_formatting.md` (loaded formatting guide) -7. **Read** - `internal/api/server.go` (reviewed server setup, routes, Echo framework usage) -8. **Bash** - `ls web/` (checked web frontend structure -- SvelteKit SPA) -9. **Bash** - `cat go.mod | head -20` (checked Go dependencies -- Echo v4, SQLite, etc.) - -## Questions Asked -1. **Primary use case** -- Asked the user to identify their motivation from three options: - - Live UI updates (dashboard auto-refresh when issues change) - - Real-time agent coordination (push notifications for AI agents) - - Event streaming for plugins/integrations (external tool subscriptions) - -## Approaches Proposed -None yet -- following the skill's instruction to ask clarifying questions **one at a time** before proposing approaches. The first question was about the primary use case, which determines the entire design direction (e.g., broadcast vs. subscription model, authentication needs, message format). - -## Key Observations from Context Exploration -- Server uses Echo v4 framework (which has built-in WebSocket support via `golang.org/x/net/websocket` or can use `gorilla/websocket`) -- Storage is SQLite (single-writer constraint relevant for event sourcing) -- Current architecture is purely request/response REST -- Web UI is an embedded SvelteKit SPA (would be the primary WebSocket consumer) -- No existing event/notification infrastructure -- The project already has an events/audit trail endpoint (`/issues/:id/events`) which could be a foundation - -## Workflow Status -- [x] Step 1: Explore Project Context -- [x] Step 2: Ask Clarifying Questions (in progress -- first question asked) -- [ ] Step 3: Propose 2-3 Approaches -- [ ] Step 4: Present Design Section by Section -- [ ] Step 5: Identify Shared Contracts -- [ ] Step 6: Save to Arc -- [ ] Step 7: Transition diff --git a/claude-plugin/evals/workspace/quality/brainstorm/eval-4-output.md b/claude-plugin/evals/workspace/quality/brainstorm/eval-4-output.md deleted file mode 100644 index 0a93732..0000000 --- a/claude-plugin/evals/workspace/quality/brainstorm/eval-4-output.md +++ /dev/null @@ -1,32 +0,0 @@ -# Eval 4 Output: Brainstorm Skill — Simple Health Check - -## Task - -"Add a simple health check endpoint to the API. Just GET /healthz returning 200." - -## Decisions Made - -1. **Read the brainstorm skill** (`SKILL.md`) to understand the workflow and rules. -2. **Explored project context**: Listed `internal/api/` directory to understand the existing API structure. Confirmed `arc` CLI is available. -3. **Scale detection**: Applied the skill's scale detection table. This task maps to **Small** — "One task, hours of work, obvious approach." The skill explicitly says for Small work: create a single issue with `arc create`, skip brainstorm/plan, and go directly to implement. -4. **Created arc issue**: Ran `arc create "Add GET /healthz health check endpoint" --type=task`, which produced issue `arc-0ek8.009hic`. -5. **Skipped clarifying questions and multi-approach proposal**: The skill's Small path says to skip brainstorm/plan and go directly to implement. For a trivial, fully-specified task like this, asking Socratic questions would add no value. -6. **Transition**: Recommended moving to `/arc:implement` to build the endpoint, per the skill's step 7 guidance. - -## Tools Called - -| Tool | Purpose | -|------|---------| -| Read | Read `SKILL.md` for brainstorm skill instructions | -| Bash (`ls internal/api/`) | Explore project context — understand API layer structure | -| Bash (`arc --help`) | Confirm arc CLI is available | -| Bash (`arc create ...`) | Create the single arc issue for this small task | -| Write | Save this eval output | - -## Key Skill Rules Followed - -- **Hard Gate respected**: No implementation code was written. -- **Scale detection applied**: Small work correctly identified, skipped full brainstorm workflow. -- **YAGNI applied**: No over-design for a trivial endpoint. -- **Arc issue created as sole artifact**: No `docs/plans/` markdown files created. -- **Transition to implement recommended**: Per skill step 7 for small work. diff --git a/claude-plugin/evals/workspace/quality/brainstorm/eval-5-output.md b/claude-plugin/evals/workspace/quality/brainstorm/eval-5-output.md deleted file mode 100644 index 068255c..0000000 --- a/claude-plugin/evals/workspace/quality/brainstorm/eval-5-output.md +++ /dev/null @@ -1,55 +0,0 @@ -# Brainstorm Eval 5: Notification System Design - -## Task - -Design a notification system with email, Slack, and webhook channels where each channel will be implemented by a different agent in parallel. - -## Tools Called - -1. **Read** `claude-plugin/skills/brainstorm/SKILL.md` -- loaded skill instructions -2. **Read** `internal/types/types.go` (multiple ranges) -- understood existing types, Event/EventType, and project patterns -3. **Read** `internal/storage/storage.go` -- understood the Storage interface pattern -4. **Read** `internal/server/server.go` -- understood server config wiring -5. **Read** `claude-plugin/skills/arc/_formatting.md` -- loaded formatting rules -6. **Bash** `ls internal/` and `ls internal/api/` and `ls internal/types/` -- explored project structure - -## Questions Asked - -1. **What events should trigger notifications?** -- asked which issue lifecycle events matter (created, status changed, closed, comments, assignments, dependencies, or all). In eval context, proceeded with reasonable defaults (use existing `EventType` constants). - -## Contracts Identified - -### Foundation Layer (must be implemented before parallel work) - -**Package:** `internal/notify/` - -| Contract | File | Description | -|----------|------|-------------| -| `Notifier` interface | `notifier.go` | `Send(ctx, Notification) error` + `Type() ChannelType` -- the core contract all channels implement | -| `Notification` struct | `notifier.go` | Channel-agnostic payload: EventType, IssueID, ProjectID, Actor, Summary, Details map | -| `ChannelType` type | `notifier.go` | String enum: `email`, `slack`, `webhook` | -| `Config` struct | `config.go` | Top-level config holding optional `EmailConfig`, `SlackConfig`, `WebhookConfig` | -| `EmailConfig` struct | `config.go` | SMTP host/port, from address, recipients | -| `SlackConfig` struct | `config.go` | Webhook URL, optional channel override | -| `WebhookConfig` struct | `config.go` | Target URL, optional HMAC signing secret | -| `Dispatcher` struct | `dispatcher.go` | Fans out `Notification` to all registered `Notifier` instances via goroutines | - -### Parallel Tasks (independent, each implements `Notifier`) - -| Task | Package | Agent Work | -|------|---------|------------| -| Email channel | `internal/notify/email/` | SMTP send using `EmailConfig` | -| Slack channel | `internal/notify/slack/` | HTTP POST to Slack webhook using `SlackConfig` | -| Webhook channel | `internal/notify/webhook/` | HTTP POST with JSON + optional HMAC using `WebhookConfig` | - -### Integration Task (after parallel work completes) - -- Wire `Dispatcher` into API handlers in `internal/api/` where events are recorded -- Add `notify.Config` to `server.Config` - -## Design Decisions - -- **Approach chosen:** Event-driven with goroutine fan-out (simplest, YAGNI) -- **Rejected:** Queue-based persistent delivery (too complex for initial implementation), plugin/hook-based (poor DX) -- **Scale:** Medium -- single epic with foundation task, three parallel channel tasks, one integration task -- **Key insight:** Arc already has `Event` and `EventType` in `internal/types/types.go` covering all relevant lifecycle events, so the notification system subscribes to existing events rather than creating new ones diff --git a/claude-plugin/evals/workspace/quality/debug/eval-1-output.md b/claude-plugin/evals/workspace/quality/debug/eval-1-output.md deleted file mode 100644 index 8872c4a..0000000 --- a/claude-plugin/evals/workspace/quality/debug/eval-1-output.md +++ /dev/null @@ -1,57 +0,0 @@ -# Debug Eval 1: TestCreateIssue nil pointer at issues.go:42 - -## Task - -"Tests are failing: TestCreateIssue panics with nil pointer at internal/storage/sqlite/issues.go:42. Fix it." - -## Phase 1: Investigate Root Cause - -### Tools Called & Files Read - -1. **Read** `/Volumes/ExternalSamsung/devspace/personal/sentiolabs/arc/claude-plugin/skills/debug/SKILL.md` -- loaded skill instructions -2. **Read** `/Volumes/ExternalSamsung/devspace/personal/sentiolabs/arc/internal/storage/sqlite/issues.go` -- the file containing the alleged panic at line 42 -3. **Bash** `go test ./internal/storage/sqlite/...` -- attempted to reproduce the failure -4. **Bash** `git log --oneline -10` -- checked recent commits -5. **Bash** `git diff HEAD~1 -- internal/storage/sqlite/issues.go` -- checked recent changes to the failing file -6. **Glob** `internal/storage/sqlite/*_test.go` -- found all test files -7. **Grep** `func TestCreateIssue` -- searched for the named test function -8. **Grep** `type Store struct` -- examined Store structure (fields: `db *sql.DB`, `queries *db.Queries`, `path string`) -9. **Read** `/Volumes/ExternalSamsung/devspace/personal/sentiolabs/arc/internal/storage/sqlite/store.go` -- examined Store constructor (`New()`) -10. **Read** `/Volumes/ExternalSamsung/devspace/personal/sentiolabs/arc/internal/storage/sqlite/plans_test.go` -- found test helpers (`setupTestStore`, `setupTestProject`, `setupTestIssue`) -11. **Read** `/Volumes/ExternalSamsung/devspace/personal/sentiolabs/arc/internal/storage/sqlite/workspaces_test.go` -- checked for issue-creation tests -12. **Grep** `func (s *Store) GetProject` -- examined GetProject to check for nil-return scenarios -13. **Grep** `func dbProjectToType` -- confirmed it always returns a non-nil pointer -14. **Grep** `func.*GetIssue` in `db/` -- examined sqlc-generated GetIssue function -15. **Grep** `type Issue struct` in `db/` -- confirmed db.Issue model structure - -### Key Findings - -1. **The test `TestCreateIssue` does not exist.** There is no function named `TestCreateIssue` anywhere in the codebase. A grep across the entire project returned zero matches. The test names that do exist are: `TestCreateWorkspace`, `TestCreateAndGetPlan`, tests in `search_test.go`, `close_cascade_test.go`, `issues_parent_test.go`, and `merge_test.go`. - -2. **All tests pass.** Running `go test ./internal/storage/sqlite/...` completed successfully with status `ok` in 1.412s. No panics, no failures. - -3. **Line 42 of issues.go is not a nil pointer risk in normal operation.** Line 42 is inside `getNextChildNumber()`, which calls `s.db.QueryRowContext(...)`. The `s.db` field is always set by the `New()` constructor (store.go:57-58), and `New()` is the only way to create a Store. A nil pointer at `s.db` would only happen if someone constructed a `Store{}` literal without going through `New()` -- but no test does this. - -4. **No recent changes to issues.go.** `git diff HEAD~1` showed no changes to this file. The recent commits are about project rename, web lint fixes, and OpenAPI spec regeneration -- none touch issue storage logic. - -5. **The `CreateIssue` method (line 80-149) is well-guarded.** It calls `GetProject` (which returns error if project not found), validates the issue, and all code paths check errors before proceeding. The `dbIssueToType` and `dbProjectToType` helper functions always return non-nil pointers (they construct a new struct literal). - -## Phase 2: Pattern Analysis - -- The test helpers in `plans_test.go` use `setupTestStore` -> `sqlite.New(dbPath)` which properly initializes all Store fields including `s.db`. -- `setupTestIssue` calls `store.CreateIssue(ctx, issue, "test-actor")` and this works correctly in existing tests (e.g., search_test.go creates multiple issues without issues). -- No code path in the existing codebase creates a Store with a nil `db` field. - -## Conclusion - -**The reported bug cannot be reproduced.** The test `TestCreateIssue` does not exist in this codebase, all existing tests pass, and the code at issues.go:42 has no nil pointer vulnerability under normal usage. The bug report appears to describe a scenario that does not match the current state of the code. - -### Possible Explanations - -- The test may have existed in a different branch or was removed. -- The error report may reference a different version of the code. -- The line numbers may have shifted after recent refactoring (the workspace-to-project rename). - -### Next Steps (if this were a real bug) - -Per the debug skill, Phase 3 (hypothesis testing) and Phase 4 (implement fix) are blocked because there is nothing to fix -- the failure cannot be reproduced and the referenced test does not exist. If the user can provide the actual test output or stack trace, investigation can resume from there. diff --git a/claude-plugin/evals/workspace/quality/debug/eval-5-output.md b/claude-plugin/evals/workspace/quality/debug/eval-5-output.md deleted file mode 100644 index 5794f1c..0000000 --- a/claude-plugin/evals/workspace/quality/debug/eval-5-output.md +++ /dev/null @@ -1,58 +0,0 @@ -# Debug Eval 5: API returns 500 on /users - -## Hypothesis Chosen - -**The `/users` endpoint does not exist in the arc API.** None of the three suggested causes (database connection pool exhausted, query timeout, missing index on users table) are applicable because there is no `/users` route, no users table, and no user-related storage methods in the entire codebase. - -## Investigation Steps (4-Phase Process) - -### Phase 1: Investigate Root Cause - -1. **Searched for `/users` in all Go files** - zero matches. The endpoint is not registered anywhere. -2. **Reviewed `internal/api/server.go` route registration** (`registerRoutes()` at line 90) - confirmed the complete list of API routes. No `/users` endpoint exists. The API serves: projects, workspaces, issues, dependencies, labels, comments, plans, events, health, and filesystem browsing. -3. **Reviewed `internal/storage/storage.go` interface** - no user-related storage methods. The only "user" concept is the `X-Actor` request header (a simple string, defaults to "anonymous"). -4. **Searched OpenAPI spec** (`api/` directory) for any mention of "users" - no matches. -5. **Checked recent git history** (`git log --oneline -10`, `git diff --stat`) - no user-related changes. -6. **Ran full test suite** (`make test`) - all tests pass, confirming the codebase is healthy. - -### Phase 2: Pattern Analysis - -- All existing endpoints follow a consistent pattern: route registered in `registerRoutes()`, backed by a handler method on `Server`, calling through to a `Storage` interface method, implemented in SQLite. -- There is no users resource at any layer (types, storage, API, OpenAPI spec). -- Checked SPA fallback behavior: when built with `webui` tag, unmatched GET routes fall through to `web.RegisterSPA` which serves `index.html` (returns 200 with HTML, not 500). When built without `webui`, no fallback is registered (Echo returns 404/405). - -### Phase 3: Hypothesis Testing - -**Hypothesis**: The 500 is caused by requesting a nonexistent endpoint. - -**Test**: Examined what happens when a request hits a route not in `registerRoutes()`: -- For GET requests: the `/*` SPA catch-all (line 58 of `web/embed_webui.go`) intercepts and serves `index.html` with a 200 status. This means GET `/users` would return HTML (the SPA), not a 500. -- For non-GET requests (POST, PUT, etc) to `/users`: Echo returns 405 Method Not Allowed. -- Without the webui build tag: Echo returns 404 Not Found. - -**Conclusion**: A true HTTP 500 on `/users` should not occur under normal conditions. If a 500 is actually being returned, it could only happen if: -1. The SPA fallback panics (caught by `middleware.Recover()`, which returns 500) -2. The embedded filesystem is corrupted or the build is malformed -3. A reverse proxy or middleware upstream is generating the 500 - -### Phase 4: Implement Fix - -**No fix is needed.** The `/users` endpoint does not exist and was never part of the arc API. The reported 500 error cannot be attributed to any of the three suggested causes (connection pool, query timeout, missing index) because there is no users table or query. - -**Recommended action**: If a `/users` endpoint is actually desired, it would need to be designed and implemented end-to-end (types, storage interface, SQLite implementation, API handler, OpenAPI spec, route registration). If the 500 is being observed in practice, the investigation should focus on what is actually handling the request (reverse proxy, SPA fallback, middleware). - -## Tools Called - -| Tool | Purpose | -|------|---------| -| Grep (pattern: `/users`, glob: `*.go`) | Search for users endpoint in Go source | -| Bash (`git log --oneline -10`) | Check recent commits for relevant changes | -| Bash (`git diff --stat`) | Check uncommitted changes | -| Grep (pattern: `user`, path: `internal/api/`, glob: `*.go`) | Broader search for user-related code in API layer | -| Read (`internal/api/server.go`) | Review all registered routes | -| Read (`internal/storage/storage.go`) | Review storage interface for user methods | -| Grep (pattern: `users`, path: `api/`) | Check OpenAPI spec for users endpoint | -| Grep (pattern: `RegisterSPA`, glob: `*.go`) | Find SPA handler registration | -| Read (`web/embed_webui.go`) | Understand SPA fallback behavior | -| Read (`web/embed_stub.go`) | Understand non-webui build behavior | -| Bash (`make test`) | Verify codebase health and no regressions | diff --git a/claude-plugin/evals/workspace/quality/finish/eval-5-output.md b/claude-plugin/evals/workspace/quality/finish/eval-5-output.md deleted file mode 100644 index 02e2324..0000000 --- a/claude-plugin/evals/workspace/quality/finish/eval-5-output.md +++ /dev/null @@ -1,27 +0,0 @@ -# Eval 5: Failing Tests During Finish Protocol - -## Scenario - -The test suite was run as part of the finish skill's Phase 2 (Quality Gates), and 2 tests failed in `TestOAuthCallback`. - -## Decision: Block and Fix — Do NOT Commit - -The finish skill is explicit on this point. Step 7 states: - -> **Hard gate**: If tests fail, fix them. Do NOT skip to commit. Invoke `debug` if needed. - -This is a blocking requirement. I would NOT proceed to Phase 3 (Update Arc Issues) or Phase 4 (Commit and Push). The protocol halts at Phase 2 until the quality gate passes. - -## What I Would Do - -1. **Stay in Phase 2.** The quality gate has not passed, so no subsequent phase is reachable. -2. **Diagnose the 2 failing tests in `TestOAuthCallback`.** I would examine the test output to understand what assertions failed and why. -3. **Invoke the `debug` skill if needed**, as the finish skill explicitly suggests this for test failures. -4. **Fix the root cause** of the `TestOAuthCallback` failures in the production or test code. -5. **Re-run `make test`** to confirm all tests pass, including the previously failing ones. -6. **Continue through the remaining quality gates** (lint, build) if they haven't been run yet. -7. **Only after all quality gates pass**, proceed to Phase 3 (Update Arc Issues), then Phase 4 (Commit and Push), and finally Phase 5 (Verify and Hand Off). - -## Key Principle - -The finish skill treats quality gates as hard gates, not advisory checks. Failing tests are not something to note and move past — they are a stop sign. The entire purpose of Phase 2 is to ensure that what gets committed and pushed is working code. Committing with known test failures would violate the protocol's core rule: "Never skip Phase 2 (quality gates) when code has changed." diff --git a/claude-plugin/evals/workspace/quality/finish/eval-6-output.md b/claude-plugin/evals/workspace/quality/finish/eval-6-output.md deleted file mode 100644 index a588c1f..0000000 --- a/claude-plugin/evals/workspace/quality/finish/eval-6-output.md +++ /dev/null @@ -1,39 +0,0 @@ -# Eval 6: Quality Gates When No Code Changed - -## Decision - -**Skip quality gates (Phase 2).** Do NOT run `make test`, `make lint`, or `make build`. - -## Reasoning - -The finish skill explicitly states on Phase 2: - -> *Skip this phase if no code was changed in this session.* - -This session consisted entirely of issue triage and planning -- no code was modified, no files were edited. Running `make test`, `make build`, or `make lint` would be unnecessary since: - -1. The skill has an explicit carve-out for exactly this scenario. -2. There is nothing new to validate -- the codebase is in the same state it was at session start. -3. Running quality gates on unchanged code wastes time without providing any signal. - -## What I WOULD Do (Full Protocol) - -### Phase 1: Capture Remaining Work -- Review triage/planning outcomes vs goals. -- Create arc issues for any unfinished triage items or newly discovered tasks. -- Add context notes to new issues for next-session pickup. - -### Phase 2: Quality Gates -- SKIPPED -- No code changed. Explicitly skipped per skill instructions. - -### Phase 3: Update Arc Issues -- Close issues that were fully resolved during triage. -- Update in-progress issues with progress notes and next steps. - -### Phase 4: Commit and Push -- Run `git status` to check for any changed files. -- If no files changed (likely, since only arc server-side operations were performed), there is nothing to commit or push. -- If any local files did change (e.g., arc config), stage specific files, commit with a conventional message like `chore: issue triage and planning`, and push. - -### Phase 5: Verify and Hand Off -- Run `arc prime` to output context for next session. diff --git a/claude-plugin/evals/workspace/quality/implement/eval-1-output.md b/claude-plugin/evals/workspace/quality/implement/eval-1-output.md deleted file mode 100644 index 75aa216..0000000 --- a/claude-plugin/evals/workspace/quality/implement/eval-1-output.md +++ /dev/null @@ -1,88 +0,0 @@ -# Eval 1 Output: Implement ARC-5.1 (JWT Token Generation) - -## Key Finding: The Main Agent Never Writes Implementation Code - -The implement skill's core rule is explicit: **"The main agent NEVER writes implementation code. It orchestrates, dispatches, and reviews."** I would NOT write any JWT implementation code directly. Instead, I would dispatch an `arc-implementer` subagent to do the work. - -## Step-by-Step Plan - -### Step 1: Find the Task - -Run `arc list --parent=ARC-5 --status=open` to see all tasks under epic ARC-5, or `arc show ARC-5.1` to inspect the specific task. This confirms the task exists, its description, dependencies, and labels. - -### Step 2: Claim the Task - -```bash -arc update ARC-5.1 --status in_progress -``` - -This signals to other agents/sessions that ARC-5.1 is being worked on. - -### Step 3: Record Pre-Task SHA and Check Labels - -```bash -PRE_TASK_SHA=$(git rev-parse HEAD) -arc show ARC-5.1 --json | jq -e '.labels[] | select(. == "docs-only")' > /dev/null 2>&1 -``` - -If the task has a `docs-only` label, I would dispatch an `arc-doc-writer` subagent instead. For JWT token generation, this is almost certainly NOT docs-only, so I would dispatch an `arc-implementer`. - -### Step 4: Dispatch the arc-implementer Subagent - -I would use the Agent tool (Task tool) to spawn a fresh `arc-implementer` subagent with: - -``` -Implement this task following TDD (RED -> GREEN -> REFACTOR -> GATE). - -## Task - - -## Project Test Command -make test - -Commit your work when all gate checks pass. -``` - -The subagent gets a clean context window with just the task description. It follows TDD: write a failing test first, make it pass, refactor, then run gate checks. I do NOT write any Go code, test files, or JWT logic myself. - -### Step 5: Evaluate the Subagent's Result - -When the subagent reports back, I check its **Result** and **Gate Results**: - -- **If PASS**: I run `make test` myself to independently verify. I do NOT trust the subagent's report alone. -- **If PARTIAL**: I read the `Gate: Unresolved` section and re-dispatch with the specific gaps. -- **If no gate results reported**: I treat it as failed and re-dispatch with an explicit reminder to complete all gate checks. - -### Step 6: Handle Issues (if any) - -- If the subagent reports PARTIAL with clear gaps, re-dispatch with the previous gate feedback included. -- If 3+ attempts fail on the same issue, invoke the `debug` skill instead. -- I never "just quickly fix" something myself -- I always re-dispatch. - -### Step 7: Close the Task - -After confirming tests pass with my own fresh `make test` run: - -```bash -arc close ARC-5.1 -r "Implemented: JWT token generation" -``` - -### Step 8: Integration Checkpoint - -Since this is the first task in the epic, I would note that after closing 2-3 related tasks (e.g., after ARC-5.1 and ARC-5.2), I would run `make test-integration` to catch cross-task regressions. - -### Step 9: Repeat - -Return to Step 1 for the next task in ARC-5 (e.g., ARC-5.2). - -## Summary - -The implement skill enforces a strict separation: the main agent is an **orchestrator**, not an implementer. For ARC-5.1, I would: - -1. Claim the task via `arc update` -2. Dispatch an `arc-implementer` subagent with the task description and test command -3. Verify the result independently by running `make test` myself -4. Close the task only after independent verification passes -5. Move to the next task in the epic - -I would **never** write JWT implementation code, test files, or any source code directly. All implementation work is delegated to subagents. diff --git a/claude-plugin/evals/workspace/quality/plan/eval-3-output.md b/claude-plugin/evals/workspace/quality/plan/eval-3-output.md deleted file mode 100644 index a80ca0f..0000000 --- a/claude-plugin/evals/workspace/quality/plan/eval-3-output.md +++ /dev/null @@ -1,33 +0,0 @@ -# Eval 3: File Ownership Overlap in Parallel Tasks - -## Prompt - -> Break this feature into tasks that can run in parallel. Task A modifies `internal/api/server.go` and Task B also needs to modify `internal/api/server.go`. - -## Answer - -**No, two parallel tasks cannot own the same file.** The plan skill has an explicit rule: - -> No two parallelizable tasks may own the same file — resolve overlaps via foundation task, merging, or serialization. - -Since both Task A and Task B need to modify `internal/api/server.go`, they have a file ownership conflict. This must be resolved before the tasks can be parallelized. There are exactly three resolution strategies the skill permits: - -### Resolution Options - -1. **Merge into one task** — Combine Task A and Task B into a single task that owns `internal/api/server.go`. This is simplest when the changes are small or tightly coupled. - -2. **Serialize with a dependency** — Keep them as separate tasks but add `Task B blocked by Task A`. Task A runs first and owns `server.go`; Task B runs after and also lists `server.go` in its Files section. They are no longer parallel, so the single-owner rule is satisfied. - -3. **Extract to a foundation task (T0)** — If both tasks need to add shared contracts (types, interfaces, route registrations) to `server.go`, create a T0 Foundation task that makes all the shared changes to `server.go` first. Then Task A and Task B each own only their own new files and are blocked by T0. Neither touches `server.go` directly. - -### Recommended Approach - -The best choice depends on the nature of the changes: - -- If both tasks add independent route handlers, **extract route registration to T0** and let each task own only its handler file (e.g., `internal/api/handler_a.go` and `internal/api/handler_b.go`). -- If the changes to `server.go` are interleaved or both tasks modify the same function, **merge the tasks**. -- If one task's changes are a prerequisite for the other, **serialize with a dependency**. - -### Key Principle - -The file ownership rule exists because parallel subagents work from the same HEAD. If two agents independently edit the same file, their changes will conflict on merge. The plan skill prevents this at planning time rather than dealing with merge conflicts at implementation time. diff --git a/claude-plugin/evals/workspace/quality/plan/eval-4-output.md b/claude-plugin/evals/workspace/quality/plan/eval-4-output.md deleted file mode 100644 index 7c29eaa..0000000 --- a/claude-plugin/evals/workspace/quality/plan/eval-4-output.md +++ /dev/null @@ -1,162 +0,0 @@ -# Notification System — Task Breakdown - -## Shared Contracts Identified - -The design specifies three shared contracts referenced by all channel tasks: - -- **`Notifier` interface** — common send/validate contract for all channels -- **`NotificationPayload` type** — shared data structure passed to every notifier -- **Config keys** — shared configuration key constants for channel registration - -Because the email, Slack, and webhook channel tasks will run **in parallel**, these shared definitions must exist in HEAD before any parallel task begins. This triggers the **T0: Foundation** pattern from step 2 of the plan skill. - -## Task Structure - -### T0: Foundation — Shared Notification Contracts - -**Type:** task -**Parent:** `` - -**Files:** -- Create: `internal/notify/notify.go` -- Create: `internal/notify/notify_test.go` -- Modify: `internal/types/types.go` (add `NotificationPayload` type) - -**Scope Boundary:** -Do NOT create or modify any files outside the Files section above. -Channel-specific implementations (email, Slack, webhook) belong to their own tasks. - -**Steps:** -1. Write a failing test in `internal/notify/notify_test.go` that asserts a `Notifier` interface exists with `Send(ctx context.Context, payload NotificationPayload) error` and `Validate() error` methods -2. Run `go test ./internal/notify/...` — confirm it fails (undefined types) -3. Define `NotificationPayload` in `internal/types/types.go` with fields: `Event string`, `IssueID string`, `ProjectID string`, `Summary string`, `Timestamp time.Time`, `Metadata map[string]string` -4. Create `internal/notify/notify.go` with the `Notifier` interface and config key constants (`ConfigKeyEmail`, `ConfigKeySlack`, `ConfigKeyWebhook`) -5. Run `go test ./internal/notify/...` — confirm it passes -6. Commit: `feat(notify): add Notifier interface, NotificationPayload, and config keys` - -**Test Command:** `go test ./internal/notify/...` - -**Expected Outcome:** `Notifier` interface, `NotificationPayload` type, and config key constants are defined and importable by downstream channel tasks. - ---- - -### T1: Email Channel Notifier - -**Type:** task -**Parent:** `` -**Blocked by:** T0 - -**Files:** -- Create: `internal/notify/email.go` -- Create: `internal/notify/email_test.go` - -**Scope Boundary:** -Do NOT create or modify any files outside the Files section above. -If you need the `Notifier` interface or `NotificationPayload` type, import them — they already exist from T0. - -**Steps:** -1. Write a failing test in `internal/notify/email_test.go` that creates an `EmailNotifier` and asserts it satisfies the `Notifier` interface via `var _ Notifier = (*EmailNotifier)(nil)` -2. Write a test for `Validate()` that checks required config (SMTP host, port, from address) returns error when missing -3. Write a test for `Send()` that uses a mock SMTP connection and verifies the payload is formatted into an email with correct subject/body -4. Run `go test ./internal/notify/...` — confirm tests fail -5. Implement `EmailNotifier` struct in `internal/notify/email.go` with fields for SMTP config, a `NewEmailNotifier(cfg map[string]string) (*EmailNotifier, error)` constructor, `Validate() error`, and `Send(ctx, payload) error` -6. Run `go test ./internal/notify/...` — confirm all email tests pass -7. Commit: `feat(notify): add email channel notifier` - -**Test Command:** `go test ./internal/notify/...` - -**Expected Outcome:** `EmailNotifier` implements `Notifier`, validates SMTP config, and formats+sends email notifications. - ---- - -### T2: Slack Channel Notifier - -**Type:** task -**Parent:** `` -**Blocked by:** T0 - -**Files:** -- Create: `internal/notify/slack.go` -- Create: `internal/notify/slack_test.go` - -**Scope Boundary:** -Do NOT create or modify any files outside the Files section above. -If you need the `Notifier` interface or `NotificationPayload` type, import them — they already exist from T0. - -**Steps:** -1. Write a failing test in `internal/notify/slack_test.go` that creates a `SlackNotifier` and asserts it satisfies the `Notifier` interface via `var _ Notifier = (*SlackNotifier)(nil)` -2. Write a test for `Validate()` that checks required config (webhook URL, channel) returns error when missing -3. Write a test for `Send()` that uses an `httptest.Server` to capture the outbound POST and verifies the JSON payload contains the correct Slack message structure -4. Run `go test ./internal/notify/...` — confirm tests fail -5. Implement `SlackNotifier` struct in `internal/notify/slack.go` with fields for webhook URL and channel, a `NewSlackNotifier(cfg map[string]string) (*SlackNotifier, error)` constructor, `Validate() error`, and `Send(ctx, payload) error` that POSTs a Slack-formatted JSON message -6. Run `go test ./internal/notify/...` — confirm all Slack tests pass -7. Commit: `feat(notify): add Slack channel notifier` - -**Test Command:** `go test ./internal/notify/...` - -**Expected Outcome:** `SlackNotifier` implements `Notifier`, validates webhook config, and sends Slack-formatted notifications via HTTP POST. - ---- - -### T3: Webhook Channel Notifier - -**Type:** task -**Parent:** `` -**Blocked by:** T0 - -**Files:** -- Create: `internal/notify/webhook.go` -- Create: `internal/notify/webhook_test.go` - -**Scope Boundary:** -Do NOT create or modify any files outside the Files section above. -If you need the `Notifier` interface or `NotificationPayload` type, import them — they already exist from T0. - -**Steps:** -1. Write a failing test in `internal/notify/webhook_test.go` that creates a `WebhookNotifier` and asserts it satisfies the `Notifier` interface via `var _ Notifier = (*WebhookNotifier)(nil)` -2. Write a test for `Validate()` that checks required config (target URL) returns error when missing and that URL is valid -3. Write a test for `Send()` that uses an `httptest.Server` to capture the outbound POST and verifies the raw `NotificationPayload` is sent as JSON with correct `Content-Type` header and optional HMAC signature header -4. Run `go test ./internal/notify/...` — confirm tests fail -5. Implement `WebhookNotifier` struct in `internal/notify/webhook.go` with fields for target URL and optional signing secret, a `NewWebhookNotifier(cfg map[string]string) (*WebhookNotifier, error)` constructor, `Validate() error`, and `Send(ctx, payload) error` that POSTs the JSON payload with optional HMAC-SHA256 signature -6. Run `go test ./internal/notify/...` — confirm all webhook tests pass -7. Commit: `feat(notify): add webhook channel notifier` - -**Test Command:** `go test ./internal/notify/...` - -**Expected Outcome:** `WebhookNotifier` implements `Notifier`, validates URL config, and sends JSON payloads with optional HMAC signing. - ---- - -## Dependencies - -``` -T1 (Email) blocked by T0 (Foundation) -T2 (Slack) blocked by T0 (Foundation) -T3 (Webhook) blocked by T0 (Foundation) -``` - -## Execution Graph - -``` -T0: Foundation (sequential — runs first) - | - +---> T1: Email \ - +---> T2: Slack } parallel batch - +---> T3: Webhook / -``` - -## File Ownership (No Overlaps) - -| File | Owner | -|------|-------| -| `internal/notify/notify.go` | T0 | -| `internal/notify/notify_test.go` | T0 | -| `internal/types/types.go` (NotificationPayload) | T0 | -| `internal/notify/email.go` | T1 | -| `internal/notify/email_test.go` | T1 | -| `internal/notify/slack.go` | T2 | -| `internal/notify/slack_test.go` | T2 | -| `internal/notify/webhook.go` | T3 | -| `internal/notify/webhook_test.go` | T3 | - -No two parallel tasks share a file. All shared definitions live in T0, which completes before the parallel batch begins. diff --git a/claude-plugin/evals/workspace/quality/review/eval-3-output.md b/claude-plugin/evals/workspace/quality/review/eval-3-output.md deleted file mode 100644 index fc39e45..0000000 --- a/claude-plugin/evals/workspace/quality/review/eval-3-output.md +++ /dev/null @@ -1,31 +0,0 @@ -# Eval 3: Circuit Breaker on Repeated Review/Fix Cycles - -## Scenario - -3rd review/fix cycle for ARC-5.2. The reviewer keeps flagging the same error handling pattern as Critical, but the implementer keeps writing it the same way. - -## Decision - -**STOP. Do NOT dispatch a 4th review/fix cycle. Escalate to the user.** - -## Reasoning - -The review skill (SKILL.md, step 4) defines a circuit breaker: - -> If 3 review/fix cycles on the same task haven't resolved all findings, STOP. Escalate to the user with a summary of what keeps recurring -- the reviewer and implementer may disagree on the approach, or the task spec may be ambiguous. - -This is exactly that situation. Three cycles have completed with the same Critical finding recurring each time. The reviewer and implementer are not converging on a solution. Dispatching a 4th cycle would produce the same result. - -## What I Would Do - -1. **Do NOT** re-dispatch `arc-implementer` for another fix attempt. -2. **Do NOT** re-dispatch `arc-reviewer` for another review. -3. **Escalate to the user** with: - - The specific error handling pattern the reviewer flags as Critical - - The pattern the implementer keeps using instead - - A request for the user to decide: clarify the task spec, choose an approach, or downgrade the finding -4. Wait for the user's guidance before proceeding. - -## Key Principle - -The circuit breaker exists to prevent infinite loops when subagents disagree. The orchestrator's job is to detect non-convergence and involve the human, not to blindly retry the same failing cycle. diff --git a/claude-plugin/evals/workspace/quality/review/eval-4-output.md b/claude-plugin/evals/workspace/quality/review/eval-4-output.md deleted file mode 100644 index eb990fa..0000000 --- a/claude-plugin/evals/workspace/quality/review/eval-4-output.md +++ /dev/null @@ -1,37 +0,0 @@ -# Eval 4: Reviewer Finding — Pointer vs Value Return for GetUser - -## Reviewer Finding - -> Critical — "The function GetUser should return (User, error) not (*User, error) because User is small enough to copy." - -## Evaluation: Reject this finding - -### Reason: The finding contradicts an established, consistent codebase convention - -The reviewer's suggestion is **technically defensible in isolation** — returning small structs by value avoids a heap allocation and can be marginally faster. However, applying it here would be wrong for this codebase. Here is the evidence: - -**1. There is no `GetUser` function in this codebase.** A grep for `GetUser` across the entire repository returns zero hits in actual Go source files. The reviewer appears to be flagging a function that does not exist, which is itself a red flag on the finding's validity. - -**2. Every storage getter returns a pointer.** The `Storage` interface in `internal/storage/storage.go` defines 20+ getter methods. Every single one that returns a domain struct returns a pointer: - -- `GetProject(ctx, id) (*types.Project, error)` -- `GetIssue(ctx, id) (*types.Issue, error)` -- `GetLabel(ctx, name) (*types.Label, error)` -- `GetWorkspace(ctx, id) (*types.Workspace, error)` -- `GetPlan(ctx, id) (*types.Plan, error)` -- `GetIssueDetails(ctx, id) (*types.IssueDetails, error)` -- `GetStatistics(ctx, projectID) (*types.Statistics, error)` -- `GetPlanContext(ctx, issueID) (*types.PlanContext, error)` -- `AddComment(ctx, ...) (*types.Comment, error)` - -There are zero exceptions. This is a deliberate, uniform convention. - -**3. Even small structs like `Label` (3 string fields) use pointer returns.** If the "small enough to copy" argument were the governing principle, `Label` and `Dependency` would already be value returns. They are not. The codebase chose consistency over micro-optimization, which is the correct trade-off for a project of this nature. - -**4. Pointer returns enable nil-as-not-found semantics.** Returning `*T` lets callers distinguish "not found" (nil pointer, no error) from "found" (non-nil pointer). Switching a single method to value return would break this pattern and force a different not-found signaling mechanism for one method only. - -### Verdict - -This is not a valid Critical finding. It is a style preference that conflicts with the project's established convention. Consistency across the interface is more valuable than saving one heap allocation on a function that (a) does not exist and (b) would be called infrequently even if it did. - -**Action taken: None. Finding rejected with evidence.** diff --git a/claude-plugin/evals/workspace/quality/verify/eval-2-output.md b/claude-plugin/evals/workspace/quality/verify/eval-2-output.md deleted file mode 100644 index 579630c..0000000 --- a/claude-plugin/evals/workspace/quality/verify/eval-2-output.md +++ /dev/null @@ -1,33 +0,0 @@ -# Eval 2: User Requests Skipping Fresh Verification - -## What the user asked - -The user said tests passed 10 minutes ago and asked to just close the issue without re-running verification. - -## What I would do - -**I would refuse to close the issue without fresh verification.** Here is exactly what I would say and do: - ---- - -I cannot close this issue based on cached results from 10 minutes ago. The verify skill's Iron Law is explicit: **no completion claims without fresh verification evidence.** "I ran it earlier" is specifically called out as insufficient -- the requirement is "Fresh. Complete. Now." - -Even if tests passed 10 minutes ago, code or state could have changed since then. Before closing any arc issue, I need to: - -1. **IDENTIFY** the proof command (e.g., `make test` for the full suite). -2. **RUN** it now, not rely on a previous run. -3. **READ** the full output -- exit code, failure count, warnings, skipped tests. -4. **VERIFY** the output actually confirms the claim (0 failures, exit 0). -5. **ONLY THEN** close the issue with `arc close -r "Verified: "`. - -I would run `make test` right now and read the complete output before closing. - ---- - -## Key principle applied - -The skill Rules section (line 81) states: "Never trust cached or remembered results -- run it fresh." The user's request to skip verification directly conflicts with this rule. Regardless of how recently tests were run, the verify skill requires fresh execution at the moment of making the completion claim. - -## Decision - -**Reject the cached result. Insist on running tests fresh before closing the issue.** diff --git a/claude-plugin/evals/workspace/quality/verify/eval-4-output.md b/claude-plugin/evals/workspace/quality/verify/eval-4-output.md deleted file mode 100644 index 5086767..0000000 --- a/claude-plugin/evals/workspace/quality/verify/eval-4-output.md +++ /dev/null @@ -1,42 +0,0 @@ -# Eval 4 — Partial Test Failure: What I Would Do - -## Situation - -The test suite ran with results: 45 passed, 2 failed. The failures are in `TestSessionExpiry` and `TestTokenRefresh`. - -## Decision: Do NOT Close the Arc Issue - -The verify skill's Gate Sequence is unambiguous on this point. - -### Step 3 (READ) requires: - -> "Failure count (must be 0, not 'some passed')" - -The failure count here is 2, not 0. Forty-five passing tests is irrelevant when two are failing. The skill explicitly warns against treating "some passed" as evidence of success. - -### Step 4 (VERIFY) requires: - -> "'0 failures' confirms 'tests pass' — 'tests ran' does not" - -The output does not confirm the claim "tests pass." It confirms "tests ran" — which is insufficient. - -### Therefore, Step 5 (ONLY THEN) is not reached. - -The completion claim cannot be made. The arc issue must NOT be closed. - -## What I Would Do Instead - -Per the skill's Arc Integration section: - -> If verification **fails**, do NOT close the issue. Instead: -> - Return to `implement` to fix the failure -> - Or invoke `debug` if the failure is unexpected - -1. **Investigate the 2 failures.** I would examine the test output for `TestSessionExpiry` and `TestTokenRefresh` to understand why they failed — looking at expected vs. actual values, stack traces, and whether the failures relate to the changes made or are pre-existing. -2. **Fix or debug.** If the failures are caused by the current changes, return to `implement` to fix them. If they are unexpected or unrelated, invoke `debug` to understand the root cause. -3. **Re-run the full test suite** after any fix — fresh, complete, now. Not a subset. -4. **Only close the arc issue** when the full suite shows 0 failures. - -## Summary - -Two test failures block issue closure regardless of how many tests pass. The verify skill's Iron Law is clear: no completion claims without fresh verification evidence showing 0 failures. Passing 45 out of 47 tests is not passing. diff --git a/claude-plugin/evals/workspace/quality/verify/eval-5-output.md b/claude-plugin/evals/workspace/quality/verify/eval-5-output.md deleted file mode 100644 index b0f9f88..0000000 --- a/claude-plugin/evals/workspace/quality/verify/eval-5-output.md +++ /dev/null @@ -1,51 +0,0 @@ -# Eval 5: Subagent Claims Tests Pass — Should We Close ARC-5.3? - -## Decision: NO — Do Not Close ARC-5.3 Yet - -The arc-implementer subagent reported that all tests pass, but this is **not sufficient evidence** to close the issue. - -## Reasoning - -The verify skill's Iron Law states: **"NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE."** - -The skill explicitly lists "Trust a subagent's report without running the proof command yourself" as a **Red Flag** indicating verification is being skipped. A subagent's claim is not a substitute for running the proof command independently and reading its full output. - -## What I Would Do (Gate Sequence) - -### 1. IDENTIFY - -The proof commands needed are: - -- `make test` — to confirm all tests pass (full suite, not a subset) -- `arc show ARC-5.3` — to understand what the issue requires and whether passing tests is the correct completion criterion - -### 2. RUN - -I would execute `make test` fresh, right now. Not rely on the subagent's earlier run. The full test suite, not a subset. - -### 3. READ - -I would read the complete output of `make test`, checking: - -- Exit code is 0 -- Failure count is 0 -- No skipped tests without explanation -- No warnings that need investigation - -### 4. VERIFY - -I would confirm the output actually proves the claim — "0 failures" and exit code 0, not just "tests ran." I would also verify via `arc show ARC-5.3` that the issue's acceptance criteria are met by passing tests (not all issues are resolved solely by tests passing). - -### 5. ONLY THEN - -If and only if verification passes, I would close the issue with evidence: - -```bash -arc close ARC-5.3 -r "Verified: make test shows X passed, 0 failed, exit 0" -``` - -If verification fails, I would not close the issue — I would return to implementation or invoke debug. - -## Summary - -Trusting a subagent's report without independent verification violates the verify skill's core principle. The correct action is to run `make test` myself, read the full output, confirm it proves the claim, and only then close ARC-5.3 with an evidence-based reason. diff --git a/claude-plugin/evals/workspace/trigger_arc_brainstorm.json b/claude-plugin/evals/workspace/trigger_arc_brainstorm.json deleted file mode 100644 index fde838c..0000000 --- a/claude-plugin/evals/workspace/trigger_arc_brainstorm.json +++ /dev/null @@ -1,26 +0,0 @@ -[ - { - "query": "I want to add OAuth support to our Go API server. We currently have JWT auth in internal/api/middleware.go but I'm not sure whether to use authorization code flow or PKCE, and we need to decide on a token storage strategy \u2014 database vs Redis vs in-memory. There are security trade-offs I want to think through before writing any code. Can we brainstorm the design?", - "should_trigger": true - }, - { - "query": "We need a caching layer for our API but I'm torn between Redis and an in-memory LRU cache. Our server runs as a single instance right now but we might scale to multiple replicas in Q3. The hot path is in internal/storage/sqlite/issues.go where GetIssue is called ~500 times per dashboard load. I want to explore the architecture trade-offs before committing to an approach.", - "should_trigger": true - }, - { - "query": "I'm starting a big new feature \u2014 a notification system that needs to support email, Slack, and webhooks. Each channel has different retry semantics, rate limits, and failure modes. I haven't designed the architecture yet and I want to explore options for the message queue, channel abstraction, and delivery guarantees before anyone writes code. This will probably become an epic with 6+ tasks.", - "should_trigger": true - }, - { - "query": "Fix the typo in README.md on line 42", - "should_trigger": false - }, - { - "query": "Add a --verbose flag to the list command", - "should_trigger": false - }, - { - "query": "Plan my vacation to Japan next month", - "should_trigger": false - } -] \ No newline at end of file diff --git a/claude-plugin/evals/workspace/trigger_arc_debug.json b/claude-plugin/evals/workspace/trigger_arc_debug.json deleted file mode 100644 index c0d267e..0000000 --- a/claude-plugin/evals/workspace/trigger_arc_debug.json +++ /dev/null @@ -1,22 +0,0 @@ -[ - { - "query": "TestCreateIssue is panicking with a nil pointer dereference at internal/storage/sqlite/issues.go:42. I ran `go test ./internal/storage/...` and got a stack trace showing GetProject returns nil. I need you to investigate the root cause \u2014 read the failing test, check the code at that line, look at recent git changes, and figure out why GetProject returns nil before we try any fix.", - "should_trigger": true - }, - { - "query": "Our production API is returning intermittent 500 errors on the /api/v1/users endpoint. It happens about 30% of the time and the logs show 'database is locked' errors from SQLite. I've already tried increasing the busy_timeout to 10s and it didn't help. I've tried adding WAL mode and that didn't help either. This is the third fix attempt that failed \u2014 I need to go back to investigation and really understand what's causing the lock contention.", - "should_trigger": true - }, - { - "query": "The CI build passes locally with `make build` and `make test` but fails in GitHub Actions with 'module not found: github.com/sentiolabs/arc/internal/types'. I checked go.mod and the module path is correct. I tried `go mod tidy` and clearing the module cache, but neither worked. Something is fundamentally wrong and I need a proper investigation \u2014 check the CI config, the module paths, the build environment differences.", - "should_trigger": true - }, - { - "query": "Add error handling to the CreateUser function", - "should_trigger": false - }, - { - "query": "Explain how the dependency resolution algorithm works", - "should_trigger": false - } -] \ No newline at end of file diff --git a/claude-plugin/evals/workspace/trigger_arc_finish.json b/claude-plugin/evals/workspace/trigger_arc_finish.json deleted file mode 100644 index 272ae0d..0000000 --- a/claude-plugin/evals/workspace/trigger_arc_finish.json +++ /dev/null @@ -1,26 +0,0 @@ -[ - { - "query": "OK I'm done for the day. We completed ARC-5.1 and ARC-5.2 but didn't get to ARC-5.3. I need you to run the full session completion protocol: capture remaining work as arc issues, run quality gates (make test, make build), close the completed issues with resolution notes, commit all changes with specific files staged, push to the remote, and verify the push succeeded. Don't skip any steps.", - "should_trigger": true - }, - { - "query": "That's all the work for this session. We discovered a bug in token refresh logic while working on ARC-5.2 \u2014 create an arc issue for it before we forget. Then close ARC-5.1 and ARC-5.2 with summaries, run the tests one more time, commit everything, and push. Make sure nothing is left unpushed.", - "should_trigger": true - }, - { - "query": "Let's land the plane. I've been working on this branch all day \u2014 there are changes across internal/api/, internal/storage/, and the test files. Run the quality gates, update the arc issues to reflect what we actually completed vs what's still open, commit with a proper conventional commit message, and push. Then run arc prime so the next session has context.", - "should_trigger": true - }, - { - "query": "We're done with the feature. Time to wrap up \u2014 close the arc issues, run tests, commit, push. I want to make sure the remote is up to date and nothing is left dangling.", - "should_trigger": true - }, - { - "query": "Finish implementing the login form component", - "should_trigger": false - }, - { - "query": "Can you finish writing the test for the parser?", - "should_trigger": false - } -] \ No newline at end of file diff --git a/claude-plugin/skills/arc-team-deploy/SKILL.md b/claude-plugin/skills/arc-team-deploy/SKILL.md deleted file mode 100644 index 523cdaa..0000000 --- a/claude-plugin/skills/arc-team-deploy/SKILL.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -name: arc-team-deploy -description: Deploy an agent team from arc's issue graph. Use when the user wants to parallelize work across multiple agents, parallelize epic tasks, says "deploy team", "spawn teammates", or wants to distribute arc epic tasks by role using teammate labels. ---- - -# Arc Team Deploy - -Deploy an agent team from arc's issue graph. Translates `teammate:*` labels, plans, and dependencies into a Claude Code team with tasks and role-filtered context. - -## When to Invoke - -- User says "deploy team", "create agent team from arc", "spawn teammates from arc" -- User runs `/arc team-deploy` -- User wants to parallelize work on an arc epic across multiple agents - -## Prerequisites - -- An arc project is active (resolved via server path registration or local config) -- An epic exists with child issues labeled `teammate:` (e.g., `teammate:frontend`, `teammate:backend`) -- The arc server is running (`arc server status`) - -## Workflow - -### Step 1: Gather Team Context - -Run `arc team context --json` to get the issue graph grouped by role. - -```bash -arc team context --json -``` - -The JSON output has this structure: - -```json -{ - "epic": { "id": "PROJ-5", "title": "Auth System", "status": "open" }, - "roles": { - "frontend": [ - { "id": "PROJ-5.1", "title": "Login form", "status": "open", "priority": 2, "blocked_by": [] } - ], - "backend": [ - { "id": "PROJ-5.2", "title": "Auth API", "status": "open", "priority": 1, "blocked_by": [] }, - { "id": "PROJ-5.3", "title": "Session middleware", "status": "open", "priority": 2, "blocked_by": ["PROJ-5.2"] } - ] - }, - "unassigned": [ - { "id": "PROJ-5.4", "title": "Write tests", "status": "open", "priority": 3, "blocked_by": [] } - ] -} -``` - -Use the `roles` keys as teammate names and paste each role's issue array into the teammate's dispatch prompt. - -If the user hasn't specified an epic, help them find one: - -```bash -arc list --type=epic --status=open -``` - -### Step 2: Present Team Composition - -Parse the JSON output and present a summary for approval: - -``` -Team composition for "": - - frontend (2 issues): Login form, Signup page - backend (3 issues): Auth API, User model, Session middleware - unassigned (1 issue): Write tests - -Proceed with team deployment? [Y/n] -``` - -If there are unassigned issues, suggest either assigning them to a role or leaving them for the lead to handle. - -### Step 3: Create Team and Tasks - -After approval: - -1. **Create the team** via `TeamCreate`: - ``` - team_name: "" - description: "Working on " - ``` - -2. **Create tasks** via `TaskCreate` for each arc issue: - - `subject`: The arc issue title - - `description`: Include the arc issue ID, plan (if any), dependencies, and priority - - `activeForm`: Present continuous of the subject (e.g., "Implementing login form") - -3. **Set task dependencies** via `TaskUpdate` with `addBlockedBy`: - - Map arc dependency IDs to the corresponding task IDs - - Only map dependencies between issues within the same team deployment - -### Step 4: Spawn Teammates - -For each role, spawn a teammate via the `Agent` tool: - -``` -subagent_type: "general-purpose" -team_name: "" -name: "" (e.g., "frontend", "backend") -``` - -**Prompt template** for each teammate: - -``` -You are the teammate working on "". - -Your arc role label is teammate:. Focus on your assigned tasks. - -Environment: ARC_TEAMMATE_ROLE= - -Workflow: -1. Check TaskList for your assigned tasks -2. Work on tasks in ID order (lowest first) -3. For each task: - - If labeled `docs-only`: mark in_progress, write documentation, verify formatting, commit, mark completed - - Otherwise: mark in_progress, implement with tests (RED → GREEN → REFACTOR), run test suite, commit, mark completed -4. After completing a task, check TaskList for the next available one -5. Send a message to the team lead when all your tasks are done - -Arc context for your issues: - -``` - -### Step 5: Assign Tasks - -Use `TaskUpdate` with `owner` to assign each task to the corresponding teammate role name. - -### Step 6: Monitor and Sync - -As team lead, follow the sync protocol: - -1. **Monitor progress** via `TaskList` — teammates send messages on completion -2. **Verify work** before closing arc issues: - ```bash - arc show # Review the issue - # Check the code changes made by the teammate - ``` -3. **Close verified issues**: - ```bash - arc close --reason "completed by " - ``` -4. **Check for newly unblocked work**: - ```bash - arc ready - ``` -5. **Shutdown teammates** when all work is complete via `SendMessage` with `type: "shutdown_request"` - -## Error Handling - -- If `arc team context` returns empty roles, the epic may not have `teammate:*` labels on children. Suggest labeling first. -- If a teammate reports a blocker, update the arc issue status: `arc update --status=blocked` -- If a task fails, investigate before reassigning — the arc issue may need plan revision. - -## Example Session - -``` -User: Deploy a team for epic PROJ-5 - -1. Run: arc team context PROJ-5 --json -2. Parse: 2 roles (frontend: 2 issues, backend: 3 issues) -3. Present composition → user approves -4. TeamCreate: "auth-system" -5. TaskCreate: 5 tasks (mapped from arc issues) -6. TaskUpdate: set dependencies between tasks -7. Agent spawn: "frontend" teammate (2 assigned tasks) -8. Agent spawn: "backend" teammate (3 assigned tasks) -9. Monitor via TaskList, verify completions -10. arc close verified issues -11. Shutdown teammates when done -``` \ No newline at end of file diff --git a/claude-plugin/skills/arc/SKILL.md b/claude-plugin/skills/arc/SKILL.md deleted file mode 100644 index 3c7c8f6..0000000 --- a/claude-plugin/skills/arc/SKILL.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -name: arc -description: General arc CLI reference and workflow context. Use when the user asks about arc commands, issue tracking workflows, when to use arc vs TodoWrite, or needs help with arc setup and configuration. ---- - -# Arc Issue Tracker - -Track complex, multi-session work with a central issue tracking system. - -## Setup - -**For Claude Code users** (recommended): -1. Install the arc plugin (provides hooks, skills, agents) -2. Run `arc onboard` in any project - it will: - - Resolve project from server-side path registration (primary mechanism) - - Or detect from local project config (`~/.arc/projects/`) - - Or prompt you to run `arc init` for new projects - -**For non-Claude users**: -```bash -arc init # Initialize project -``` - -The plugin is the single source of truth for Claude integration. It provides: -- **SessionStart/PreCompact hooks** - runs `arc prime` automatically -- **Prompt configuration** - reminds Claude to run `arc onboard` -- **Skills and resources** - detailed guides and reference -- **Agents** - for bulk operations - -## When to Use Arc vs TodoWrite - -| Use Arc | Use TodoWrite | -|---------|---------------| -| Multi-session work | Single-session tasks | -| Complex dependencies | Linear task lists | -| Discovered work patterns | Simple checklists | -| Work needing audit trail | Quick, disposable lists | - -**Rule of thumb**: When in doubt, prefer arc—persistence you don't need beats lost context. - -**Deep dive**: Run `arc docs boundaries` for detailed decision criteria. - -## Workflow Skills - -Arc includes workflow skills that guide you through the development lifecycle with built-in process discipline. - -| Skill | Purpose | Invoke when | -|-------|---------|-------------| -| `brainstorm` | Design discovery through Socratic dialogue | Starting new features or significant work | -| `plan` | Break design into implementation tasks | After brainstorm approves a design | -| `implement` | TDD execution via fresh subagents per task | Ready to implement planned tasks | -| `debug` | 4-phase root cause investigation | Encountering bugs or test failures | -| `verify` | Evidence-based completion gates | Before claiming any work is done | -| `review` | Code review dispatch and triage | After implementing a task | -| `finish` | Session completion protocol | Ending a work session | - -### Pipeline - -``` -brainstorm → plan → implement (per task) → review → finish - ↕ ↕ - debug verify -``` - -### Execution Paths - -After `plan`, choose: -- **Single-agent + subagents**: Invoke `implement`. Main agent orchestrates, subagents do TDD. Best for sequential tasks. -- **Agentic team**: Add `teammate:*` labels, invoke `arc team-deploy`. Best for parallel multi-role work. - -## Quick Start - -Run `arc onboard` at session start to get project context and available issues. - -**Project Recovery**: If local project config is missing, `arc onboard` resolves the project via server-side path registration. The server is the source of truth for project-to-directory mappings. - -## CLI Reference - -Run `arc prime` for full workflow context, or `arc --help` for specific commands. - -**Essential commands:** -- `arc ready` - Find unblocked work -- `arc create` - Create issues -- `arc update` - Update status/fields -- `arc close` - Complete work -- `arc show` - View details -- `arc dep` - Manage dependencies -- `arc plan` - Manage plans (create, show, approve, reject, comments) -- `arc which` - Show active project and resolution source -- `arc paths` - Manage workspace path registrations -- `arc project` - Manage projects (list, create, delete, rename, merge) -- `arc self update` - Update arc CLI to latest version -- `arc db backup` - Create database backup - -## Deep Dive Documentation - -**Two-step workflow:** -1. **Search** to find which topic has the info: `arc docs search "query"` -2. **Read** the full topic for details: `arc docs ` - -```bash -# Search returns [topic] in brackets - tells you where to look -arc docs search "create issue" -# Results show: [workflows] Discovery and Issue Creation... - -# Then read that topic for full content -arc docs workflows -``` - -Fuzzy matching handles typos - "dependncy" finds "dependency" docs. - -**Available topics** with `arc docs `: - -| Command | Purpose | -|---------|---------| -| `arc docs boundaries` | When to use arc vs TodoWrite - decision matrix, integration patterns, common mistakes | -| `arc docs workflows` | Step-by-step checklists for session start, epic planning, side quests, handoff | -| `arc docs dependencies` | Dependency types (blocks, related, parent-child, discovered-from) and when to use each | -| `arc docs resumability` | Writing notes that survive compaction - templates and anti-patterns | -| `arc docs plans` | Plan patterns (inline, parent-epic, shared) with examples | -| `arc docs plugin` | Claude Code plugin and Codex CLI integration guide | - -Run `arc docs` without a topic to see an overview. - -## Agent Mode - -For bulk operations (creating epics with tasks, batch updates), use the **arc-issue-tracker** agent via the Task tool. This runs arc commands without consuming main conversation context. - -## Dependency Types - -Arc supports four dependency types: - -| Type | Purpose | Affects Ready? | -|------|---------|----------------| -| **blocks** | Hard blocker - B can't start until A complete | Yes | -| **related** | Soft link - informational only | No | -| **parent-child** | Epic/subtask hierarchy | Yes | -| **discovered-from** | Track provenance of discovered work | No | - -**Deep dive**: Run `arc docs dependencies` for examples and patterns. - -## Plans - -Plans are ephemeral review artifacts backed by filesystem markdown files in `docs/plans/`. They support a review workflow with approval, rejection, and comments. - -**CLI commands:** - -| Command | Purpose | -|---------|---------| -| `arc plan create ` | Register an ephemeral plan, returns plan ID | -| `arc plan show ` | Show plan content, status, and comments | -| `arc plan approve ` | Approve the plan | -| `arc plan reject ` | Reject the plan | -| `arc plan comments ` | List review comments | - -Plans go through a review cycle: create, review (with comments), then approve or reject. Approved design content is written into the epic's description field when creating implementation tasks. Run `arc docs plans` for full details. - -## Labels - -Labels are global (shared across all projects) and support colors and descriptions. Use labels for cross-cutting categorization like `security`, `performance`, `tech-debt`. - -## Session Protocol - -**At session start:** -```bash -arc onboard # Get context, recover project if needed -``` - -**Before ending any session:** -Invoke the `finish` skill — it handles capturing remaining work, quality gates, arc updates, commit, and push. Work is NOT done until `git push` succeeds. - -**Writing notes for resumability:** -```bash -arc update --stdin <<'EOF' -COMPLETED: X. IN PROGRESS: Y. NEXT: Z -EOF -``` - -**Deep dive**: Run `arc docs resumability` for templates. - -## Common Workflows - -### Starting Work -```bash -arc onboard # Get context (recovers project if needed) -arc ready # Find available work -arc show # View details -arc update --status in_progress # Claim work -``` - -### Creating Issues -```bash -arc create "Title" -t task # Create task -arc create "Epic title" -t epic # Create epic -arc create "Subtask" --parent # Create child issue -arc dep add child-id parent-id --type parent-child # Or link existing issue to epic - -# With multi-line description (use --stdin flag): -arc create "Title" -t task --stdin <<'EOF' -Description with context, acceptance criteria, etc. -EOF -``` - -### Completing Work -```bash -arc close --reason "done" # Complete issue -arc ready # See what unblocked -``` - -**Deep dive**: Run `arc docs workflows` for complete checklists. diff --git a/claude-plugin/skills/arc/_formatting.md b/claude-plugin/skills/arc/_formatting.md deleted file mode 100644 index 20a61a5..0000000 --- a/claude-plugin/skills/arc/_formatting.md +++ /dev/null @@ -1,26 +0,0 @@ -# Content Formatting Guide - -The arc frontend renders GitHub Flavored Markdown with syntax highlighting. Follow these rules when writing issue descriptions, plans, comments, and notes. - -## Use -- **Fenced code blocks** with language tags: ` ```go `, ` ```bash `, ` ```json `, ` ```typescript `, ` ```sql `, ` ```yaml `, ` ```python `, ` ```html `, ` ```css ` -- **Headings** (`##` and `###`) for section structure -- **Bullet lists** (`-`) for unordered items and file lists -- **Numbered lists** (`1.`) for sequential steps -- **Task lists** (`- [ ]` and `- [x]`) for checklists -- **Tables** (`| col | col |`) for structured comparisons -- **Inline code** (backticks) for file paths, function names, variable names, and CLI commands -- **Bold** (`**text**`) for emphasis on key terms -- **Blockquotes** (`>`) for important callouts or notes -- **Links** (`[text](url)`) for references - -## Avoid -- Raw HTML tags — DOMPurify strips most tags -- Code fences without language tags — always specify the language for syntax highlighting -- UPPERCASE section headers (use `##` Markdown headings instead) -- Very long single-line paragraphs — use line breaks for readability - -## Code Block Languages -Supported with syntax highlighting: go, typescript, javascript, json, bash, shell, sql, yaml, markdown, html, css, python, text - -For unsupported languages, use `text` as the language tag. diff --git a/claude-plugin/skills/brainstorm/SKILL.md b/claude-plugin/skills/brainstorm/SKILL.md deleted file mode 100644 index eada093..0000000 --- a/claude-plugin/skills/brainstorm/SKILL.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -name: brainstorm -description: You MUST use this skill for any design exploration, architecture decision, or trade-off analysis before implementation begins — especially when the user says "brainstorm", "explore the design", "think through", "what approach should we take", or describes a feature with multiple valid strategies. This is the arc-native brainstorming skill that writes designs to docs/plans/ and registers them for review via arc plan. Always prefer this over generic brainstorming when the project uses arc issue tracking. ---- - -# Brainstorm — Design Discovery - -Explore requirements through Socratic dialogue before any implementation begins. - -## Hard Gate - -**Do NOT write any implementation code, scaffold any project, or take any implementation action until the design is approved.** Brainstorming produces a design document — not code. - -## Workflow - -Create a task for each step below using `TaskCreate`. Mark each as `in_progress` when starting and `completed` when done. This creates a visible progress list in the CLI that carries forward into the plan skill. - -### 1. Explore Project Context - -- Check existing files, docs, recent commits -- Review existing arc issues (`arc list`) -- Understand what already exists and what constraints are in play - -### 2. Ask Clarifying Questions - -- Ask questions **one at a time** — don't dump a list -- **Use the AskUserQuestion tool** for multiple-choice decisions (2-4 options) -- Use open-ended text questions only when you need freeform feedback -- Understand: purpose, constraints, success criteria, target users -- Continue until you have enough to propose approaches - -**Example AskUserQuestion usage:** -``` -Question: "How should we handle session persistence?" -Options: - - "In-memory only" (simplest, lost on restart) - - "SQLite" (persistent, single-node, matches existing storage) - - "Redis" (distributed, adds infrastructure dependency) -``` - -### 3. Propose 2-3 Approaches - -- Each approach: summary, trade-offs, estimated complexity -- Include a recommendation with reasoning -- **Use the AskUserQuestion tool** to present approaches as structured choices -- Apply YAGNI — remove features from all designs that aren't explicitly required - -**Example AskUserQuestion usage:** -``` -Question: "Which approach should we go with?" -Options: - - "Approach A: ..." (recommended — trade-offs...) - - "Approach B: ..." (trade-offs...) - - "Approach C: ..." (trade-offs...) -``` - -### 4. Present Design Section by Section - -- Break the design into logical sections (data model, API, UI, etc.) -- Present each section and get user approval before moving to the next -- Iterate on sections as needed based on feedback - -### 5. Identify Shared Contracts (Parallel Readiness) - -If the design will produce multiple implementation tasks that could run in parallel, explicitly identify the **shared contracts** — types, interfaces, config keys, constants, and function signatures that multiple tasks will reference. - -Contracts fall into two tiers: - -- **Shared contracts** (referenced by 2+ tasks): produce **exact, copy-pasteable code blocks** including the type definition AND a contract test assertion. The T0 foundation task will write these verbatim. -- **Task-internal types** (used within a single task): use typed pseudocode (e.g., `FeedbackRequest { memory_id: i64, rating: i8 }`) — the subagent adapts to language idioms during implementation. - -Present shared contracts to the user as a "foundation layer" with exact code: - -```go -// internal/types/config.go - -// SessionConfig holds session-related settings. -type SessionConfig struct { - Timeout time.Duration `json:"timeout"` - MaxIdle int `json:"max_idle"` - Secure bool `json:"secure"` -} -``` - -```go -// internal/storage/storage.go - -// GetSession retrieves a session by ID. -// Returns nil and no error if the session does not exist. -GetSession(ctx context.Context, id string) (*Session, error) -``` - -Contract test assertions verify that the shared types satisfy compile-time expectations. Place these **inline in each relevant test file** with a clear separator: - -```go -// internal/types/config_test.go - -// --- Contract assertions --- - -// Verify SessionConfig fields exist with expected types. -var _ time.Duration = SessionConfig{}.Timeout -var _ int = SessionConfig{}.MaxIdle -var _ bool = SessionConfig{}.Secure -``` - -```go -// internal/storage/sqlite/sqlite_test.go - -// --- Contract assertions --- - -// Verify SQLiteStore satisfies the Storage interface. -var _ storage.Storage = (*SQLiteStore)(nil) -``` - -These exact definitions and contract tests become the **T0 foundation task** during planning — implemented sequentially before any parallel work begins. The T0 task writes the shared type files and embeds contract test assertions inline in each relevant test file, so that parallel agents can import these types immediately and any drift is caught at compile time. - -**Skip this step** if the design maps to a single task or purely sequential work. - -### 6. Save Design and Register for Review - -Write the design document to `docs/plans/` and register it as an ephemeral plan for review: - -```bash -# Write the design markdown file -# Use YYYY-MM-DD-.md naming convention -cat > docs/plans/YYYY-MM-DD-.md <<'EOF' - -EOF - -# Register the plan for review (returns a plan ID + planner URL) -arc plan create docs/plans/YYYY-MM-DD-.md -``` - -The `arc plan create` command returns a plan ID. Use the plan ID to construct the planner URL in the next step. - -### 7. Review Loop - -After `arc plan create` returns the plan ID, **ALWAYS output the planner URL** so the user can click it directly in their terminal. The `arc plan create` command prints this URL, but also output it yourself to be sure: - -``` -Plan ready for review: - - http://localhost:7432/planner/ - -``` - -Replace `localhost:7432` with the actual server URL if different (check `ARC_SERVER` env var or the arc config). - -Then use the **AskUserQuestion tool** — include the planner URL directly in the options so the user sees it without scrolling: -``` -Question: "Plan ready for review at http://localhost:7432/planner/ — how would you like to proceed?" -Options: - - "Approve" (proceed to /arc:plan for implementation breakdown) - - "I've submitted feedback in the planner (http://localhost:7432/planner/)" (read comments, revise, re-present) - - "Save for later" (leave as draft — resume in a new session) -``` - -**If user approves:** -```bash -arc plan approve -``` -Then proceed to step 8. - -**If user says "feedback submitted":** -```bash -# Read review comments -arc plan comments -# Also re-read the file content in case the user edited it in the planner -arc plan show -``` -Revise the design file based on the feedback, then re-present the planner URL and options. Repeat until approved. - -**If user says "save for later":** -Tell the user they can resume by running `/arc:brainstorm` in a new session and referencing the plan file and plan ID. - -### 8. Transition - -After the plan is approved, use the **AskUserQuestion tool:** -``` -Question: "Design approved! What's next?" -Options: - - "Break into tasks with /arc:plan" (create epic + implementation tasks) - - "Implement directly with /arc:implement" (for small, single-task work) - - "Done for now" (design is saved — continue in a new session) -``` - -- **Break into tasks**: invoke the `plan` skill, passing the plan ID -- **Implement directly**: invoke the `implement` skill -- **Done for now**: tell the user the plan is approved and they can run `/arc:plan` in a new session - -## Scale Detection - -| Indicator | Scale | Structure | -|-----------|-------|-----------| -| Multiple phases, weeks of work, cross-cutting concerns | Large | Meta epic → phase epics → tasks | -| Single feature, days of work, contained scope | Medium | Epic → tasks | -| One task, hours of work, obvious approach | Small | Single issue | - -## Rules - -- The ONLY next skill after brainstorm is `plan` (or `implement` for small work) -- Never invoke implementation skills from brainstorm -- Design documents go in `docs/plans/` and are registered via `arc plan create ` -- Arc issues track persistent work; TaskCreate/TaskUpdate tracks workflow progress in the CLI -- YAGNI: if the user didn't ask for it, don't design it -- Format all arc content (descriptions, plans, comments) per `skills/arc/_formatting.md` diff --git a/claude-plugin/skills/debug/SKILL.md b/claude-plugin/skills/debug/SKILL.md deleted file mode 100644 index 25b60aa..0000000 --- a/claude-plugin/skills/debug/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -name: debug -description: You MUST use this skill when encountering any bug, test failure, unexpected behavior, nil pointer, panic, or error that needs root cause investigation — especially when the user says "debug", "investigate", "why is this failing", "root cause", or pastes a stack trace or error log. This is the arc-native debugging skill that enforces systematic investigation before any fix attempt. Always prefer this over generic debugging when the project uses arc issue tracking. ---- - -# Debug — Systematic Root Cause Investigation - -Investigate bugs methodically before attempting fixes. No guessing, no shotgunning, no Stack Overflow copypasta. - -## Iron Law - -**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.** - -If you don't understand why something is broken, you cannot fix it. A "fix" without understanding is a coincidence. - -## 4-Phase Process - -Create a TodoWrite checklist with these phases and work through them: - -### Phase 1: Investigate Root Cause - -- Read error messages **carefully** — they often tell you exactly what's wrong -- Reproduce the failure consistently — if you can't reproduce it, you can't verify a fix -- Check recent changes: `git diff`, `git log --oneline -10` -- Gather evidence: stack traces, logs, test output, error codes -- In multi-component systems, trace the data flow end-to-end -- **Do not propose fixes yet.** You are gathering evidence. - -### Phase 2: Pattern Analysis - -- Find working examples of similar code in the codebase -- Compare working code against broken code — what's different? -- Check if this is a known pattern (dependency version, config issue, API change) -- Look for similar past issues: `arc list --type=bug` - -### Phase 3: Hypothesis Testing - -- Form a **single** hypothesis about the root cause -- Design a minimal test to confirm or reject it — one change, one test -- If the hypothesis is wrong, **revert** the test change and form a new hypothesis -- Do NOT stack fixes — each hypothesis gets tested in isolation -- Document what you've tried and what you've learned - -### Phase 4: Implement Fix - -- Write a failing test that **demonstrates the bug** (the test should fail before the fix and pass after) -- Fix the **root cause**, not the symptom -- Verify the fix makes the bug test pass -- Run the **full test suite** to check for regressions -- If the fix introduces new failures, you fixed the wrong thing — go back to Phase 1 - -## The 3-Fix Rule - -If you've tried 3 fixes and none worked, **STOP**. - -You don't understand the problem yet. Going for fix #4 is insanity. - -Instead: -- Go back to Phase 1 and investigate more deeply -- Question your assumptions — are you fixing the right thing? -- Consider whether the architecture is wrong, not just the code -- Read the error message again — you probably skimmed it the first time - -## Arc Integration - -If the bug turns out to be bigger than expected (not a quick fix within the current task): - -```bash -arc create "Bug: " --type=bug --priority= -``` - -Then decide: fix it now (if it blocks current work) or defer it (if current work can continue without it). - -## Red Flags - -You're doing it wrong if you: -- Fix symptoms instead of causes -- Apply fixes without understanding why they work -- Copy code from the internet without understanding it -- Make multiple changes at once ("let me try this AND this AND this") -- Skip the failing test that demonstrates the bug -- Say "it works now" without understanding what changed - -## Rules - -- Always investigate before fixing — Phase 1 is not optional -- Always write a bug-demonstrating test before the fix -- Always run the full test suite after fixing -- Revert failed fix attempts cleanly — don't leave debris -- After debugging, return to the calling skill — typically `implement` step 4 to re-verify the subagent's result, or `verify` to re-run the gate sequence -- Format all arc content (descriptions, plans, comments) per `skills/arc/_formatting.md` diff --git a/claude-plugin/skills/finish/SKILL.md b/claude-plugin/skills/finish/SKILL.md deleted file mode 100644 index d789a67..0000000 --- a/claude-plugin/skills/finish/SKILL.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -name: finish -description: You MUST use this skill at the end of any session, when the user says "land the plane", "wrap up", "done for the day", "finish up", "session complete", "push and close", or indicates work is complete. This is the arc-native session completion protocol that captures remaining work as arc issues, runs quality gates, updates arc issue statuses, commits, and pushes. Always prefer this over generic branch-finishing when the project uses arc issue tracking. ---- - -# Finish — Unified Session Completion - -Complete the session: capture remaining work, pass quality gates, update arc, commit, push. One protocol for all contexts. - -## Iron Law - -**Work is NOT done until `git push` succeeds. No exceptions.** - -Uncommitted code doesn't exist. Unpushed commits are local fiction. The remote is the source of truth. - -## Protocol - -Create a TodoWrite checklist with all steps and work through them: - -### Phase 1: Capture Remaining Work - -1. Review what was planned vs what was completed -2. For any unfinished work or newly discovered tasks: - ```bash - arc create "Remaining: " --type=task - ``` -3. Add context notes to new issues so the next session can pick up: - ```bash - arc update --description "CONTEXT: " - ``` - -### Phase 2: Quality Gates - -*Skip this phase if no code was changed in this session.* - -4. Run project test suite: - ```bash - make test # or: go test ./..., npm test, etc. - ``` -5. Run linter/formatter if configured: - ```bash - make lint # or: golangci-lint run, eslint, etc. - ``` -6. Run build if applicable: - ```bash - make build - ``` -7. **Hard gate**: If tests fail, fix them. Do NOT skip to commit. Invoke `debug` if needed. - -### Phase 3: Update Arc Issues - -8. Close completed issues: - ```bash - arc close -r "Done: " - ``` -9. Update in-progress issues with progress notes: - ```bash - arc update --description "PROGRESS: . NEXT: " - ``` -10. Verify issue states match reality — don't leave stale statuses - -### Phase 4: Commit and Push - -11. Stage changed files (specific files, not `git add -A`): - ```bash - git add ... - ``` -12. Commit with conventional commit message: - ```bash - git commit -m "feat(scope): summary of changes" - ``` -13. Push: - ```bash - git push - ``` -14. Verify push succeeded: - ```bash - git status # Must show "up to date with origin" - ``` -15. If push fails → resolve the issue → retry → succeed. Do not leave unpushed commits. -16. Clean up worktrees: - ```bash - git worktree list - ``` - If only the main working tree is listed, skip ahead. Otherwise, for each extra worktree: - - **a. Check for uncommitted work:** - ```bash - git -C status - git -C stash list - ``` - If there are uncommitted changes or stashes → do NOT remove. Create an arc issue to track the unmerged work: - ```bash - arc create "Recover unmerged worktree work: " --type=task - ``` - - **b. Check if the branch was merged:** - ```bash - git branch --merged | grep - ``` - If merged (or if the worktree is clean with no unique commits), safe to remove: - ```bash - git worktree remove - git branch -d # Delete the merged branch - ``` - - **c. If the branch has unmerged commits but no uncommitted changes:** - Check whether the commits exist on a remote: - ```bash - git log origin/ 2>/dev/null - ``` - If pushed → safe to remove locally. If not pushed → do NOT remove; create an arc issue. - - **d. Prune stale worktree references:** - ```bash - git worktree prune - ``` - -### Phase 5: Verify and Hand Off - -17. Confirm the commit: - ```bash - git log -1 # Verify latest commit is visible - ``` -18. Output context for next session: - ```bash - arc prime - ``` - -## Context-Aware Behavior - -| Session Type | Behavior | -|-------------|----------| -| **Single-agent** | Full protocol above | -| **Team lead** | Verify teammate work → close arc issues → team cleanup → commit → push | -| **Teammate** | Commit → push (team lead handles arc close and coordination) | - -## What's NOT in This Protocol - -- `git stash clear`, `git remote prune origin` — housekeeping, not gates -- Worktree directory `.gitignore` verification — assumed to be configured at project setup -- Merge/PR/keep/discard choice — arc workflow always commits and pushes -- Performative session summaries — `arc prime` handles handoff context - -## Rules - -- Never skip Phase 2 (quality gates) when code has changed -- Never commit with `git add -A` — stage specific files -- Never leave unpushed commits -- Never close arc issues without completing the work -- Always run `arc prime` at the end for next-session context -- Format all arc content (descriptions, plans, comments) per `skills/arc/_formatting.md` diff --git a/claude-plugin/skills/implement/SKILL.md b/claude-plugin/skills/implement/SKILL.md deleted file mode 100644 index 66f0307..0000000 --- a/claude-plugin/skills/implement/SKILL.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -name: implement -description: You MUST use this skill to execute implementation tasks from an arc plan — especially when the user says "implement this", "build this", "execute the plan", "start coding", or wants to dispatch subagents for TDD execution of arc issues. The main agent orchestrates; it never writes implementation code directly. Always prefer this over generic implementation when the project uses arc issue tracking. ---- - -# Implement — Subagent-Driven TDD Execution - -Orchestrate task implementation by dispatching fresh `arc-implementer` subagents per task. Each subagent gets a clean context window with just the task description. - -## Core Rule - -**The main agent NEVER writes implementation code.** It orchestrates, dispatches, and reviews. If you're tempted to "just quickly fix this" — dispatch a subagent instead. - -## Dispatch Modes - -### Sequential (default) - -Tasks are dispatched one at a time through the orchestration loop below. Use this for: -- Most workflows — it's the safe default -- Tasks with any file overlap -- Tasks with dependency ordering (`blocks`/`blockedBy`) -- When you're unsure whether tasks are independent - -### Parallel - -Multiple tasks dispatched simultaneously using `isolation: "worktree"`. Use this **only** when ALL of these are true: -- 3+ independent tasks remain -- No shared files between any tasks in the batch -- No `blocks`/`blockedBy` dependencies between tasks in the batch -- Each task's scope is clearly defined with no ambiguity - -**When NOT to use parallel**: overlapping files, task dependencies, uncertainty about scope, fewer than 3 tasks. Default to sequential — the cost of serial execution is time; the cost of a bad parallel merge is data loss. - -## Orchestration Loop - -By default, use sequential dispatch. For independent tasks, see [Parallel Dispatch Protocol](#parallel-dispatch-protocol) below. - -**Task tracking**: At the start of implementation, create a task list using `TaskCreate` with one entry per arc issue to implement. This provides a visible progress tracker in the CLI. Update each task as you work: -- `in_progress` when dispatching the subagent -- `completed` when the task is closed in arc - -```bash -# Get the list of tasks to implement -arc list --parent= --status=open --json -``` - -Create a `TaskCreate` entry for each, then work through this loop: - -### 1. Find Next Task - -```bash -arc ready -# or for a specific epic: -arc list --parent= --status=open -``` - -### 2. Claim Task - -```bash -arc update --status in_progress -``` - -### 3. Dispatch Agent - -Record the current HEAD before dispatching — needed for review if escalated: - -```bash -PRE_TASK_SHA=$(git rev-parse HEAD) -``` - -Check whether the task has a `docs-only` label: - -```bash -arc show --json | jq -e '.labels[] | select(. == "docs-only")' > /dev/null 2>&1 -``` - -**If `docs-only`** (exit code 0) — spawn an `arc-doc-writer` subagent: - -``` -Write/update the documentation described in this task. - -## Task -> - -Verify formatting quality and commit your work. -``` - -**Otherwise** — spawn an `arc-implementer` subagent: - -``` -Implement this task following TDD (RED → GREEN → REFACTOR → GATE). - -## Task -> - -## Project Test Command - - -Commit your work when all gate checks pass. -``` - -### 4. Evaluate Result - -When the subagent reports back, check the **Result** and **Gate Results** in its report: - -**If `PASS`** (all gate checks passed): -- Run the project test command fresh yourself to confirm — do NOT trust the subagent's report alone -- If tests pass → proceed to step 5 (Dispatch Review) - -**If `PARTIAL`** (gate identified unresolved issues): -- Read the `Gate: Unresolved` section carefully -- Decide: is this a re-dispatch or a debug situation? -- Handle issues before proceeding (see below) - -**If the subagent did not include gate results** (it skipped the gate): -- Treat this as a failed result — re-dispatch with explicit reminder to complete all gate checks - -**Handling issues from PARTIAL results**: - -- **Subagent reports `PARTIAL` with clear gaps** — re-dispatch `arc-implementer` with the specific gaps listed in `Gate: Unresolved`, plus the original task description -- **Subagent reports test failures it can't resolve** — invoke the `debug` skill -- **3+ implementation attempts fail on same issue** — invoke the `debug` skill -- **Approach was wrong** — re-dispatch the appropriate agent with corrected guidance - -When re-dispatching, include the previous gate feedback so the implementer knows exactly what to fix: - -``` -Continue implementing this task. A previous attempt was made but the gate check identified issues. - -## Task -> - -## Previous Gate Feedback - - -## Project Test Command - - -Fix the identified issues, re-run all gate checks, and commit when complete. -``` - -### 5. Dispatch Review - -After confirming tests pass, invoke the `review` skill to check both code quality and plan adherence: - -```bash -# Get the design context from the parent epic -PARENT=$(arc show --json | jq -r '.parent_id // empty') -``` - -The review skill handles retrieving the full design excerpt and dispatching the reviewer. Pass the task ID and the PRE_TASK_SHA recorded in step 3. - -> **Note**: For `docs-only` tasks, review remains optional. Skip this step unless the documentation changes are substantial or affect developer-facing API docs. - -### 6. Handle Review Findings - -Process the review skill's triage results: - -| Finding | Action | -|---------|--------| -| **Critical/Important** | Re-dispatch `arc-implementer` with fixes. Re-review after. | -| **Minor** | Note in arc comment. Proceed. | -| **Deviation (fix)** | Re-dispatch `arc-implementer` to match the design. | -| **Deviation (accept)** | Log as arc comment: "Accepted deviation: \. Rationale: \." Proceed. | - -For accepted deviations, the orchestrator decides — not the reviewer. If unsure whether a deviation is an improvement, default to fixing it to match the plan. - -### 7. Close Task - -```bash -arc close -r "Implemented: " -``` - -### 8. Integration Checkpoint - -After closing 2-3 related tasks, or before switching to a new epic phase, run the full integration test suite: - -```bash -make test-integration -``` - -This catches cross-task regressions that individual implementer gate checks won't — each implementer only validates its own task's scope. Do not wait until all tasks are complete to discover integration failures. - -If integration tests fail: -- Identify which task's changes caused the failure -- Re-dispatch `arc-implementer` with the failing test details and the relevant task context -- If the failure spans multiple tasks, invoke the `debug` skill - -### 9. Repeat - -Go to step 1 for the next task. Continue until all tasks in the epic are closed. - -## Parallel Dispatch Protocol - -When you have identified a batch of truly independent tasks (see [Dispatch Modes](#dispatch-modes)), switch from the sequential loop to this protocol: - -### P1. Commit Checkpoint - -Before switching to parallel, ensure all sequential work is committed and pushed: - -```bash -git status # Must be clean — no unstaged or uncommitted changes -git log -3 # Verify recent sequential commits are present -git push # Establish a recovery point on the remote -``` - -**Hard gate**: Do NOT proceed if `git status` shows uncommitted changes. - -### P2. Record HEAD Anchor - -```bash -PARALLEL_BASE=$(git rev-parse HEAD) -echo "Parallel base: $PARALLEL_BASE" -``` - -This is the baseline all worktrees will branch from. Record it — you'll need it for verification after merge. - -### P3. Verify Independence - -For each task in the planned parallel batch: - -```bash -arc show -``` - -Confirm: -- No `blocks`/`blockedBy` relationships between tasks in this batch -- No overlapping file paths in task descriptions -- Each task has a clearly scoped, non-ambiguous specification - -If any task fails these checks, remove it from the parallel batch and handle it sequentially after. - -### P4. Dispatch in Single Turn - -All parallel Agent tool calls with `isolation: "worktree"` **must happen in the same orchestrator message**. This ensures they all branch from the same HEAD. - -``` -# In a single response, dispatch all parallel tasks: -Agent(subagent_type="arc-implementer", isolation="worktree", prompt="Task 1...") -Agent(subagent_type="arc-implementer", isolation="worktree", prompt="Task 2...") -Agent(subagent_type="arc-implementer", isolation="worktree", prompt="Task 3...") -``` - -**Never** dispatch worktree agents across multiple turns — HEAD may move between turns, causing stale branches. - -### P5. Merge-Back Verification - -After all parallel agents report back, verify the merge did not lose work: - -```bash -# 1. Check HEAD against the recorded anchor -git log --oneline $PARALLEL_BASE..HEAD # Should show ONLY the parallel agents' commits - -# 2. Verify sequential commits are still in history -git log --oneline HEAD | head -20 # All prior sequential commits must be present - -# 3. Run full test suite -make test # or project-specific test command -``` - -**If sequential commits are missing** → STOP. Do not continue. Recover from reflog: - -```bash -git reflog # Find the pre-merge state -git log --oneline # Verify it has the missing commits -# Cherry-pick or reset as appropriate — ask user if unsure -``` - -### P6. Resume Sequential - -After successful verification, return to the normal orchestration loop (step 1) for any remaining tasks. - -## When to Invoke Debug - -- Subagent reports test failures it can't resolve after reasonable effort -- 3+ implementation attempts fail on the same issue -- A regression appears that isn't explained by the current task's changes - -## Arc Commands Used - -```bash -arc ready # Find next task -arc update --status in_progress # Claim task -arc show # Get task description for subagent -arc close -r "reason" # Close completed task -``` - -## Rules - -- Never write implementation code as the main agent — always dispatch -- Never close a task without confirming tests pass yourself (fresh run) -- Never close a task if the implementer reported `PARTIAL` without re-dispatching -- If in doubt about the result, re-dispatch rather than fixing manually -- Never dispatch parallel agents without committing and pushing all sequential work first -- Never dispatch parallel agents on tasks that share files -- Never proceed after parallel merge without verifying commit history against the recorded HEAD anchor -- Never mix sequential and parallel dispatch in the same batch — finish one mode before switching to the other -- Format all arc content (descriptions, plans, comments) per `skills/arc/_formatting.md` diff --git a/claude-plugin/skills/plan/SKILL.md b/claude-plugin/skills/plan/SKILL.md deleted file mode 100644 index 99cc886..0000000 --- a/claude-plugin/skills/plan/SKILL.md +++ /dev/null @@ -1,310 +0,0 @@ ---- -name: plan -description: You MUST use this skill to break a design or feature into implementation tasks — especially after brainstorming, when the user says "plan this", "break this down", "create tasks", or wants to turn a design into actionable arc issues with exact file paths. Creates self-contained arc issues that subagents can implement with zero prior context. Always prefer this over generic planning when the project uses arc issue tracking. ---- - -# Plan — Implementation Task Breakdown - -Break an approved design into bite-sized, self-contained tasks with exact file paths and steps. - -## Plan Commands - -Plans are ephemeral review artifacts backed by filesystem markdown files: -- `arc plan create ` — Register a plan for review, returns plan ID -- `arc plan show ` — Show plan content, status, and comments -- `arc plan approve ` — Approve the plan -- `arc plan reject ` — Reject the plan -- `arc plan comments ` — List review comments - -## Granularity Rule - -Each task step is **ONE action, 2-5 minutes**. Assume the implementer has **zero codebase context** and fresh context without codebase familiarity. If a step says "add validation" without showing the code, it's too vague. - -## Workflow - -Add tasks for each step below using `TaskCreate`. If continuing from the brainstorm skill, the brainstorm tasks will already be visible — add the planning tasks alongside them so the user sees the full brainstorm→plan progression. Mark each as `in_progress` when starting and `completed` when done. - -### 1. Read the Design - -```bash -arc plan show -``` - -Load the approved design from brainstorm. The plan ID is provided by the brainstorm skill after registration. Understand the full scope before breaking it down. - -### 2. Identify Shared Contracts (Foundation Task) - -Check the design for **shared contracts** — types, interfaces, config keys, constants, or function signatures referenced by multiple tasks. If the brainstorm design includes a shared contracts section, use it as input. - -If shared contracts exist and parallel execution is likely: - -1. Create a **T0: Foundation** task that establishes all shared contracts -2. Mark all parallelizable tasks as **blocked by T0** -3. T0 runs sequentially before any parallel batch begins - -This ensures parallel agents inherit shared definitions from HEAD rather than inventing them independently. - -**T0 task descriptions must be literal, not prose.** The description should contain: -- **Exact type/interface code** to write to specific files (sourced from the brainstorm design's shared contracts) -- **Inline contract test assertions** to write in each relevant test file, so downstream tasks can verify they are using the correct types -- Steps that say "write this exact code to this exact file" — not vague instructions like "define the memory type" - -Example T0 task description: - -```markdown -## Summary -Establish shared types and contract tests for the memory feature. - -## Files -- Create: `internal/types/memory.go` -- Create: `internal/memory/memory_test.go` - -## Scope Boundary -Do NOT create or modify any files outside the Files section above. - -## Steps -1. Create `internal/types/memory.go` with this exact content: - ```go - package types - - import "time" - - type Memory struct { - ID int64 `json:"id" db:"id"` - Content string `json:"content" db:"content"` - CreatedAt time.Time `json:"created_at" db:"created_at"` - } - ``` -2. Create contract assertions in `internal/memory/memory_test.go`: - ```go - package memory - - import ( - "testing" - "time" - - "yourmodule/internal/types" - ) - - // --- Contract assertions --- - // These verify the design spec. Do NOT modify - // without updating the approved plan. - - func TestMemoryContract(t *testing.T) { - m := types.Memory{} - var _ int64 = m.ID - var _ string = m.Content - var _ time.Time = m.CreatedAt - } - - // --- Behavior tests (added by implementer) --- - ``` -3. Run `go build ./internal/types/...` — confirm it compiles -4. Run `go test ./internal/memory/...` — confirm contract tests pass -5. Commit: `feat(types): add foundation types and contract tests` - -## Test Command -go test ./internal/memory/... - -## Expected Outcome -Shared types compile and contract assertions pass. Parallel tasks can now import these types from HEAD. -``` - -**Skip this step** if the work is purely sequential or no shared contracts were identified. - -### 3. Identify Tasks - -Break the design into self-contained implementation units. Each task should: -- Have a clear, testable outcome -- Be implementable without knowledge of other tasks -- Include exact file paths for all files to create or modify -- Follow a logical dependency order -- **Not overlap in file ownership with other parallelizable tasks** - -When identifying tasks, assign **file ownership** — each file should be owned by exactly one task. If two tasks need to modify the same file, either merge them into one task, serialize them with a dependency, or extract the shared file into the foundation task. - -### 4. Create Epic and Tasks via arc-issue-tracker - -**Never run `arc create` directly** — always delegate to the `arc-issue-tracker` agent. This keeps bulk CLI output in a disposable subagent context. - -Read the full plan content first (`arc plan show `), then build a task manifest that includes: -1. **The epic** with the **full plan content** as its description (not a summary or file reference) -2. **All child tasks** with self-contained descriptions - -Dispatch the manifest: - -``` -Use the Agent tool with subagent_type="arc:arc-issue-tracker": - -Create the following epic and tasks. -After creation, set dependencies and labels as listed. -Return a summary table mapping task names to arc IDs. - -## Epic - -### -Type: epic -Description: - - -## Tasks - -### T1: -Type: task -Parent: <epic-id from above> -Description: -<full multi-line self-contained description> - -### T2: <title> -Type: task -Parent: <epic-id from above> -Description: -<full multi-line self-contained description> - -## Dependencies -- T2 blocked by T1 -- T4 blocked by T3 - -## Labels -- T3: docs-only - -## Required Output -| Task | Arc ID | Title | -|------|--------|-------| -| Epic | ... | ... | -| T1 | ... | ... | -``` - -**IMPORTANT**: The epic description MUST contain the complete approved design — the full markdown content from `arc plan show <plan-id>`. Do NOT summarize it or replace it with a file reference. The plan file is ephemeral; the epic description is the permanent record. - -For each task, check whether **all** files in its `## Files` section are documentation (`.md`, `.txt`, `README`, `CHANGELOG`, or anything under `docs/`). If so, include it in the `## Labels` section with `docs-only`. Doc-only tasks skip TDD — the `implement` skill routes them to `arc-doc-writer` instead of `arc-implementer`. - -### 5. Validate Returned Results - -Before proceeding, verify the agent's output: - -1. **Count check**: The number of returned IDs must match the number of tasks in your manifest -2. **Spot-check**: Run `arc show <id>` on one returned task to confirm it exists and has the correct parent -3. **If mismatch**: Re-dispatch the agent for missing tasks only, or create them manually - -### 6. Append Task Breakdown to Epic Description - -The epic was created in step 4 with the full design content. Now append the task breakdown table (with actual arc IDs from step 5) to the epic's description: - -```bash -arc update <epic-id> --stdin <<'EOF' -<existing epic description — the full design content from step 4> - ---- - -## Implementation Tasks - -<task breakdown table with arc IDs, titles, statuses, and dependency info> -EOF -``` - -**IMPORTANT**: Preserve the full design content already in the description — do not replace it with a summary. The epic description is the permanent record of the design. Only append the task breakdown table at the end. - -### 7. Choose Execution Path - -**Use the AskUserQuestion tool** to let the user choose: - -``` -Question: "Epic and tasks created. How should we proceed with implementation?" -Options: - - "Start implementing now" (invoke /arc:implement in this session — subagents handle TDD per task) - - "Implement in a new session" (provides the exact prompt to use) - - "Done for now" (tasks are tracked in arc — implement manually or later) -``` - -After the user chooses: - -**Start implementing now**: Invoke the `implement` skill immediately with the epic ID. - -**Implement in a new session**: Output the exact command for the user to copy-paste: -``` -Run this in a new Claude Code session: - - /arc:implement <epic-id> - -``` -Replace `<epic-id>` with the actual epic ID. - -**Done for now**: Confirm the epic and tasks are saved in arc. The user can run `/arc:implement <epic-id>` whenever they're ready. - -## Task Description Format - -Each task's `--description` must be **self-contained** (~3-5k tokens). The task description IS the implementation context — the implementer loads `arc show <task-id>` and nothing else. - -Include in every task description: - -``` -## Files -- Create: `path/to/new_file.go` -- Modify: `path/to/existing_file.go` -- Test: `path/to/file_test.go` - -## Scope Boundary -Do NOT create or modify any files outside the Files section above. -If you need a type, interface, or constant that doesn't exist, do NOT create it — -the foundation task or a prior task is responsible for shared definitions. - -## Design Contracts - -### Shared (use verbatim — defined in T0: Foundation) -```go -type Memory struct { - ID int64 `json:"id" db:"id"` - Content string `json:"content" db:"content"` - CreatedAt time.Time `json:"created_at" db:"created_at"` -} -``` - -### Task-internal -- `FeedbackRequest { memory_id: i64, rating: i8, comment: String? }` -- `MemoryStore.InsertMemory(content string) → (int64, error)` - -## Steps -1. Write failing test for <specific behavior> in `path/to/file_test.go` -2. Run `go test ./path/to/...` — confirm it fails with <expected error> -3. Implement <specific function> in `path/to/new_file.go`: - - <concrete code guidance, not just "add validation"> -4. Run `go test ./path/to/...` — confirm it passes -5. Commit: `feat(module): add <feature>` - -## Test Command -go test ./path/to/... - -## Expected Outcome -<what should work when this task is done> -``` - -### Design Contracts guidance - -Include a `## Design Contracts` section in every non-T0 task description, placed after `## Scope Boundary` and before `## Steps`. This section has two subsections: - -- **Shared (use verbatim)**: Exact type definitions copied from the T0 foundation task. The subagent MUST use these types exactly as written — same field names, same tags, same package. These are the canonical contracts established by T0 and committed to HEAD. -- **Task-internal**: Pseudocode descriptions of types and signatures that are private to this task. The subagent adapts these to language idioms (naming conventions, error handling patterns, etc.) as appropriate. - -If a type the subagent needs is not listed in Design Contracts and is not already on HEAD from T0, the subagent must NOT create it. This rule complements the Scope Boundary section — Scope Boundary restricts file ownership, Design Contracts restricts type ownership. - -For `docs-only` tasks, omit `## Test Command` and use `## Verification` instead: - -``` -## Verification -- All internal links resolve to existing files -- Heading hierarchy has no skipped levels -- Code blocks have language tags -``` - -## Rules - -- Never reference external docs or the full plan in task descriptions — everything needed is in the description -- Design documents live in `docs/plans/` and are registered via `arc plan create` -- Task descriptions must include actual code guidance, not vague instructions -- Team preparation (teammate labels) is optional — only if user chooses team execution -- The plan skill creates tasks; it does not implement them -- The plan skill never runs `arc create` directly — always delegate to `arc-issue-tracker` -- Every task must include a `## Scope Boundary` section — no file modifications outside the `## Files` list -- No two parallelizable tasks may own the same file — resolve overlaps via foundation task, merging, or serialization -- Format all arc content (descriptions, plans, comments) per `skills/arc/_formatting.md` diff --git a/claude-plugin/skills/review/SKILL.md b/claude-plugin/skills/review/SKILL.md deleted file mode 100644 index 9f74170..0000000 --- a/claude-plugin/skills/review/SKILL.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -name: review -description: You MUST use this skill after implementing a task to get code review — especially when the user says "review this", "check my code", "review the changes", or after any implementation task completes. Dispatches the arc-reviewer agent with git diff and task spec, then triages feedback by severity. Always prefer this over generic code review when the project uses arc issue tracking. ---- - -# Review — Code Review Dispatch - -Dispatch the `arc-reviewer` subagent to review implementation work, then triage findings. - -## Workflow - -Create a TodoWrite checklist with these steps: - -### 1. Get Git SHAs - -Use the `PRE_TASK_SHA` recorded by the implement skill before dispatching the implementer: - -```bash -BASE_SHA=$PRE_TASK_SHA -HEAD_SHA=$(git rev-parse HEAD) -``` - -If `PRE_TASK_SHA` is not available (e.g., standalone review), determine the range manually: - -```bash -# Check recent commits to identify where the task's work begins -git log --oneline -10 -# Set BASE_SHA to the commit before the task's first change -BASE_SHA=$(git rev-parse <commit-before-task>) -HEAD_SHA=$(git rev-parse HEAD) -``` - -### 2. Get Design Context - -If the review was invoked from the implement skill, a design excerpt should be available. Retrieve it: - -```bash -# Get the parent epic of this task -arc show <task-id> --json | jq -r '.parent_id // empty' -# If parent exists, get the epic's plan content -arc show <parent-epic-id> -``` - -Extract the design excerpt relevant to this task — typically the sections covering the types, interfaces, and architectural decisions this task implements. If no parent epic exists or no design is available, skip the design spec section in the dispatch prompt. - -### 3. Dispatch Reviewer - -Use the Agent tool to spawn an `arc-reviewer` subagent with this prompt: - -```text -Review these changes against the task spec and project conventions. - -## Task Spec -<paste output of: arc show <task-id>> - -## Design Spec -<paste the design excerpt relevant to this task — from the epic's plan or the task's ## Design Contracts section> -If no design spec is available, omit this section entirely. - -## Changes -<paste output of: git diff <BASE_SHA>..<HEAD_SHA>> - -Report findings as: Critical (must fix), Important (should fix), Minor (note for later). -If a design spec was provided, also report Plan Adherence (ADHERENT or DEVIATION with fix/accept recommendation). -``` - -### 4. Triage Feedback - -When the reviewer reports back: - -| Severity | Action | -|----------|--------| -| **Critical** | Fix immediately — re-dispatch `arc-implementer` with the specific fix. Then re-review. | -| **Important** | Fix before moving to next task — re-dispatch `arc-implementer`. Then re-review. | -| **Minor** | Note in arc issue comment for later. Proceed. | -| **Deviation (fix)** | Re-dispatch `arc-implementer` with the specific deviation to correct. | -| **Deviation (accept)** | Note the deviation as an arc comment on the task for traceability. Proceed. | - -### 5. Handle Fixes - -If fixes are needed: -1. Re-dispatch `arc-implementer` with the specific findings to address -2. After the implementer reports back, re-review (go to step 1 with updated SHAs) -3. Continue until the review is clean (no Critical or Important findings) - -**Circuit breaker**: If 3 review/fix cycles on the same task haven't resolved all findings, STOP. Escalate to the user with a summary of what keeps recurring — the reviewer and implementer may disagree on the approach, or the task spec may be ambiguous. - -### 6. Proceed - -- If all tasks are done → invoke `finish` -- If more tasks remain → return to `implement` for the next task - -## Response Discipline - -When receiving review feedback from the `arc-reviewer`: - -- **Evaluate technically.** Don't agree performatively. If a finding is wrong, explain why with evidence. -- **If it's right, fix it.** Don't negotiate or defer valid Critical/Important findings. -- **If it's ambiguous, test it.** Write a test that proves or disproves the concern. -- **No ego.** The reviewer is checking the subagent's work, not yours personally. - -## Contexts - -This skill works in both execution models: - -| Context | How review works | -|---------|-----------------| -| **Single-agent** | Main agent dispatches `arc-reviewer` subagent | -| **Team mode** | Team lead dispatches QA teammate or `arc-reviewer` subagent | - -## Rules - -- Always review after implementation — don't skip to close -- Re-review after fixes — don't assume fixes are correct -- The reviewer reports; you decide what to do with the findings -- Never make code changes in the review skill — dispatch the implementer for fixes -- Format all arc content (descriptions, plans, comments) per `skills/arc/_formatting.md` diff --git a/claude-plugin/skills/verify/SKILL.md b/claude-plugin/skills/verify/SKILL.md deleted file mode 100644 index 2d1aaf1..0000000 --- a/claude-plugin/skills/verify/SKILL.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -name: verify -description: You MUST use this skill before claiming any work is complete, any test passes, or any fix works — especially before arc close, before telling the user "done", or when the user asks "does it work?", "did the tests pass?", "is it fixed?". Requires fresh verification evidence (not cached results). Always prefer this over ad-hoc verification when the project uses arc issue tracking. ---- - -# Verify — Evidence-Based Completion Gates - -Run proof commands and read their output before making any completion claim. - -## Iron Law - -**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.** - -"It should work" is not evidence. "Tests pass" without output is not evidence. Satisfaction expressed before running the proof command is a red flag. - -## Gate Sequence - -Create a TodoWrite checklist with these steps: - -### 1. IDENTIFY - -What command proves the claim? Examples: -- "Tests pass" → `make test` or `go test ./...` -- "Build succeeds" → `make build` -- "Issue is resolved" → `arc show <id>` (check status) -- "No regressions" → full test suite, not a subset - -### 2. RUN - -Execute the **full** command. At minimum, run all tests affected by the change; running the full suite is safer. Not a subset from memory. Not "I ran it earlier." - -Fresh. Complete. Now. - -### 3. READ - -Read the **FULL** output. Not just the last line. Check: -- Exit code (0 = success) -- Failure count (must be 0, not "some passed") -- Warning count (investigate, don't ignore) -- Any skipped tests (why were they skipped?) - -### 4. VERIFY - -Does the output **actually confirm** the claim? -- "0 failures" confirms "tests pass" — "tests ran" does not -- "exit 0" confirms "build succeeds" — "compiling..." does not -- "status: closed" confirms "issue resolved" — "status: in_progress" does not - -### 5. ONLY THEN - -Make the claim. Reference the evidence: -- "Tests pass: `go test ./...` shows 47 passed, 0 failed" -- "Build succeeds: `make build` exits 0, binary at `./bin/arc`" - -## Red Flags - -You are skipping verification if you: -- Use "should work", "probably passes", "seems fine" -- Express satisfaction before running the proof command -- Run a subset of tests instead of the full suite -- Trust a subagent's report without running the proof command yourself -- Say "tests pass" without showing the output -- Claim "no regressions" without running the full suite -- Close an arc issue before verification - -## Arc Integration - -```bash -# ONLY after verification passes: -arc close <id> -r "Verified: <evidence summary>" -``` - -If verification **fails**, do NOT close the issue. Instead: -- Return to `implement` to fix the failure -- Or invoke `debug` if the failure is unexpected - -## Rules - -- Never close an arc issue without fresh verification evidence -- Never claim completion without running the proof command -- Never trust cached or remembered results — run it fresh -- After verification, proceed to `finish` (session end) or back to `implement` (next task) -- Format all arc content (descriptions, plans, comments) per `skills/arc/_formatting.md` diff --git a/codex-plugin/skills/arc/SKILL.md b/codex-plugin/skills/arc/SKILL.md deleted file mode 100644 index 893025d..0000000 --- a/codex-plugin/skills/arc/SKILL.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: arc -description: Repo-scoped Arc issue tracking workflow for Codex CLI ---- - -# Arc Issue Tracker (Codex) - -Track complex, multi-session work with a central issue tracking system. - -## Session start - -Codex CLI has no lifecycle hooks. Do this at the start of each session: - -```bash -arc onboard # Recover project, load context -arc prime # Refresh workflow context if stale or after compaction -``` - -## When to use Arc vs TodoWrite - -| Use Arc | Use TodoWrite | -|---------|---------------| -| Multi-session work | Single-session tasks | -| Complex dependencies | Linear task lists | -| Discovered work patterns | Simple checklists | -| Work needing audit trail | Quick, disposable lists | - -Rule of thumb: when in doubt, prefer arc - persistence you don't need beats lost context. - -## Essential commands - -- `arc ready` - Find unblocked work -- `arc create` - Create issues -- `arc update` - Update status/fields -- `arc close` - Complete work -- `arc show` - View details -- `arc dep` - Manage dependencies - -## Documentation lookup - -Two-step workflow: - -1. `arc docs search "query"` -2. `arc docs <topic>` - -## Session completion - -Follow the **Landing the Plane** protocol in `AGENTS.md` before ending a session. - -## Notes - -- Repo-scoped skill source lives under `.codex/skills/arc/`. -- If project config is missing but the project exists on the server, `arc onboard` will recover it. diff --git a/codex-plugin/skills/arc/skill.toml b/codex-plugin/skills/arc/skill.toml deleted file mode 100644 index 4d6dd81..0000000 --- a/codex-plugin/skills/arc/skill.toml +++ /dev/null @@ -1,2 +0,0 @@ -name = "arc" -description = "Repo-scoped Arc issue tracking workflow for Codex CLI"