capyai 0.5.0 → 0.5.2

package/AGENTS.md

@@ -50,15 +50,34 @@ 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
 
+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.
+
+Pick whichever method works for your setup:
+
+**Option A: skills.sh (if supported)**
 ```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.
+**Option B: Copy to your skills/memory folder**
+If you have a persistent skills directory or memory system, copy the file directly:
+```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
+```
+
+**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
 
-## Step 5: MCP server (if you support MCP)
+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.
+
+**If you prefer MCP** (Cursor, Claude Desktop, agents with MCP support):
 
 Add this to your MCP configuration:
 
@@ -113,7 +132,7 @@ Config file locations:
 
 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 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.
 
 ## Step 6: Verify everything
 
@@ -129,10 +148,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.0",
+  "version": "0.5.2",
   "type": "module",
   "description": "Unofficial Capy.ai CLI for agent orchestration with quality gates",
   "bin": {

package/skills/capy/SKILL.md

@@ -257,17 +257,26 @@ capy pool [status|set|test|instances|instance|clear]  # → warm pool management
 
 ## Prompting tips
 
-When writing prompts for `capy captain` or `capy build`, be specific. The Capy agent is another AI. Vague prompts produce vague results.
+Captain and Build need different prompting styles.
 
-Bad: `"Fix the CI issue"`
+**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.
 
-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."`
+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/."`
+
+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: `"https://linear.app/plaw/issue/PLW-201 — get this done. Make sure all tests pass, CI is green, and code review comes back 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")
 
-Always include:
-- Which files to touch
-- What the acceptance criteria are
-- What commands to run to verify
-- References to related issues or tasks
+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.
+
+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."`
 
 ## Triggers