@firatcand/roster 0.1.0

package/templates/scaffold/product/EXPERT.md

@@ -0,0 +1,87 @@
+<!--
+This expert prompt is opinionated. It reflects one founder's judgment about
+which thinkers, frameworks, and skills are useful for this function. Replace
+freely with your own perspectives — the practitioner panel, skills routing,
+and stage filter are all customizable to your context.
+-->
+
+# Product Expert
+
+Senior product leader advising a solo founder building products (default: B2B SaaS — adapt frameworks when context signals otherwise and state the adaptation). Challenge assumptions, identify gaps, produce specification-grade artifacts.
+
+## Scope
+
+- **Critique**: Audit guideline files in `projects/<project>/guidelines/` related to product strategy — `messaging.md`, `competitors.md`, `do-and-dont.md`, `icps/*.md` (when product-led). Score, name gaps, recommend.
+- **Generate guidelines**: Produce or refine these guideline files. Refine project `CLAUDE.md` identity when underspecified.
+- **Guide**: Specification, positioning, analytics, research, tradeoff discussions. Strategic output — files only when the task asks for substrate.
+
+You do **NOT** produce sprint-level backlog artifacts (individual tickets, per-sprint user stories, ad-hoc analytics dashboards, throwaway one-shot specs). PRDs, foundational requirements, and acceptance criteria are substrate when they shape a category-level decision — those you do produce via Specify mode. **Experts shape substrate; agents produce artifacts.**
+
+## Read-first protocol
+
+On invocation, read:
+
+1. `projects/<project>/CLAUDE.md` — project identity
+2. `projects/<project>/guidelines/voice.md` and `icps/*` — audience and tone
+3. Existing guideline files relevant to the task
+4. `projects/<project>/state.md` — current focus
+
+Ask only about gaps. Never re-ask what's in substrate. If multiple modes are plausible, state which mode you're entering before proceeding.
+
+## Operating modes
+
+State the mode. Don't mix.
+
+| Mode | Trigger | Behavior |
+|---|---|---|
+| **Specify** | Spec, requirements, user stories, acceptance criteria | product-spec (+ software-architect / ux-design if relevant) → intake → artifact |
+| **Position** | Positioning, value props, messaging hierarchy | product-position (+ plg-skill if PLG-relevant) → intake → artifact |
+| **Analyze** | Metrics, funnels, measurement framework | plg-skill if PLG-relevant → intake → recommendations |
+| **Research** | Competitive analysis, market mapping | intake → artifact |
+| **Advise** | Open question, tradeoff, decision framework | direct response, skills as needed |
+
+When ambiguous, state your interpretation before producing output.
+
+## Mandatory intake (Specify / Position / Analyze / Research)
+
+Ask only what's missing.
+
+- **Specify**: problem and audience · desired user outcome (not feature description) · constraints (timeline, stack, dependencies) · definition of done · edge cases, risks, non-goals
+- **Position**: product/feature being positioned · primary buyer and user · alternatives (competitors, workarounds, status quo) · defensible differentiation · product stage
+- **Analyze**: question to answer · product stage · existing instrumentation · decisions this informs
+- **Research**: category/segment · specific questions · known competitors · decision this feeds
+
+In Advise mode, skip formal intake. Ask inline only if genuinely underspecified.
+
+## Skills
+
+| Task | Skill |
+|---|---|
+| PRDs, feature specs, user stories, acceptance criteria, spec audits | product-spec |
+| Positioning, messaging hierarchy, value props, category, differentiation | product-position |
+| Architecture decisions, stack selection, monolith vs microservices, db choices, migration | software-architect |
+| UX audits, flows, interaction critique, Gestalt/affordance review | ux-design |
+| PLG strategy, freemium, activation metrics, PQLs, viral loops | plg-skill |
+
+Prefer skill methodology over general reasoning when the task falls within their domain.
+
+## Output rules
+
+- Generated guidelines write to `projects/<project>/guidelines/<file>.md`. Name the path before writing.
+- Use must / should / may — never could / might. Every requirement testable.
+- Open every artifact with a one-line summary of what it is and what decision it supports.
+- Close every artifact with **Open Questions** — unresolved items, missing inputs, next steps.
+- Tables for comparisons. Prose for reasoning.
+
+## Behavior rules
+
+- **Challenge before you build.** Name weak assumptions, dependencies, gaps before producing.
+- **Separate problem from solution.** Confirm the problem before specifying a feature.
+- **Name tradeoffs.** State what every recommendation costs.
+- **Scope ruthlessly.** Flag when scope exceeds a single shippable increment; suggest decomposition.
+- **Be direct.** No "it depends" without conditions. No filler praise.
+- **Stay in your lane.** Specification, positioning, analytics, research. Lightweight on execution; recommend domain handoff.
+
+## Stage filter
+
+Early-stage: limited budget, no brand awareness, unvalidated assumptions. Bias toward learning over scaling. Flag every claim that depends on an unvalidated market, customer, or product assumption.

package/templates/scaffold/projects/_demo/CLAUDE.md

@@ -0,0 +1,35 @@
+---
+project: _demo
+type: example
+created: 2026-05-03
+---
+
+# Acme Corp — Demo Project
+
+This is a sample project demonstrating how `roster` organizes work. Acme Corp is a fictional B2B SaaS company that helps small businesses automate their accounting workflows.
+
+This demo is **safe to delete**. It exists to show the structure of a populated project. Real projects go in `projects/<your-project-name>/`.
+
+## Identity
+
+- Product: Acme Books — accounting automation for SMBs
+- Stage: early-stage SaaS, post-launch
+- Audience: SMB owners and bookkeepers
+- Primary motion: outbound to bookkeeping firms and SMB owners
+
+## Active agent instances
+
+- `gtm/sdr/projects/_demo/` — outbound prospecting and cold outreach
+
+## Files in this project
+
+- `CLAUDE.md` — this file
+- `state.md` — session continuity (auto-updated)
+- `guidelines/` — substrate (voice, ICPs, messaging, brand-book, etc.)
+
+## How to use as a learning example
+
+1. Browse `projects/_demo/guidelines/` to see what filled-in substrate looks like
+2. Browse `gtm/sdr/projects/_demo/config/default.yaml` to see how an agent instance is configured
+3. Try running the agent against this demo: `/sdr run cold-outreach for _demo` (will prompt for filled bindings — feel free to use placeholder values for the test)
+4. Delete this entire `_demo/` directory and its instance(s) when you're ready to start fresh

package/templates/scaffold/projects/_demo/README.md

@@ -0,0 +1,16 @@
+# _demo
+
+Placeholder project for testing roster workflows. Rename or duplicate this directory to
+create a real project — `scripts/new-project.sh <name>` automates that in Phase 2.
+
+## Structure
+
+```
+projects/_demo/
+├── guidelines/           # written by function-level experts (added in Phase 2)
+├── config/default.yaml   # per-project agent config (added in Phase 2)
+└── state.md              # session continuity notes (max 5 lines; updated via /save-state)
+```
+
+In Phase 1 this directory only proves `roster init` writes files to the right place. The
+full project substrate lands when Phase 2 ships `templates/scaffold/` (see ROS-17).

package/templates/scaffold/projects/_demo/config/default.yaml

@@ -0,0 +1,28 @@
+---
+project: _demo
+created: 2026-05-03
+---
+
+# Project-level config — Acme Corp demo
+#
+# Cross-agent defaults for this project. Agent-scoped config (per-instance
+# tool bindings, channel caps, scoring thresholds) lives at:
+#   <function>/<agent>/projects/<project>/config/default.yaml
+#
+# Keep this file thin. It's read by chief-of-staff for audit reports and
+# by any agent that needs project-wide signals.
+
+# Display name shown in reports and Slack messages.
+display_name: Acme Corp
+
+# Stage: idea | pre-launch | early | growth | mature
+stage: early
+
+# Primary go-to-market motion. Drives default agent suggestions.
+# Options: outbound | inbound | plg | hybrid
+motion: outbound
+
+# Default approval channel for HITL — used when an agent's instance config
+# leaves approval_channel unset.
+# Options: slack | inline | auto
+approval_channel: auto

package/templates/scaffold/projects/_demo/guidelines/asset-links.md

@@ -0,0 +1,15 @@
+# Asset Links — Acme Corp
+
+## Brand
+- Logo files: <Drive folder URL>
+- Brand guidelines PDF: <Drive folder URL>
+
+## Templates
+- Email template (cold outreach): <Drive doc URL>
+- LinkedIn DM template: <Drive doc URL>
+- Demo script: <Drive doc URL>
+
+## External
+- Website: https://acmecorp.example.com
+- Calendar booking: https://cal.com/acmecorp/intro
+- Knowledge base: https://docs.acmecorp.example.com

package/templates/scaffold/projects/_demo/guidelines/brand-book.md

@@ -0,0 +1,25 @@
+# Brand Book — Acme Corp
+
+## Logo
+- Wordmark "Acme" in deep navy
+- Optional small icon (ledger lines)
+
+## Colors
+- Primary: Navy (#1a2742)
+- Secondary: Warm white (#fafaf6)
+- Accent: Muted gold (#c9a85d)
+- Error: Brick red (#a93f3f)
+
+## Typography
+- Display: Söhne (or Inter as web fallback)
+- Body: Inter
+- Code: JetBrains Mono
+
+## Imagery
+- Photography: real small businesses, daylight, no stock-art smiles
+- Illustrations: line-art only, navy + gold, no soft gradients
+
+## Don't
+- Don't pair navy + green — looks generic SaaS
+- Don't use stock images of "diverse team in conference room"
+- Don't use dramatic AI-generated illustrations

package/templates/scaffold/projects/_demo/guidelines/icps/_persona-template.md

@@ -0,0 +1,44 @@
+# <Persona Name>
+
+Short slug for filename: `<slug>.md` (e.g., `founding-team-hiring-manager.md`).
+
+## Who they are
+- Industry: <list>
+- Company stage: <list>
+- Company size: <range>
+- Geography: <list or global>
+
+## Their role
+- Title patterns: <list>
+- Reports to: <list>
+- Tenure: <typical>
+- Day-to-day: <what they actually do>
+
+## What they care about
+- Top 3 pains: <list>
+- Top 3 goals: <list>
+- What success looks like for them: <description>
+
+## Buying signals / triggers
+Recent events or states that suggest they're a good fit RIGHT NOW:
+- <signal — e.g., "company raised Series B in last 90 days">
+- <signal — e.g., "hiring founding GTM role">
+- <signal>
+
+## Engagement signals
+Things they do publicly that suggest they're approachable:
+- <signal — e.g., "posts on LinkedIn weekly">
+- <signal — e.g., "responded to a founder DM publicly in last 30 days">
+
+## Disqualifiers
+What makes someone NOT a fit even if they otherwise match:
+- <e.g., "company in stealth — no public signals to personalize on">
+- <e.g., "C-suite at >500 person company — wrong access pattern">
+
+## Channels they respond to
+- Best: <list>
+- Acceptable: <list>
+- Avoid: <list>
+
+## Notes
+<anything else that helps an agent know this persona>

package/templates/scaffold/projects/_demo/guidelines/messaging.md

@@ -0,0 +1,20 @@
+# Messaging — Acme Corp
+
+## Headline value props
+1. **Reconciles your books in 80% less time** — primary proof point
+2. **Catches errors humans miss** — secondary, builds confidence
+3. **Works inside QuickBooks / Xero / Wave** — table stakes, but worth saying
+
+## Anti-positioning
+- We are NOT trying to replace bookkeepers — we make them more productive
+- We are NOT a generic AI tool — we're built specifically for small business accounting
+
+## Frame for cold outreach
+- Open with a question about their accounting workflow
+- Acknowledge that automation is a hot topic but most tools are generic
+- Offer something specific: a workflow demo or a 15-min audit
+
+## Frame for inbound
+- Lead with the time savings (concrete: "3 hours/week back")
+- Show the integration logos (lower the perceived risk)
+- Quote a real-feeling customer story

package/templates/scaffold/projects/_demo/guidelines/voice.md

@@ -0,0 +1,29 @@
+# Voice — Acme Corp
+
+## Adjectives describing the brand voice
+1. Practical
+2. Direct
+3. Reassuring
+
+## Tone
+- We talk like a knowledgeable colleague, not a vendor.
+- We acknowledge accounting is tedious — we don't pretend it's exciting.
+- We respect the reader's time. Short sentences. No fluff.
+
+## Sentence length
+Most sentences under 18 words. Very rarely longer.
+
+## Vocabulary
+- Use plain words: "books" not "ledger entries", "match" not "reconcile"
+- Avoid: "transformative", "revolutionary", "leveraging", "synergize"
+- Industry terms allowed when they're unavoidable: GAAP, AR, AP, COGS
+
+## Channel-specific notes
+- Email: warm + direct. Always one CTA per message.
+- LinkedIn: a little more casual, less salesy.
+- Website: most polished, but still conversational.
+
+## Anti-examples
+- "We're transforming the way SMBs handle their books" — too generic, sounds like every SaaS pitch
+- "Leverage our cutting-edge platform" — corporate speak
+- "Hope this finds you well" — empty opener

package/templates/scaffold/projects/_demo/state.md

@@ -0,0 +1,11 @@
+---
+last_session: 2026-05-03
+focus: (none — demo project)
+---
+
+# Acme Corp — Session State
+
+This file tracks short-term context across Claude Code sessions for this project. Updated via `/save-state` or by the user explicitly. Five lines max.
+
+- Status: demo / illustrative
+- Next task: replace with your real project, or delete `_demo/` entirely

package/templates/scaffold/scripts/lib/README.md

@@ -0,0 +1,13 @@
+# Shared script libraries
+
+Helper functions for use across scripts. Empty for now — add as scripts grow.
+
+Conventions:
+- Bash: `<n>.sh`, sourced via `source "$(dirname $0)/lib/<n>.sh"`
+- Python: `<n>.py` if needed (use `pip install --break-system-packages`)
+- Keep functions narrow
+
+Example future additions:
+- `lib/lesson.sh` — read/write lesson files, validate schema
+- `lib/run.sh` — append to run files, format frontmatter
+- `lib/slack.sh` — HITL posting with retry

package/templates/scaffold/scripts/lib/functions.sh

@@ -0,0 +1,89 @@
+# scripts/lib/functions.sh — shared helpers for reading the functions registry.
+# Source from a script that has $ROOT set to repo root:
+#   ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+#   source "$ROOT/scripts/lib/functions.sh"
+#
+# Provides:
+#   read_functions               — print one slug per line from .config/functions.yaml
+#   read_functions_with_metadata — print "<slug>\t<has_expert>" per line
+#   is_valid_function <slug>     — return 0 if slug is registered, else 1
+
+_have_pyyaml() {
+  command -v python3 >/dev/null 2>&1 && python3 -c "import yaml" >/dev/null 2>&1
+}
+
+read_functions() {
+  local config="${ROOT}/.config/functions.yaml"
+  if [ ! -f "$config" ]; then
+    echo "ERROR: $config not found" >&2
+    return 1
+  fi
+  if _have_pyyaml; then
+    python3 -c "
+import yaml, sys
+try:
+    with open('$config') as f:
+        data = yaml.safe_load(f) or {}
+except yaml.YAMLError as e:
+    sys.stderr.write('ERROR: malformed YAML in $config: ' + str(e) + '\n')
+    sys.exit(1)
+for fn in data.get('functions', []):
+    slug = fn.get('slug', '')
+    if slug:
+        print(slug)
+" || return 1
+  else
+    grep -E '^[[:space:]]*-[[:space:]]*slug:[[:space:]]*' "$config" \
+      | sed -E 's/^[[:space:]]*-[[:space:]]*slug:[[:space:]]*//; s/[[:space:]]*$//'
+  fi
+}
+
+read_functions_with_metadata() {
+  local config="${ROOT}/.config/functions.yaml"
+  if [ ! -f "$config" ]; then
+    echo "ERROR: $config not found" >&2
+    return 1
+  fi
+  if _have_pyyaml; then
+    python3 -c "
+import yaml, sys
+try:
+    with open('$config') as f:
+        data = yaml.safe_load(f) or {}
+except yaml.YAMLError as e:
+    sys.stderr.write('ERROR: malformed YAML in $config: ' + str(e) + '\n')
+    sys.exit(1)
+for fn in data.get('functions', []):
+    slug = fn.get('slug', '')
+    has_expert = bool(fn.get('has_expert', False))
+    if slug:
+        print(slug + '\t' + ('true' if has_expert else 'false'))
+" || return 1
+  else
+    # Fallback: awk over flat YAML; track current slug and emit when has_expert seen.
+    awk '
+      /^[[:space:]]*-[[:space:]]*slug:[[:space:]]*/ {
+        if (slug != "") print slug "\t" (he == "true" ? "true" : "false")
+        slug = $0
+        sub(/^[[:space:]]*-[[:space:]]*slug:[[:space:]]*/, "", slug)
+        sub(/[[:space:]]*$/, "", slug)
+        he = "false"
+        next
+      }
+      /^[[:space:]]*has_expert:[[:space:]]*/ {
+        v = $0
+        sub(/^[[:space:]]*has_expert:[[:space:]]*/, "", v)
+        sub(/[[:space:]]*$/, "", v)
+        he = v
+      }
+      END {
+        if (slug != "") print slug "\t" (he == "true" ? "true" : "false")
+      }
+    ' "$config"
+  fi
+}
+
+is_valid_function() {
+  local fn="$1"
+  read_functions 2>/dev/null | grep -Fxq "$fn"
+}

package/templates/scaffold/scripts/new-project.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# new-project.sh — scaffold a new project substrate inside a roster workspace.
+#
+# Usage:
+#   bash scripts/new-project.sh <project-name> [<function>]
+#
+# Arguments:
+#   project-name   Free-form name. Normalized to kebab-case (lowercase,
+#                  [a-z0-9-], non-alphanumeric runs collapsed to '-').
+#                  Examples:
+#                    "My Co"        -> my-co
+#                    "foo bar/baz"  -> foo-bar-baz
+#                    "Acme Corp 2"  -> acme-corp-2
+#   function       Optional. If provided, must be registered in
+#                  .config/functions.yaml (gtm, product, design, ops, ...).
+#
+# Creates:
+#   projects/<slug>/
+#     guidelines/.gitkeep
+#     config/default.yaml      (project-level config skeleton)
+#     state.md                 (frontmatter + 5-line stub)
+#
+# Exit codes:
+#   0  success
+#   1  usage / validation error
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck disable=SC1091
+source "$ROOT/scripts/lib/functions.sh"
+
+usage() {
+  echo "Usage: $0 <project-name> [<function>]" >&2
+  echo "  project-name   Free-form; normalized to kebab-case" >&2
+  echo "  function       Optional; must be in .config/functions.yaml" >&2
+}
+
+if [ $# -lt 1 ] || [ $# -gt 2 ]; then
+  usage
+  exit 1
+fi
+
+RAW_NAME="$1"
+FUNCTION="${2:-}"
+
+normalize() {
+  # 1. lowercase
+  # 2. replace any run of non-alphanumeric chars with a single '-'
+  # 3. trim leading/trailing '-'
+  printf '%s' "$1" \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'
+}
+
+SLUG="$(normalize "$RAW_NAME")"
+
+if [ -z "$SLUG" ]; then
+  echo "ERROR: project name '$RAW_NAME' is empty after normalization" >&2
+  exit 1
+fi
+
+if ! [[ "$SLUG" =~ ^[a-z][a-z0-9-]*$ ]]; then
+  echo "ERROR: normalized slug '$SLUG' must start with a letter and contain only a-z, 0-9, '-'" >&2
+  exit 1
+fi
+
+if [ -n "$FUNCTION" ]; then
+  if ! is_valid_function "$FUNCTION"; then
+    echo "ERROR: function '$FUNCTION' is not registered in .config/functions.yaml" >&2
+    echo "Registered functions:" >&2
+    read_functions 2>/dev/null | sed 's/^/  - /' >&2 || echo "  (registry empty or missing)" >&2
+    exit 1
+  fi
+fi
+
+TARGET="$ROOT/projects/$SLUG"
+
+if [ -e "$TARGET" ]; then
+  echo "ERROR: project '$SLUG' already exists at $TARGET" >&2
+  exit 1
+fi
+
+TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+mkdir -p "$TARGET/guidelines" "$TARGET/config" "$TARGET/assets"
+touch "$TARGET/guidelines/.gitkeep" "$TARGET/assets/.gitkeep"
+
+cat >"$TARGET/config/default.yaml" <<EOF
+---
+project: $SLUG
+created: ${TIMESTAMP%T*}
+---
+
+# Project-level config for $SLUG.
+# Cross-agent defaults. Agent-scoped instance config lives at:
+#   <function>/<agent>/projects/$SLUG/config/default.yaml
+
+display_name: $SLUG
+stage: early
+motion: outbound
+approval_channel: auto
+EOF
+
+cat >"$TARGET/state.md" <<EOF
+---
+updated: $TIMESTAMP
+---
+
+Last task: (none yet)
+Active artifacts: (none)
+Open questions: (none)
+Next session: fill in guidelines/voice.md and at least one ICP
+Notes: created via scripts/new-project.sh
+EOF
+
+echo "✓ Project '$SLUG' created at projects/$SLUG/"
+echo ""
+echo "Next steps:"
+echo "  1. Fill projects/$SLUG/guidelines/voice.md (3 adjectives + tone)"
+echo "  2. Add at least one ICP under projects/$SLUG/guidelines/icps/"
+echo "  3. Edit projects/$SLUG/config/default.yaml — set display_name, stage, motion"
+if [ -n "$FUNCTION" ]; then
+  echo "  4. Wire an agent instance via chief-of-staff: add-agent-to-project project=$SLUG function=$FUNCTION agent=<name>"
+fi