allye-pi 1.5.1

package/skills/sandbox/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: sandbox
+description: Open-ended ideation and research before committing to scope. Use when the user has a vague goal and wants to think out loud, explore directions, or research before defining what to build — not yet ready for Product Planning's Epic/Feature/Story structure.
+version: "1.3"
+category: methodology
+---
+
+# Sandbox / Discovery
+
+This is the entry point for ideas that aren't ready to become work items yet. Use it when the user wants to explore, not commit — Product Planning already assumes a direction has been chosen; this skill is where that direction gets found.
+
+<!-- adapted from superpowers:brainstorming (MIT) -->
+<HARD-GATE>
+Do not create any Allye work item, and do not treat any direction as decided, until the user has explicitly approved it. This skill's only output is a Discovery Doc and a handover — never an Epic, Feature, or Story. If you catch yourself about to call `work_create`, stop: that's Product Planning's job, one conversation later.
+</HARD-GATE>
+
+## 1. The core rule: ask, don't decide
+
+You never unilaterally pick a direction. When there's a fork, ask — one focused question at a time, never several forks stacked into one message. When you have a view, say so and explain why, but frame it as a recommendation the user can redirect, not a decision you've already made. (For *how* to ask — prose vs. the `AskUserQuestion` tool — see `using-allye`'s "Asking Questions" section; it's a global rule, not repeated here.)
+
+<!-- adapted from superpowers:brainstorming (MIT) — anti-rationalization table -->
+### Red flags — these thoughts mean stop and ask instead
+
+| Thought | Reality |
+|---|---|
+| "This is obviously what they want" | Obvious to you isn't the same as confirmed. Ask. |
+| "I'll just explore this direction and show them" | Exploring silently is still deciding silently — narrate the fork before you go down it. |
+| "We've been going back and forth a lot, let me just pick" | Fatigue isn't consent. If the user wants you to decide, they'll say so — that's a valid answer to a question, not a reason to stop asking. |
+| "This detail is too small to ask about" | Small decisions compound. If it would surprise the user later, it's worth a quick check now. |
+
+### When it's fine to just proceed
+
+<!-- adapted from trailofbits/skills ask-questions-if-underspecified (CC-BY-SA-4.0) — adapted as a rubric, not their original text -->
+Not every gap needs a question. Ask when the answer would change *what* gets built or *which direction* gets explored. Don't ask when:
+- The gap is a well-established default with no real controversy — state the assumption instead of asking about it
+- The user already answered a broader version of the question and this is a narrower instance of the same answer
+- Asking would just be confirming something the user's own message already made unambiguous
+
+## 2. Research (optional, user-triggered, parallel is fine)
+
+If the direction needs facts to evaluate — how a technology actually works, what a public repo actually does, what the current landscape looks like — offer to research before continuing the discussion, rather than reasoning from assumption.
+
+- **Web research** → dispatch the `deep-search` agent (`Agent` tool) with a single, explicit objective. It's bounded and doesn't need to ask you anything mid-task, which is what makes it safe to dispatch.
+- **Public repo analysis** → dispatch the `code-analyzer` agent (`Agent` tool) with the repo URL, a specific objective, and the session scratchpad path (it only clones under that path, and will refuse to fall back to `/tmp` if you omit it). It reads thoroughly, reports, and deletes the clone unconditionally — you never touch the clone yourself.
+
+Both can run in parallel if you need both kinds of research at once — dispatch them in the same turn.
+
+<!-- adapted from humanlayer/humanlayer research_codebase (Apache-2.0) -->
+**Keep research and direction-setting separate.** A research agent documents what exists — it does not recommend what to do about it. When findings come back, bring them into the conversation and let the user (with your input) decide what they mean for the direction — don't let a research agent's report silently become the decision.
+
+## 3. Exit: the Discovery Doc
+
+When a direction is approved — explicitly, by the user, not inferred — synthesize the conversation into a Discovery Doc:
+
+1. **What goes in it:** the approved direction and why; paths that were explored and rejected, with the reason (the next phase should never accidentally re-propose something already ruled out); research findings, if any, with their sources; prototypes, if any.
+2. **Where it goes:** call `doc_full_tree` first. Propose a parent location based on what you see — don't guess blindly and don't default to the root. Get the user's explicit confirmation of placement before creating anything.
+3. **Create it:** `doc_create` (type `guide` or `page`, needs an emoji).
+4. **Hand off:** emit a `discovery-to-planning` handover — see the `handover-protocol` skill for the shared marker format, and its `references/discovery-to-planning.md` for this handover's specific template. Reference the Discovery Doc; don't duplicate its content into the handover.
+
+## 4. What this skill is not
+
+This is not Technical Planning — no stack decisions, no architecture, no tasks here. It is not Product Planning — no Epic/Feature/Story structure gets created here (see the HARD-GATE above). If the user arrives already knowing exactly what they want and just needs it turned into work items, route to `product-planning` directly instead — Sandbox isn't the right entry point for that.

package/skills/setup/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: setup
+description: First-time setup for the Allye plugin. Uses OAuth for ALL platforms — no PAT.
+version: "1.2"
+category: bootstrap
+---
+
+# Allye Setup
+
+<EXTREMELY_IMPORTANT>
+## Allye ALWAYS uses OAuth. Never ask for a PAT.
+
+The setup flow depends on whether the platform supports native MCP OAuth:
+
+- **Claude Code / Claude Desktop** → OAuth is automatic via `.mcp.json`. No setup needed.
+- **All other platforms** (OpenCode, Cursor, Codex, Gemini, etc.) → Run the OAuth browser login script.
+
+**NEVER ask the user for a PAT. NEVER mention PAT as an option.**
+</EXTREMELY_IMPORTANT>
+
+## Step 1: Detect Platform
+
+Check which platform/agent is running. You can infer this from:
+- The environment (Claude Code has `CLAUDE_CODE` env, Claude Desktop has specific hooks)
+- The available tools and context
+- Or simply ask: "Which platform are you using?"
+
+## Step 2A: Claude Code / Claude Desktop (Native OAuth)
+
+If the user is on Claude Code or Claude Desktop:
+
+> **Allye is already configured!** The plugin's `.mcp.json` handles OAuth automatically.
+>
+> The first time you use a Allye tool, your browser will open for login.
+> Just start using Allye — try asking me to search memories or list work items.
+
+**Stop here. No further setup needed.**
+
+## Step 2B: Other Platforms (OAuth via Browser Login Script)
+
+For OpenCode, Cursor, Codex, Gemini, or any platform without native MCP OAuth:
+
+Tell the user:
+
+> I'll run the Allye OAuth login to connect your account via browser.
+
+### Run the OAuth login script:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/oauth-login.sh"
+```
+
+If `CLAUDE_PLUGIN_ROOT` is not set, find the script:
+
+```bash
+SCRIPT=$(find ~/.claude/plugins -name "oauth-login.sh" -path "*/allye*" 2>/dev/null | head -1) || SCRIPT=$(find . -name "oauth-login.sh" 2>/dev/null | head -1); echo "$SCRIPT"
+```
+
+Then run it:
+
+```bash
+bash "$SCRIPT"
+```
+
+The script will:
+1. Open the browser for Allye OAuth login
+2. Start a local callback server on port 9316
+3. After the user logs in and selects a team, capture the authorization code
+4. Exchange the code for tokens
+5. Output `ALLYE_ACCESS_TOKEN=...` and `ALLYE_REFRESH_TOKEN=...`
+
+### Configure the platform with the obtained token:
+
+**For OpenCode:**
+The `opencode.json` manifest uses `${ALLYE_ACCESS_TOKEN}`. Set the env var:
+
+```bash
+export ALLYE_ACCESS_TOKEN="<the token from the script>"
+```
+
+Or update `opencode.json` directly with the token.
+
+**For Cursor:**
+Add MCP server in Cursor settings (Settings → MCP Servers):
+- Name: `allye-mcp`
+- URL: `https://mcp.allye.app/mcp`
+- Headers: `Authorization: Bearer <token>`
+
+**For other platforms:**
+Configure the MCP connection with:
+- URL: `https://mcp.allye.app/mcp`
+- Authorization header: `Bearer <token>`
+
+### Confirm setup:
+
+> **Allye connected via OAuth!**
+>
+> Start a new session to activate the Allye tools.
+
+## Step 3: Delivery configuration
+
+Ask once, here, rather than at every dispatch. Five parallel stories would otherwise mean
+ten identical questions whose answer never varies.
+
+Check whether it already exists before asking anything:
+
+```
+user_config(action: "list")
+```
+
+If a document named `Allye Delivery Configuration` is present, show it and ask whether to
+change it. Otherwise, ask the questions below — one at a time — and create it.
+
+**Question 1 — which agent runs which phase?** Offer the phases that can differ (planning,
+technical planning, execution, review, correction) and let the user assign an agent kind to
+each. The default is the agent they are running now, for every phase; accepting that default
+is a completely reasonable answer and should take one word.
+
+**Question 2 — what arguments does each agent need?** Model selection is not uniform: what
+is `--model sonnet --permission-mode auto` for one agent is different syntax for the next.
+Store the argument string verbatim; it is passed through unchanged.
+
+**Question 3 — per repo, what is the base branch, and which gitignored files must a fresh
+worktree receive?** A worktree inherits neither, and an executor that fails on a missing
+`.env` reports a bug that is not one.
+
+**Question 4 — who satisfies each stage after review?** Only ask this when the team's pipeline
+has stages between the review gate and done: run `work_statuses()` and look. A Solo or Startup
+board goes straight from review to done and needs nothing here — **skip the question entirely
+rather than asking it and recording an empty table.**
+
+Where there are stages, offer three answers per stage:
+
+- **`agent`** — the Orchestrator satisfies it and advances. Needs a command, the same way a task
+  needs one (`verification-loop` §1): red-capable, deterministic, fast, agent-runnable.
+- **`ci`** — an external system satisfies it. Record how to read the result; the Orchestrator
+  waits rather than acting.
+- **`human`** — the Orchestrator stops and hands over.
+
+Lead with a recommendation so accepting takes one word: scans and automated test suites are
+usually `agent` or `ci`; anything that deploys, or that validates in a deployed environment, is
+`human` unless the team says otherwise.
+
+Create it:
+
+```
+user_config(
+  action: "create",
+  name: "Allye Delivery Configuration",
+  content: "{the document below}"
+)
+```
+
+Note the field is `name`, not `title` — this is the one tool in the suite that differs.
+
+### Document format
+
+```markdown
+# Allye Delivery Configuration
+
+## Phase routing
+
+| Phase | Agent kind | Native args |
+|---|---|---|
+| product-planning | claude | --model sonnet --permission-mode auto |
+| technical-planning | claude | --model sonnet --permission-mode auto |
+| execution | opencode | |
+| review | claude | --model sonnet --permission-mode auto |
+| correction | opencode | |
+
+## Repositories
+
+| Repo | Base branch | Install command | Copy into a fresh worktree |
+|---|---|---|---|
+| allye-plugin | main | | |
+| allye-api | develop | bun install | .env |
+
+## Concurrency
+
+Default parallel stories: 3
+
+## Pipeline handoff
+
+| Status | Satisfied by | Command or signal |
+|---|---|---|
+| security_scan | agent | just security-scan |
+| qa_testing | agent | just test:e2e |
+| deploy_staging | ci | GitHub Actions `deploy-staging` |
+| deploy_prod | human | |
+
+An unmapped status means **`human`**. Stopping is the safe default: an agent that advances
+past a gate nobody told it about has claimed work passed a check that never ran.
+
+Omit this section entirely when the pipeline runs straight from review to done.
+```
+
+An empty cell means "nothing required" — leave it empty rather than writing "none", so the
+table stays scannable.
+
+### Preflight before routing a phase to a non-Claude agent
+
+A dispatched agent that cannot reach Allye cannot read the story, move a status, or save the
+memory the Orchestrator collects its result from — the dispatch will appear to succeed and
+produce nothing. Before recording a non-Claude agent for any phase, confirm that agent has
+Allye configured: the MCP connection, and for OpenCode the `allye-opencode` package. If it
+does not, say so and point at the matching guide in `docs/install-*.md` rather than recording
+a route that will fail on first use.
+
+Platform capability also constrains the map. OpenCode has six agent personas; Cursor, Codex,
+and Gemini CLI have one agent and no picker — routing a specific persona to them silently
+does nothing.
+
+## Token Refresh
+
+OAuth tokens expire. When a token expires:
+- **Claude Code/Desktop**: Automatic refresh via OAuth flow
+- **Other platforms**: Run the login script again: `bash scripts/oauth-login.sh`
+
+## Error Handling
+
+- `python3` not found → Required for the OAuth callback server. Install Python 3.
+- `openssl` not found → Required for PKCE. Install OpenSSL.
+- Browser doesn't open → Copy the URL from the terminal and open manually.
+- Port 9316 in use → Run with a different port: `bash scripts/oauth-login.sh 9317`
+- `jq` not found → `brew install jq` / `sudo apt install jq`

package/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: tdd-workflow
+description: Test-Driven Development discipline for AI agents. Red-Green-Refactor cycle, detection heuristic, and anti-patterns. Use when implementing features or fixing bugs.
+version: "1.1"
+category: methodology
+---
+
+# TDD Workflow
+
+TDD is not about writing tests — it's about **designing code through tests**.
+
+---
+
+## 1. TDD Detection Heuristic
+
+Before implementing anything, ask:
+
+> **Can I write `expect(fn(input)).toBe(output)` before writing `fn`?**
+
+- **Yes** → TDD is mandatory. Follow Red → Green → Refactor.
+- **No** → Write tests after implementation, but always write tests.
+
+### When TDD applies (test first)
+
+- Pure functions and business logic
+- Data transformations and parsing
+- Validation rules
+- API endpoint behavior
+- Database queries and mutations
+- State management logic
+- Utility functions
+- Algorithm implementations
+
+### When TDD doesn't apply (test after)
+
+- UI layout and styling
+- Infrastructure and configuration
+- Third-party integrations (mock boundaries, test your adapter)
+- File system operations
+- Environment setup scripts
+- One-off data migrations
+
+<EXTREMELY_IMPORTANT>
+Even when TDD doesn't apply, you MUST still write tests.
+The only question is whether the test comes before or after the implementation.
+"No tests needed" is never an acceptable answer.
+</EXTREMELY_IMPORTANT>
+
+---
+
+## 2. The Red-Green-Refactor Cycle
+
+### Red — write a failing test
+
+Write a test that describes the target behavior, not the implementation:
+
+```javascript
+test("should return 404 when user not found", async () => {
+  const response = await request(app).get("/users/nonexistent");
+  expect(response.status).toBe(404);
+  expect(response.body.error).toBe("User not found");
+});
+```
+
+**Run the test. It MUST fail.** If it passes, either the functionality already exists (don't reimplement it) or the test is wrong (it's not testing what you think).
+
+### Green — make it pass
+
+Write the **minimum code** to make the test pass:
+
+<HARD-GATE>
+Rules for the Green phase:
+1. Do NOT add features the test doesn't require
+2. Do NOT optimize prematurely
+3. Do NOT handle edge cases not covered by tests — write more tests first
+4. Do NOT refactor during Green — that's the next phase
+5. It's OK if the code is ugly — Green is about correctness, not beauty
+</HARD-GATE>
+
+**Run the test. It MUST pass.**
+
+### Refactor — clean up
+
+With green tests as your safety net: remove duplication, improve naming, simplify logic, extract functions where the code is too long, apply patterns where they genuinely help.
+
+**Run tests after EVERY change.** A failing test means you broke something — undo and try again.
+
+### Repeat
+
+Write the next test for the next behavior. Continue the cycle until all acceptance criteria are met.
+
+---
+
+## 3. Test Quality
+
+- **Assert on behavior, not implementation** — `should return user profile for valid ID`, not `should call userRepository.findById`. Tests coupled to implementation break on every refactor.
+- **One assertion per concept.** A test that checks unrelated things (fields set *and* an email was sent) hides which concept broke when it fails — split into separate tests.
+- **Cover the edges** after the happy path passes: empty inputs, invalid inputs, boundary values, error conditions, concurrent access where applicable.
+- **Name tests as specifications** — `should throw validation error when email is invalid`, `should retry request up to 3 times on timeout`.
+
+---
+
+## 4. Rules — Non-Negotiable
+
+<HARD-GATE>
+1. **Never delete a failing test.** If a test fails, either fix the code or fix the test — but understand WHY it fails first. Deleting tests hides bugs.
+
+2. **Never suppress type errors.** No `@ts-ignore`, no `# type: ignore`, no `as any`. Type errors are bugs caught early. Fix them.
+
+3. **Never commit with failing tests.** All tests must pass before a task is marked as done. No exceptions.
+
+4. **Never mock what you don't own.** Mock your adapters, not third-party libraries directly. If the library changes, your mock won't catch it.
+
+5. **Tests must be deterministic.** No flaky tests. No tests that depend on time, network, or random values without controlling them.
+</HARD-GATE>
+
+---
+
+## 5. Testing Patterns
+
+Structure each test **Arrange-Act-Assert**: set up state, perform the one action under test, assert the result.
+
+Use the simplest test double that works:
+
+| Double | When to use |
+|--------|-------------|
+| **Stub** | Return a fixed value. Use for dependencies whose output you control. |
+| **Spy** | Verify a call was made. Use when the side effect matters. |
+| **Mock** | Set expectations upfront. Use sparingly — prefer stubs + assertions. |
+| **Fake** | Lightweight implementation (e.g., in-memory DB). Use for integration tests. |
+
+Test at your system's boundaries — validate at the input boundary, assert at the output boundary — rather than reaching into the middle.
+
+---
+
+## 6. When the Cycle Feels Wrong
+
+| Feeling | Likely cause | Fix |
+|---------|-------------|-----|
+| "I can't write a test first" | You don't understand the requirements yet | Go back to the task description. Clarify with the user. |
+| "The test is too complex" | The function does too much | Break the function into smaller pieces. Test each piece. |
+| "I need to test private methods" | The public interface is too coarse | Refactor to expose behavior through the public API. |
+| "Tests are slow" | Too many integration tests, not enough unit tests | Apply the test pyramid: many unit, some integration, few E2E. |
+| "Tests break when I refactor" | Tests are coupled to implementation | Rewrite tests to assert on behavior, not implementation details. |