capyai 0.5.2 → 0.5.3

package/AGENTS.md

@@ -52,34 +52,20 @@ If it returns `{ "error": ... }`, the API key or project ID is wrong. Ask the us
 
 ## Step 4: Load the operating manual
 
-The file `skills/capy/SKILL.md` in this repo is the full operating manual. It has everything: object model, decision trees, workflows, guardrails, command reference. You need it in your context to use Capy well.
+`skills/capy/SKILL.md` is the full operating manual: object model, decision trees, workflows, guardrails, commands. You need it in your context.
 
-Pick whichever method works for your setup:
-
-**Option A: skills.sh (if supported)**
 ```bash
 npx skills add yazcaleb/capy-cli
 ```
 
-**Option B: Copy to your skills/memory folder**
-If you have a persistent skills directory or memory system, copy the file directly:
+If skills.sh doesn't work in your setup, copy the file to your persistent skills or memory folder, or read it at session start:
 ```bash
-# Example paths — adjust to your agent's conventions
-cp skills/capy/SKILL.md ~/.claude/skills/capy/SKILL.md
-cp skills/capy/SKILL.md .cursor/skills/capy.md
-cp skills/capy/SKILL.md /path/to/your/agent/memory/capy-skill.md
+cp skills/capy/SKILL.md <your-agent-skills-dir>/capy.md
 ```
 
-**Option C: Just read it**
-If none of the above work, read `skills/capy/SKILL.md` from this repo at the start of every session. It's ~275 lines. That's your entire operating manual.
-
-## Step 5: MCP server or CLI
-
-Choose MCP if your agent supports it (structured tool calls, no shell parsing). Choose CLI if you run shell commands. Both have full API parity.
+## Step 5: MCP server (optional)
 
-**If you prefer MCP** (Cursor, Claude Desktop, agents with MCP support):
-
-Add this to your MCP configuration:
+If your agent supports MCP, add the server for structured tool calls instead of CLI. Both have full API parity.
 
 ```json
 {
@@ -130,9 +116,7 @@ Config file locations:
 | `capy_project` | Get project details (repos, code, config) | readOnly, idempotent |
 | `capy_triage` | Actionable triage with categories + recs (brief mode available) | readOnly |
 
-Tools with predictable outputs (`capy_captain`, `capy_build`, `capy_review`, `capy_approve`, `capy_retry`) declare `outputSchema` for typed structured content per the 2025-03-26 MCP spec.
-
-**If you prefer CLI** (any agent that runs shell commands): skip this step. The CLI is already installed from Step 2. Every command supports `--json` for structured output.
+If you don't use MCP, skip this step. The CLI from Step 2 works everywhere with `--json`.
 
 ## Step 6: Verify everything
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capyai",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "description": "Unofficial Capy.ai CLI for agent orchestration with quality gates",
   "bin": {

package/skills/capy/SKILL.md

@@ -28,16 +28,16 @@ Do NOT use capy when:
 
 Understand these three objects before doing anything.
 
-**Thread** — A Captain session. You give it a prompt, it plans and may spawn multiple tasks. Threads have long opaque IDs (UUIDs). Terminal states: `idle`, `archived`, `completed`. You start threads with `capy captain`.
+**Thread** — A Captain session. This is your primary interface. You give it a prompt, it plans and may spawn multiple tasks. Threads have long opaque IDs (UUIDs). Terminal states: `idle`, `archived`, `completed`. Start threads with `capy captain`. Use Captain for almost everything.
 
-**Task** — A single unit of coding work. Has a short identifier like `SCO-15`. A task produces a diff (code changes) and optionally a pull request. Terminal states: `needs_review`, `archived`, `completed`, `failed`. You start standalone tasks with `capy build`.
+**Task** — A single unit of coding work. Has a short identifier like `SCO-15`. A task produces a diff (code changes) and optionally a pull request. Terminal states: `needs_review`, `archived`, `completed`, `failed`. Captain spawns tasks automatically. You can also start standalone tasks with `capy build` for small, isolated work where Captain is overkill (a one-file fix, a config change).
 
 **Jam** — An execution run inside a task. Each jam has a model, a status, and credit usage. A task can have multiple jams (one per retry). When `jam.status` is `"idle"` and credits are zero, that jam is finished. The task is done working. You cannot send it more messages.
 
 **Lifecycle:**
 
 ```
-[you] captain/build
+[you] capy captain (default) or capy build (small isolated tasks)
   → [capy agent] in_progress (writing code, running tests)
   → [capy agent] needs_review (agent stopped, diff may exist)
   → [you] check diff, create PR, run quality gates
@@ -97,9 +97,11 @@ These are the mistakes agents make. Do not make them.
 
 ## Workflow: Start new work
 
+Default to `capy captain`. It has codebase context and plans its own approach. Only use `capy build` for small isolated tasks (one-file fix, config tweak).
+
 ```bash
-# 1. Start a Captain thread
-RESULT=$(capy captain "Implement feature X. Files: src/foo.ts, src/bar.ts. Include tests. Run tests before finishing." --json)
+# 1. Start a Captain thread (the default for almost everything)
+RESULT=$(capy captain "We need feature X implemented. Make sure tests pass and CI is green." --json)
 THREAD_ID=$(echo "$RESULT" | jq -r '.id')
 
 # 2. Wait for completion (use 600s for Captain, 300s for Build)
@@ -205,8 +207,8 @@ All commands support `--json` for structured output. All errors return `{ "error
 ### Start work
 
 ```bash
-capy captain "<prompt>" --json          # → { id, url }
-capy build "<prompt>" --json            # → { id, identifier, status }
+capy captain "<prompt>" --json          # → { id, url } — default, use for almost everything
+capy build "<prompt>" --json            # → { id, identifier, status } — small isolated tasks only
 ```
 
 Model shortcuts: `--opus`, `--sonnet`, `--mini`, `--fast`, `--kimi`, `--gemini`, `--grok`, `--qwen`, or `--model=<id>`.
@@ -257,26 +259,22 @@ capy pool [status|set|test|instances|instance|clear]  # → warm pool management
 
 ## Prompting tips
 
-Captain and Build need different prompting styles.
-
-**Captain** has full codebase context and plans its own approach. Tell it WHAT to accomplish, not HOW. Link the issue, set the quality bar, get out of its way.
+You should almost always use Captain. It has full codebase context and plans its own approach. Tell it what to accomplish, not how. Link the issue, set the quality bar, get out of its way.
 
-Bad: `"Fix CI for crypto-trading pack. The changeset file is missing. Add a changeset entry for @veto/crypto-trading with patch bump. Run 'npx changeset status' to validate. Files: packages/crypto-trading/."`
+Bad (over-specifying): `"Fix CI for crypto-trading pack. The changeset file is missing. Add a changeset entry for @veto/crypto-trading with patch bump. Run 'npx changeset status' to validate. Files: packages/crypto-trading/."`
 
-Good: `"We have a CI failure on the crypto-trading pack — missing changeset. Fix it. Reference: PLW-201. Don't finish until CI is green and tests pass."`
+Good: `"CI is failing on the crypto-trading pack, missing changeset. Fix it. Reference: PLW-201. Don't come back until CI is green and tests pass."`
 
-Good: `"https://linear.app/plaw/issue/PLW-201 — get this done. Make sure all tests pass, CI is green, and code review comes back clean."`
+Good: `"https://linear.app/plaw/issue/PLW-201 — get this done. All tests passing, CI green, code review clean."`
 
 Captain prompts should include:
 - What the problem or goal is (natural language)
 - A link to the issue if one exists (GitHub, Linear)
 - The quality bar ("tests pass", "CI green", "code review clean")
 
-Do NOT include specific files, specific commands, or implementation details. Captain figures that out.
-
-**Build** is isolated and has no codebase context. Be specific. Name the files, the commands, the acceptance criteria.
+Do NOT tell Captain which files to touch, which commands to run, or how to implement. It has the codebase. It figures that out.
 
-Good: `"Fix CI for crypto-trading pack. The changeset file is missing. Add a changeset entry for @veto/crypto-trading with patch bump. Run 'npx changeset status' to validate. Files: packages/crypto-trading/. Reference: PLW-201."`
+**Build** is the exception, not the rule. Use it only for small isolated tasks where Captain is overkill. Build has no codebase context, so be specific: name the files, the commands, the acceptance criteria.
 
 ## Triggers