capyai 0.5.1 → 0.5.3

package/AGENTS.md

@@ -50,17 +50,22 @@ Verify: `capy status --json` should return `{ "threads": [...], "tasks": [...] }
 
 If it returns `{ "error": ... }`, the API key or project ID is wrong. Ask the user.
 
-## Step 4: Install skill
+## Step 4: Load the operating manual
+
+`skills/capy/SKILL.md` is the full operating manual: object model, decision trees, workflows, guardrails, commands. You need it in your context.
 
 ```bash
 npx skills add yazcaleb/capy-cli
 ```
 
-This adds the `capy` skill to your skills directory so you have the full command reference available in context.
+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
+cp skills/capy/SKILL.md <your-agent-skills-dir>/capy.md
+```
 
-## Step 5: MCP server (if you support MCP)
+## Step 5: MCP server (optional)
 
-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
 {
@@ -111,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 don't support MCP, skip this step. The CLI works everywhere.
+If you don't use MCP, skip this step. The CLI from Step 2 works everywhere with `--json`.
 
 ## Step 6: Verify everything
 
@@ -129,10 +132,4 @@ You are now fully configured.
 
 ## Usage
 
-For the full operating manual (commands, workflows, decision trees, guardrails), install the capy skill:
-
-```bash
-npx skills add yazcaleb/capy-cli
-```
-
-This loads `skills/capy/SKILL.md` into your context with everything you need to orchestrate Capy agents.
+Read `skills/capy/SKILL.md`. That's it. Everything you need to orchestrate Capy agents is in that file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capyai",
-  "version": "0.5.1",
+  "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