@firatcand/roster 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firat Dogan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+![banner](https://raw.githubusercontent.com/firatcand/roster/7095215fd4224709f47d69270f35201b1c3206ce/roster-banner%402x.png)
+
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+# Roster
+
+> A CLI that installs and scaffolds an opinionated multi-agent workspace for Claude Code today, with Codex CLI and Gemini support landing in v0.2 — role-based agents for GTM, product, design, and ops, with a reinforcement loop that compounds learning.
+
+## What is this?
+
+`@firatcand/roster` is an npm CLI. You run it once and it does two things:
+
+1. **`roster install`** — copies a curated set of skills and agent definitions into your AI coding tool's config dir. Detects and installs to `~/.claude/`, `~/.codex/`, and `~/.gemini/`.
+2. **`roster init`** — scaffolds a structured agent-team workspace in any directory. v0.1 produces the minimal scaffold (`CLAUDE.md` + `projects/_demo/`); v0.2 adds the full tree (function dirs, role-based agents, maintenance agent, reinforcement agent).
+
+The workspace it scaffolds separates **substrate** (strategic context: brand voice, ICPs, messaging) from **artifacts** (daily output: emails, posts, components), and runs work through named YAML **plans** that are deterministic, auditable, and schedule-friendly.
+
+If you're a solo founder or ≤5-person team using Claude Code (or Codex / Gemini) and you need outbound, content, design, and ops work done without losing context between sessions — this might fit.
+
+## Getting started
+
+First-time install and first run — under 10 minutes on a Mac with Node ≥ 22.
+
+```bash
+# 1. Install skills + agents into your AI tool's config dir
+npx @firatcand/roster install
+
+# 2. Scaffold a workspace in a fresh directory
+mkdir my-team && cd my-team
+npx @firatcand/roster init
+
+# 3. Open Claude Code in that directory
+claude
+
+# 4. Run the demo SDR plan
+/sdr run cold-outreach for _demo
+
+# 5. Read the run log and provide feedback — lessons surface
+#    in dreamer/pending/ on the next nightly reinforcement pass.
+```
+
+> Until v0.1 is published to npm, install locally with `npm pack && npm install -g firatcand-roster-*.tgz` from a clone. See [docs/roadmap.md](docs/roadmap.md) for publish status.
+
+[docs/HOWTO.md](docs/HOWTO.md) has the long-form step-by-step.
+
+### What `roster install` looks like
+
+```
+$ npx --yes @firatcand/roster install --all
+
+roster v0.1.0
+Multi-agent workspace scaffolder for Claude Code, Codex CLI, and Gemini.
+
+✓ Claude Code — 3 skills → ~/.claude/skills, 7 agents → ~/.claude/agents
+✓ Codex CLI — 4 skills → ~/.codex/skills, 7 agents → ~/.codex/agents
+✓ Gemini CLI — 3 skills → ~/.gemini/extensions, 7 agents → ~/.gemini/agents
+
+Next: roster init to scaffold a workspace.
+```
+
+Without `--all`, you'll get an interactive checkbox to pick which tools to receive the skills + agents. Exit codes: 0 success, 1 error, 2 cancelled, 3 no tools detected.
+
+## Subcommands
+
+| Command | What it does |
+|---|---|
+| `roster install` | Detect installed AI tools, prompt for selection, copy skills + agents into each tool's config dir. Idempotent. |
+| `roster install --all` | Install to every detected tool, non-interactive (good for CI / scripted migration). |
+| `roster install --tool <name>` | Install to a single named tool (`claude`, `codex`, or `gemini`), non-interactive. |
+| `roster init [name]` | Scaffold the agent-team workspace into CWD. Substitutes `{{PROJECT_NAME}}`. |
+| `roster doctor` | Audit installed skills/agents per AI tool; exits non-zero on drift. Includes a Scheduling section that runs `schedule validate` against the current workspace. |
+| `roster schedule validate` | Validate every `roster/<function>/schedules.yaml` file in the workspace. `--json` / `--silent` / `--cwd <dir>`. Exits non-zero on schema or cron errors. |
+| `roster --help` / `--version` | Usage + version from `package.json`. |
+
+## Tool support
+
+| Tool | Status | Skills installed to | Agents installed to |
+|---|---|---|---|
+| Claude Code | Supported | `~/.claude/skills/<skill>/` (directory per skill) | `~/.claude/agents/<agent>.md` |
+| Codex CLI | Supported | `~/.codex/skills/<skill>/` (directory per skill) | `~/.codex/agents/<agent>.md` |
+| Gemini CLI | Supported | `~/.gemini/extensions/<skill>/` (directory per skill) | `~/.gemini/agents/<agent>.md` |
+| Cursor | **Out of scope** — see [docs/roadmap.md](docs/roadmap.md) | — | — |
+
+Detection is presence-only: roster considers a tool installed if its config root exists. Override via `ROSTER_CLAUDE_HOME` / `ROSTER_CODEX_HOME` / `ROSTER_GEMINI_HOME` (used by the test suite).
+
+## What roster installs
+
+`roster install` copies three skills and seven agents into each detected tool's config dir. Skills are the entry points (one per agent function); agents are the building blocks the skills call.
+
+**Skills**
+
+| Skill | Purpose |
+|---|---|
+| `chief-of-staff` | Repo maintenance for roster workspaces — create, archive, rename, and audit projects, agents, and functions. Wraps `scripts/` with confirmation gates for destructive operations. |
+| `dreamer` | Off-hours reflection. Reads recent runs + feedback, detects recurring patterns, drafts lesson candidates, and writes approved lessons to the right playbook scope. The only agent that writes to playbook files. |
+| `sdr` | Cold outreach for a project — find prospects matching an ICP, enrich, draft personalized first-touch messages in the project's voice, and route through HITL approval. |
+
+**Agents** (called by skills, not invoked directly)
+
+| Agent | Owner skill | Purpose |
+|---|---|---|
+| `critic` | `sdr` | Reviews drafts for tone, brand fit, risk, compliance. Returns pass/fail with specific feedback. Does not rewrite. |
+| `enricher` | `sdr` | Fills missing fields on prospects (recent posts, company news) via Apollo, HeyReach, web search. Does not score or contact. |
+| `prospector` | `sdr` | Finds prospects matching ICP criteria. Read-only — no enrichment beyond search, no contact, no CRM writes. |
+| `writer` | `sdr` | Drafts a single first-touch message for a single prospect using enrichment context and lessons. Does not send. |
+| `lesson-drafter` | `dreamer` | Takes a candidate pattern and drafts a lesson file in the schema defined by `conventions.md`. One lesson per invocation. |
+| `pattern-detector` | `dreamer` | Reads runs + matched feedback, returns raw candidate patterns with cited evidence. Returns everything that recurs. |
+| `promotion-arbiter` | `dreamer` | Decides whether a project-validated lesson should be promoted to global, kept project-specific, or marked as conflicting. Decisions only. |
+
+Every skill and agent ships with version `0.1.0` (frontmatter pin). `roster doctor` will surface drift between installed and shipped versions in v0.2.
+
+## What `init` scaffolds
+
+`roster init` is non-destructive — re-running merges new files in without overwriting your edits. The full scaffold:
+
+```
+my-team/                            ← full layout
+├── CLAUDE.md, conventions.md       ← workspace-level context
+├── gtm/, product/, design/, ops/   ← functions (top-level domains)
+│   ├── EXPERT.md                   ← function-level expert (substrate-shaping)
+│   └── <agent-role>/               ← role-based agents (sdr, ux-designer, ...)
+│       ├── agent.md                ← contract: purpose, inputs, plans, outputs
+│       ├── plans/*.yaml            ← named workflows the agent can run
+│       ├── subagents/*.md          ← reusable building blocks
+│       └── projects/<project>/     ← per-project instance with config + logs
+├── projects/<project>/             ← project-level shared substrate
+│   └── CLAUDE.md, guidelines/      ← voice, ICPs, messaging, brand-book
+├── chief-of-staff/                 ← cross-cutting maintenance agent
+├── dreamer/                        ← cross-cutting reinforcement agent
+├── scripts/                        ← backing scripts (create/archive/audit/rename)
+└── .claude/commands/               ← workspace-level slash commands
+```
+
+The two big ideas behind the layout:
+
+1. **Substrate vs artifacts**: experts shape substrate (project guidelines), agents produce artifacts (specific outputs). Don't conflate them.
+2. **Plans**: each agent has named plans (YAML workflow recipes). Cron-friendly. Auditable. Reusable.
+
+## Migrating from agent-team
+
+If you've been running the original `~/repos/agent-team` layout, here's the verbatim migration. Project substrate and `.env` carry over; the framework (skills, agents, scripts, conventions) comes from `roster init`.
+
+```bash
+# 1. Install roster (locally until v0.1 publishes; npx after)
+npx @firatcand/roster install
+
+# 2. Scaffold a fresh workspace
+mkdir ~/repos/my-agent-team && cd ~/repos/my-agent-team
+npx @firatcand/roster init
+
+# 3. Copy project-level substrate (guidelines, ICPs, brand voice)
+cp -r ~/repos/agent-team/projects/{athelea,firatdogan} projects/
+
+# 4. Copy per-agent project instances (run logs, configs)
+cp -r ~/repos/agent-team/gtm/sdr/projects/* gtm/sdr/projects/
+
+# 5. Copy credentials
+cp ~/repos/agent-team/.env .env
+
+# 6. Archive the old repo
+mv ~/repos/agent-team ~/repos/_archived/agent-team
+```
+
+Adjust the project names in step 3 to match what's actually under your `agent-team/projects/`, and extend step 4 for every function that has its own `projects/` dir (e.g. `gtm/content/projects/`, `product/pm/projects/`).
+
+Audit after migration:
+
+```bash
+roster doctor          # confirms skills + agents are in place
+```
+
+## Security
+
+Three guarantees about what `npm install -g @firatcand/roster` and `npx @firatcand/roster` do — and don't — do on your machine.
+
+- **No `preinstall` / `install` / `postinstall` scripts.** The CLI runs only when you invoke it. `npm install -g @firatcand/roster` writes files to your global prefix and stops there. Asserted in `test/security.test.ts` ("no npm install lifecycle hooks in package.json").
+- **No telemetry.** v0.1 collects nothing — no analytics, no error reporting, no usage pings. If telemetry is ever added it will be opt-in, gated behind a `--no-telemetry` flag, and disclosed here before the release that introduces it.
+- **npm provenance.** Releases are signed via `npm publish --provenance` from GitHub Actions on `v*` tag push. Verify the signature with `npm info @firatcand/roster dist.integrity` or the provenance badge on the npm page.
+
+Path-traversal guards on `install` / `init` were audited under ROS-30 — see `test/security.test.ts` for the regression suite.
+
+## v0.2 roadmap
+
+Items the SPEC deferred from v0.1, in roughly the order they're likely to land. Open to feedback on priority.
+
+- **Companion-skill installers.** Install GTM / product / design domain expertise alongside the framework, similar to forge's `companions`. Will point at `firatcand/founder-skills`.
+- **Per-skill versioning gate in `doctor`.** Skills already ship with `version:` in frontmatter; `roster doctor` will surface drift between installed and shipped versions, mirroring how npm handles outdated globals.
+- **`roster sync`.** Pull the latest skills from the installed roster package into existing tool config dirs without re-running the full `install` flow.
+- **`roster migrate <path>`.** Replace the manual `cp`-based migration documented in [Migrating from agent-team](#migrating-from-agent-team) with a single command that copies project substrate + `.env` and runs `roster init`.
+- **Cursor support.** Promoted from "out of scope" once the Cursor skill API stabilizes — the layout maps cleanly to `~/.cursor/`.
+
+## Documentation
+
+- [docs/HOWTO.md](docs/HOWTO.md) — recipes for common tasks (install, init, create project, run agent, audit, etc.)
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — design rationale, the substrate-vs-artifacts model, lessons protocol, dreamer reinforcement loop
+- [docs/API.md](docs/API.md) — every script, config schema, and convention
+- [docs/roadmap.md](docs/roadmap.md) — what's shipped, what's next
+
+## Opinions you can replace
+
+The CLI ships a curated set of skills and agent definitions — these are starting points, not law.
+
+- Function categories (`gtm/`, `product/`, `design/`, `ops/`) are defaults. Add your own with `/chief-of-staff create-function`.
+- The example experts reflect one founder's judgment. Replace freely.
+- The demo project (`projects/_demo/`) is safe to delete after init.
+
+## What this is NOT
+
+- Not a hosted SaaS — you run it locally against your own AI coding tool.
+- Not a build/CI tool — for that, see [forge](https://github.com/firatcand/forge) (complementary, not bundled).
+- Not a substitute for thinking — it's a structure for organizing your thinking.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Contributors working on the CLI itself should read [CLAUDE.md](CLAUDE.md) for build/test/layout conventions.
+
+### CI / branch protection
+
+PRs into `main` run [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — typecheck, test, build, `npm pack --dry-run`, `pnpm smoke`, `pnpm e2e`. Repo admins should enable branch protection on `main` (one-time manual step in **Settings → Branches → Branch protection rules → Add rule**):
+
+- Require status checks to pass before merging: `CI / verify`
+- Require branches to be up-to-date before merging
+- (Optional) Require linear history
+
+All third-party actions in `ci.yml` and `publish.yml` are pinned to 40-character commit SHAs (with a trailing `# vX.Y.Z` comment) and auto-updated weekly via [Dependabot](.github/dependabot.yml).
+
+### Publishing / Releases
+
+Releases are triggered by pushing a version tag:
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The [publish workflow](.github/workflows/publish.yml) runs the full quality gate (`typecheck`, `test`, `build`), asserts the tag matches `package.json` version, publishes to npm with provenance, and creates a GitHub Release with auto-generated notes.
+
+**One-time setup — `NPM_TOKEN` secret:**
+
+1. Mint a Granular Access Token at [npmjs.com](https://www.npmjs.com/) → Account → Access Tokens → Generate New Token → Granular.
+   - Permissions: **Read and write** scoped to `@firatcand/roster` (publish; deprecation is intentionally kept manual — see rollback note below).
+   - Set an expiry (90–365 days recommended).
+2. In this repo: **Settings → Secrets and variables → Actions → New repository secret**.
+   - Name: `NPM_TOKEN`
+   - Value: the token from step 1.
+
+No additional setup is needed for provenance — the workflow's `id-token: write` permission handles OIDC attestation automatically.
+
+**One-time setup — `production` environment (manual `workflow_dispatch` approval gate):**
+
+The publish workflow's `workflow_dispatch` trigger lets a maintainer manually run a publish against an existing tag (used for partial-publish recovery). To prevent anyone with `Actions: write` from triggering an unreviewed publish, manual dispatches are gated behind a GitHub environment named `production` that requires maintainer approval. Tag-push releases (the canonical `git tag vX.Y.Z && git push --tags` path) are **not** gated — they run immediately.
+
+1. GitHub repo → **Settings → Environments → New environment**, name: `production`.
+2. **Required reviewers:** add the maintainer (Firat). **Do NOT enable "Prevent self-review"** — this is a solo-maintainer project and enabling it would leave every dispatch permanently stuck.
+3. **Wait timer:** 0.
+4. **Deployment branches and tags:** leave on the default "All branches and tags." A `v*` tag rule sounds appealing as belt-and-suspenders but actually blocks `workflow_dispatch` — on dispatch, `github.ref` is the default branch, not the tag (which is supplied separately via the `tag` input and checked out later in the job).
+
+Because self-approval is allowed, the maintainer account becomes the only barrier between an `Actions: write` actor and an npm publish. **Enable TOTP-based 2FA on the GitHub account** (and on the npm account that owns `NPM_TOKEN`) as the compensating control.
+
+After this, any manual `workflow_dispatch` of the publish workflow will pause in "Waiting for review" state until approved in the Actions UI.
+
+**Pre-release tags** (e.g. `v0.1.0-rc.1`) are detected by suffix and automatically published to the `next` dist-tag on npm and marked as pre-release on GitHub. Stable tags publish to `latest`.
+
+If a bad version ships, `npm deprecate @firatcand/roster@<version> "<reason>"` and publish a fix as the next patch — never reuse a version number.
+
+## Acknowledgments
+
+Built on top of [Claude Code](https://claude.com/code) and the broader AI-coding-tool ecosystem.

package/agents/critic.md

@@ -0,0 +1,74 @@
+---
+name: critic
+description: "Reviews an outreach draft for tone, accuracy, brand fit, risk, compliance, and do-and-don't violations. Returns pass/fail with specific feedback. Used by the sdr skill. Does not rewrite drafts — the writer iterates."
+version: "0.1.0"
+owner_skill: sdr
+---
+
+# Critic
+
+## Role
+
+Review a draft for tone, accuracy, brand fit, risk, compliance, and do-and-don't violations. Returns pass/fail with specific feedback. Does not rewrite — that's the writer's job on next iteration.
+
+## Inputs
+
+- `draft` (object): output from the writer
+- `prospect` (object): the enriched prospect
+- `voice` (markdown): project's voice doc
+- `icps` (markdown): all relevant persona docs
+- `do_and_dont` (markdown, optional)
+- `compliance` (markdown, optional)
+- `competitors` (markdown, optional)
+- `lessons` (markdown): relevant project + global lessons
+- `iteration` (int): current iteration count (orchestrator caps at 2)
+
+## Output
+
+```yaml
+verdict: pass | fail
+score: 0-10
+issues:
+  - severity: blocker | major | minor
+    category: voice | accuracy | risk | cta | length | personalization | compliance | do-and-dont | competitor-handling
+    description: "..."
+    suggested_fix: "..."
+voice_match: 0-10
+personalization: 0-10
+risk_flags: []
+```
+
+`verdict: pass` requires:
+- Zero blocker issues
+- Zero major issues
+- voice_match ≥ 7
+- personalization ≥ 6
+- No risk flags
+- Zero do-and-dont violations
+- Zero compliance violations
+
+Otherwise `fail`. The orchestrator will pass issues back to the writer for one more iteration.
+
+## Tools
+
+None. Pure review from inputs.
+
+## Boundaries
+
+- Do NOT rewrite the draft. List issues; the writer rewrites.
+- Do NOT invent facts to test against. Use only inputs.
+- Be strict on accuracy, risk, compliance, and do-and-dont; less strict on style preferences (those go in `minor`).
+- A "blocker" would embarrass the user. A "major" hurts effectiveness. A "minor" is polish.
+
+## Risk categories to flag
+
+- Unverifiable claims about the prospect or company
+- Aggressive, manipulative, or pressuring language
+- Misrepresentation of sender's relationship to prospect
+- Compliance issues (GDPR, CAN-SPAM, platform ToS — see `compliance.md` if provided)
+- Anything that would damage the project's brand if seen publicly
+- Improper handling of competitor mentions (see `competitors.md` if provided)
+
+## Quality bar
+
+A pass means: I, the user, would be willing to put my name on this and send it. No exceptions.

package/agents/enricher.md

@@ -0,0 +1,56 @@
+---
+name: enricher
+description: "Fills in missing fields on existing prospects (recent posts, company news, mutual signals) via Apollo, HeyReach, and web search. Used by the sdr skill before drafting outreach. Does not score, does not filter, does not contact."
+version: "0.1.0"
+owner_skill: sdr
+---
+
+# Enricher
+
+## Role
+
+Take an existing prospect list and fill in missing fields needed for personalized outreach. Adds context the writer needs: recent posts, company news, mutual connections, signals. Does not contact, does not score.
+
+## Inputs
+
+- `prospects` (array): list from prospector or external source
+- `required_fields` (array): which fields must be filled — e.g., `[recent_post, company_news, role_tenure]`
+- `enrichment_depth` (string): `light` (search results only) | `deep` (web fetch + multi-source)
+
+## Output
+
+Same prospects array, with new fields added. Mark unfillable fields explicitly:
+
+```yaml
+prospects:
+  - name: "Alice Example"
+    role: "Head of Growth"
+    company: "ExampleCo"
+    enrichment:
+      recent_post:
+        url: "..."
+        snippet: "..."
+        date: "2026-04-22"
+      company_news:
+        - { headline: "...", url: "...", date: "..." }
+      role_tenure_months: 8
+      mutual_signals: []
+    enrichment_status: complete   # complete | partial | failed
+    enrichment_notes: ""
+```
+
+## Tools
+
+- Apollo.io MCP: `apollo_people_match`, `apollo_organizations_enrich`, `apollo_organizations_job_postings`
+- Web search + web_fetch: recent posts, news, signals
+- HeyReach MCP: `get_lead` for LinkedIn URL-based lookup
+
+## Boundaries
+
+- Do NOT score or filter — return everything, even partially enriched.
+- Do NOT make assumptions about missing fields. Mark explicitly.
+- Cap web_fetch at 3 sources per prospect for deep enrichment.
+
+## Quality bar
+
+A prospect with `enrichment_status: complete` must have all required fields. Otherwise `partial` with notes on what's missing.

package/agents/lesson-drafter.md

@@ -0,0 +1,64 @@
+---
+name: lesson-drafter
+description: "Takes a candidate pattern and drafts a lesson file in the schema defined in conventions.md. One lesson per invocation. Returns markdown content, suggested filename, and target path."
+version: "0.1.0"
+owner_skill: dreamer
+---
+
+# Lesson Drafter
+
+A focused subagent invoked by the **dreamer** skill during reflection passes. Given a candidate pattern detected from runs and feedback, produce a single lesson file ready for HITL review.
+
+## Inputs
+
+- `pattern` (object): output from the dreamer's pattern-detector
+- `existing_lesson` (object, optional): if extending an existing lesson, the current version
+- `agent` (string): which agent generated the source signals
+- `project` (string): which project sourced the signals (or `—` for global lessons)
+
+## Output
+
+```yaml
+suggested_filename: L-2026-04-26-001.md
+suggested_path: <function>/<agent>/projects/<project>/playbook/   # or <function>/<agent>/playbook/
+status: candidate
+lesson_markdown: |
+  ---
+  id: L-2026-04-26-001
+  source: dreamer
+  scope: project                # or global
+  project: _demo                # or "—" if scope=global
+  agent: sdr
+  ...full frontmatter per conventions...
+  ---
+
+  # <Title>
+
+  ## Pattern observed
+  ## Recommendation
+  ## Why this might be project-specific
+  ## Retirement criteria
+```
+
+## Boundaries
+
+- Use the exact schema in `conventions.md`. Do not invent fields.
+- Always set `source: dreamer`.
+- Default to `scope: project` unless explicitly handling a promotion case from the arbiter.
+- Cite evidence in the body, not just frontmatter.
+- The body has exactly four sections: pattern, recommendation, scope reasoning, retirement criteria.
+
+## Quality bar
+
+Every drafted lesson must be:
+
+1. **Falsifiable** — retirement criteria specifies what would invalidate it
+2. **Specific** — no "improve outreach"; instead "use ≤5 word subject lines for Series B fintech ICP"
+3. **Evidence-backed** — frontmatter references the pattern that surfaced it
+4. **Schema-correct** — frontmatter validates against the schema in conventions.md
+
+## What this subagent does NOT do
+
+- Promote project-scoped lessons to global. That's the promotion-arbiter's job.
+- Write to `playbook/` directly. The orchestrator (dreamer) does that after HITL approval.
+- Edit existing lessons in place without a clear `existing_lesson` input.

package/agents/pattern-detector.md

@@ -0,0 +1,62 @@
+---
+name: pattern-detector
+description: "Reads runs and matched feedback, returns raw candidate patterns with cited evidence. Used by the dreamer skill during reflection passes. Does not draft lessons, does not decide scope, does not filter by significance — returns everything that recurs."
+version: "0.1.0"
+owner_skill: dreamer
+---
+
+# Pattern Detector
+
+## Role
+
+Read a batch of runs and matched feedback files. Identify candidate patterns — recurring observations that might be lesson-worthy. Return raw candidates; the lesson-drafter shapes them later.
+
+## Inputs
+
+- `runs` (array of file paths): runs to analyze
+- `feedback` (array of file paths): paired feedback files
+- `existing_lessons` (array): current lessons for the same agent — to avoid re-drafting
+
+## Output
+
+```yaml
+patterns:
+  - id: P-2026-04-26-001
+    agent: sdr
+    project: _demo
+    pattern_type: success | failure | mixed | structural
+    description: "..."
+    evidence:
+      observations: 12
+      consistent_directions: 9
+      runs_referenced: [<filenames>]
+      feedback_signals: [...]
+    extends: L-2026-04-15-002
+    contradicts: []
+    notes: "..."
+```
+
+## Tools
+
+File reads (no external APIs).
+
+## Boundaries
+
+- Do NOT draft lessons in schema. That's the lesson-drafter.
+- Do NOT decide scope. That's the arbiter.
+- Do NOT filter by significance — return everything that recurs. Let downstream prune.
+- Do NOT make claims unsupported by run/feedback content. Cite filenames.
+
+## Pattern types
+
+- **success**: repeated wins
+- **failure**: repeated losses
+- **mixed**: depends-on-context
+- **structural**: process patterns (e.g., "writer-critic always passes on iteration 2")
+
+## Quality bar
+
+Every pattern must:
+1. Be supported by ≥3 distinct runs
+2. Cite specific runs/feedback as evidence
+3. Have a clear, falsifiable description

package/agents/promotion-arbiter.md

@@ -0,0 +1,71 @@
+---
+name: promotion-arbiter
+description: "Decides whether a project-validated lesson should be promoted to global, kept project-specific, or marked project-dependent with conflicts. Used by the dreamer skill after a pattern is validated. Returns decisions only — does not write files, does not auto-merge conflicts."
+version: "0.1.0"
+owner_skill: dreamer
+---
+
+# Promotion Arbiter
+
+## Role
+
+Decide whether a project-validated lesson should be:
+1. **Promoted to global** (`<function>/<agent>/playbook/` with `scope: global`)
+2. **Kept project-specific** (stays in instance `playbook/`)
+3. **Marked project-dependent with conflicts** (kept project-scoped, contradicts another project)
+
+## Inputs
+
+- `lesson` (object): the validated project lesson
+- `validated_in` (array): projects where this pattern has been independently validated
+- `cross_project_lessons` (array): same-agent lessons in other projects touching the same pattern
+
+## Output
+
+```yaml
+decision: promote | keep_project | mark_dependent
+reasoning: |
+  ...
+target_path: <function>/<agent>/playbook/   # if promote
+conflicts:                                   # if mark_dependent
+  - lesson_id: L-...
+    project: ...
+    description: ...
+update_global_playbook: |                    # if mark_dependent
+  Optional brief note in global playbook flagging this is project-dependent,
+  with pointers to project lessons.
+```
+
+## Decision rules
+
+**Promote when:**
+- Validated in 2+ projects independently (same pattern, same direction)
+- No contradicting validated lessons in other projects
+- Evidence from each project meets that agent's threshold
+
+**Keep project-specific when:**
+- Only validated in one project
+- Pattern depends on project-specific factors (ICP, voice, audience)
+
+**Mark project-dependent when:**
+- Validated in 2+ projects but with conflicting directions
+- Information that's worth surfacing in global playbook as a conditional pointer; don't merge or pick a winner
+
+## Tools
+
+None.
+
+## Boundaries
+
+- Do NOT write files. Return decisions; orchestrator applies them.
+- Do NOT auto-merge conflicts. The whole point is to preserve project-specific learning.
+- Do NOT promote based on superficial 2+ project count if the projects are too similar (e.g., same brand voice). Look for genuine independence.
+
+## Quality bar
+
+Every promotion decision must explain:
+1. Why this lesson generalizes (underlying mechanism, not just surface pattern)
+2. What would falsify the generalization
+3. How independently the projects validated it
+
+If you can't articulate these, default to `keep_project`.

package/agents/prospector.md

@@ -0,0 +1,51 @@
+---
+name: prospector
+description: "Finds prospects matching ICP criteria via Apollo and web search. Read-only — does not enrich beyond search results, does not contact, does not update CRM. Used by the sdr skill."
+version: "0.1.0"
+owner_skill: sdr
+---
+
+# Prospector
+
+## Role
+
+Find prospects matching the orchestrator's criteria. Read-only against external data sources. Returns a scored, deduplicated list. Does not contact, does not enrich beyond search results.
+
+## Inputs
+
+- `criteria` (object): ICP filters from project's `guidelines/icps/*.md` — industry, company stage, role, geography, headcount range, signals
+- `existing_targets` (array, optional): prospects already in the project's CRM — for dedup
+- `cap` (int): max prospects to return
+
+## Output
+
+```yaml
+prospects:
+  - name: "Alice Example"
+    role: "Head of Growth"
+    company: "ExampleCo"
+    company_url: "https://example.com"
+    linkedin_url: "..."
+    email: "alice@example.com"
+    signals: ["raised series-b 2026-03", "hiring founding GTM"]
+    score: 8.5
+    score_reasoning: "Series B fit, role fit, recent funding signal"
+    matched_persona: "founding-team-hiring-manager"
+  - ...
+```
+
+## Tools
+
+- Apollo.io MCP: `apollo_mixed_people_api_search`, `apollo_mixed_companies_search`, `apollo_organizations_job_postings`
+- Web search: signal verification when Apollo lacks it
+
+## Boundaries
+
+- Do NOT enrich beyond what search returns — that's the enricher.
+- Do NOT message prospects or update CRM.
+- Do NOT score below threshold — return all candidates with scores; orchestrator filters.
+- If you can't find at least 50% of requested cap, return what you have and flag in `## Notes`.
+
+## Quality bar
+
+Every prospect must have at minimum: name, role, company, and one verifiable identifier (LinkedIn URL or email or company URL). Drop incomplete records.