Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions .agents/skills/orchestrate/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
name: orchestrate
description: >
Orchestrate sub-agents for large tasks inside a single environment: plan,
delegate coding to cheap/fast models, parallelize the critical path, keep
reviews lean, and close every loop. Use when acting as an orchestrator or
writing a kickoff for one. Prefer implement when fan-out does not clearly pay.
---

# Orchestrate

This is the kody `orchestrate` skill, scoped to `@kodycodes/cli`.

Fan out **sub-agents inside one environment** (shared checkout). This repo is
one package; multi-environment fleets are out of scope here.

Two modes: **be** the orchestrator, or **spawn** one (smarter model) if you are
optimized for cheap/fast execution.

## Defaults (override only if the user says so)

- **Prefer implement.** Fan out only when non-conflicting workstreams clearly
beat one implementer. Sequential slices → implement (or one implementer).
- **No orchestration theater.** Ban review → recheck → final → CI-watch chains
per slice. **One** hard-to-reverse review before merge.
- **One CI wait path** — parent `gh pr checks` _or_ a ci-watcher, not both.
- **Targeted tests while iterating;** `npm run validate` before ready-for-review.
- Close loops yourself — don't leave humans as the relay.

## Role

1. Plan, delegate, integrate, ship. Bulk-code only when fan-out costs more.
2. Frontier model orchestrates; cheap/fast models implement (prefer Grok 4.5 /
`composer-2.5-fast` for mechanical work).
3. Critical path first; parallelize non-conflicting files; serialize shared
ones.
4. **You do final QA.** Never declare done from sub-agent claims.

## Fan-out (when it pays)

- One implementer per independent vertical slice
- Cheap sweeps (parity / errors)
- Audit → prioritized cleanup, then parallel cleanup agents
- One independent "hard-to-reverse / security" review before merge

## Kickoff (when spawning an orchestrator)

Keep it short: goals + constraints + out-of-scope; "you orchestrate, don't bulk
code"; preferred implementer model; single-environment; done = falsifiable.
Point at this skill.
61 changes: 61 additions & 0 deletions .agents/skills/ship-pr/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
---
name: ship-pr
description: >
Babysit a PR: iterate with AI reviewers and CI until green, get it ready,
optionally squash-merge as Kody and watch the publish, then send a Discord
summary. Medium risk waits for AI reviewer(s) and addresses valid feedback.
Use when a pull request needs to be shepherded to done.
---

# Ship PR

This is the kody `ship-pr` skill, scoped to `@kodycodes/cli`.

## Risk → merge authority

Self-assess; user policy overrides.

- **Low** — green CI; nits ignorable; squash-merge when policy allows.
- **Medium** — wait for AI reviewer(s); address **valid** feedback (ignore
insignificant nits / already-fixed / wrong); then merge when policy allows.
- **High** — leave ready-for-review unless the user granted merge authority.

## Loop

1. Mark ready — `kody:@kentcdodds/github/pr/set-review-status`
`{ prUrl, status: 'ready' }` (or owner/repo/prNumber).
2. Wait for CI — `gh pr checks` (or compose `loop-on-ci` / `fix-ci`).
3. Fix failures; for **medium+**, wait on AI reviewer(s) and address valid
feedback. Rebase only when actually unmergeable. Local gate is
`npm run validate`. If the change touches login / MCP protocol, also smoke
`whoami`, `search`, and `execute` against `https://kody.codes/mcp`.
4. Green + (medium+: valid feedback cleared) → break.
5. Push → repeat.

## Gates ≠ CI

Blocked on a release / trusted-publishing / calendar gate → **end the run**
and schedule a wake. Don't sleep-poll or code-thrash an intentional time
window.

## Merge / publish

When policy + risk allow: squash-merge via `kody:@kentcdodds/github/pr/merge`
`{ prUrl, mergeMethod: 'squash' }`. `main` conventional commits publish
`@kodycodes/cli` through semantic-release. Useful: `pr/get-checks`,
`request`, `graphql` on the same package.

## Done → Discord

Always summarize (merged or not) with agent / PR / CI / publish links:

```javascript
import postMessage from 'kody:@kentcdodds/discord/post-message'

export default async function main() {
return postMessage({
channelId: '1491568683737157683',
content: '…summary with links…',
})
}
```
11 changes: 11 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# @kodycodes/cli

Official Kody MCP client. `npm run validate` is the local gate (typecheck,
tests, build).

Skills:

- [ship-pr](./.agents/skills/ship-pr/SKILL.md) — babysit a PR to green, then
merge when policy allows
- [orchestrate](./.agents/skills/orchestrate/SKILL.md) — fan out sub-agents
inside one checkout when it clearly pays
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

Turn one-off agent work into something you can rerun: a local MCP client for
[Kody](https://kody.codes) with login, OS keychain token storage, `search`, and
`execute`.
`execute`. Talks MCP `2026-07-28` (Kody's stateless `/mcp` lane) and logs in
with Client ID Metadata Documents (SEP-991).

```bash
npx @kodycodes/cli login
Expand All @@ -25,7 +26,7 @@ Or run via `npx @kodycodes/cli` without a global install.

| Command | Purpose |
| --- | --- |
| `kody login` | Browser OAuth (DCR + PKCE). Stores access and refresh tokens. |
| `kody login` | Browser OAuth (CIMD + PKCE). Stores access and refresh tokens. |
| `kody logout` | Deletes stored credentials. |
| `kody status` | Shows login state without printing secrets. |
| `kody whoami` | Confirms the MCP connection and lists tools. |
Expand All @@ -45,7 +46,7 @@ Credentials are stored in the OS secret store:
- Linux: Secret Service / libsecret

If the keychain is unavailable (common on headless Linux), the CLI writes a
`0600` file under `$XDG_CONFIG_HOME/kody` (or `%APPDATA%\\kody` on Windows,
`0600` file under `$XDG_CONFIG_HOME/kody` (or `%APPDATA%\kody` on Windows,
`~/Library/Application Support/kody` on macOS). Tokens are never printed.

Access tokens refresh automatically on expiry or HTTP 401.
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@
"access": "public"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.30.0",
"@modelcontextprotocol/client": "2.0.0",
"@napi-rs/keyring": "^1.3.0"
},
"devDependencies": {
Expand Down
2 changes: 1 addition & 1 deletion skills/kody/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ npx @kodycodes/cli skill install
kody login
```

The CLI opens a browser for Kody OAuth (PKCE + dynamic client registration).
The CLI opens a browser for Kody OAuth (PKCE + Client ID Metadata Documents).
If a browser cannot open, it prints the URL. Tokens (access + refresh) are
stored in the OS keychain on macOS, Windows, and Linux. Linux without Secret
Service falls back to a `0600` file under `$XDG_CONFIG_HOME/kody`.
Expand Down
Loading