Seeding A Project

Project Seeder

Generate the configuration files that agent roles need to work in a project.

What Gets Generated

project-root/
├── CLAUDE.md                     ← Auto-loaded by Claude Code: brief project context
├── AGENTS.md                     ← Full team reference: stack, commands, conventions
└── .agents/                      ← IDE-neutral agent content (every agent reads)
    ├── knowledge/                ← shared, committed cross-role knowledge (Step 2.5)
├── profile.md                ← Quick-reference project card
    ├── workflow.md               ← How the team actually works (PR sampling — Step 0.5)
    ├── team-comms.md             ← Who's on the team and how to route work (Step 6.5)
    ├── architecture.md           ← System design map (if complex enough)
    ├── conventions.md            ← Detected coding standards
    ├── testing.md                ← Test infrastructure details
    ├── onboarding.md             ← Scout's own audit trail
    └── memory/<role-id>/
        ├── MEMORY.md             ← Index (add a line for each entry)
        └── project_briefing.md   ← Per-role project briefing (Step 7c)

Not every project needs all files. Skip what's not relevant.

References

Each major step has a focused reference file:

• references/scout-survey.md — full Step 0.5 (PR sampling) + Step 0.7 (project-systems capture) procedure
• references/templates.md — templates for every generated file (CLAUDE.md / AGENTS.md / profile / conventions / testing / architecture / role-memory seeding)
• references/team-comms-templates.md — .agents/team-comms.md templates by host
• references/team-comms-workflow.md — full Step 6.5 procedure
• references/agent-tools-wiring.md — full Step 6.8 procedure (tool whitelists for restrictive hosts)
• references/role-overrides.md — full Step 6.9 procedure (role substitutions when agents are missing)
• references/role-customization.md — full Step 7 procedure (persona repurposing for non-default stacks)

Step 0.5 — PR-sampling survey

Before writing any content files, scout samples the project's PR history to understand how the team actually works — not just what the code looks like. It classifies PRs into five categories (framework / test-impl / bugfix / feature / review signal), samples 2–3 per category (max ~15 total), and extracts signals that feed .agents/workflow.md, .agents/testing.md, .agents/conventions.md, and .agents/architecture.md.

Git host is detected first (GitHub / GitLab / Bitbucket / Azure DevOps / Gitea) so the correct CLI is used. Empty repos get a stub workflow.md and the seed continues.

Full procedure — host detection table, classification rules, sampling rules, signal-to-destination table, report format — lives in references/scout-survey.md § Step 0.5.

Step 0.7 — Project-systems capture

After PR sampling, scout resolves the project-systems map — issue tracker, TMS, KB, bug-filing style, automation PR policy — and writes it into .agents/profile.md § Project systems. The operator can pre-fill these in the onboarding prompt (under a ## Project systems block); unspecified fields become ASK and scout either asks interactively or writes Unconfirmed.

Downstream skills read this section at runtime: test-case-analysis (bug filing), bugfix-workflow (tracker CLI), test-automation-workflow (test-case storage), project-manager + test-automation-engineer (merge policy, base branch).

Full procedure — all 11 captured fields, defaults, destinations, report format — lives in references/scout-survey.md § Step 0.7.

Step 1 — Generate CLAUDE.md

The most immediately impactful file. Claude Code loads it automatically at the start of every session, so every agent has project context without doing anything. Keep it under 80 lines.

Check first — it may already exist:

cat CLAUDE.md 2>/dev/null && echo "EXISTS" || echo "NOT FOUND"

• If it doesn't exist: create it fresh from the template in references/templates.md.
• If it exists: treat it as the engineer's carefully crafted document. Read the whole thing before touching anything. Make only surgical additions for genuinely missing facts (e.g. a command you verified that isn't listed). Fix only clear errors. Do not restructure, reword, or "improve" prose — the wording is intentional. When in doubt, leave it alone and ask the engineer directly. Preserve any <!-- FACTORY:<id> START --> … END --> block verbatim (the pre-rename <!-- BUNDLE:<id> START --> … END --> form may also appear on older installs and must likewise be preserved) — it's a team factory's conventions, not yours to edit.

What belongs here: one-paragraph project overview, 3–5 most important commands (install, dev, test), critical conventions, key paths (entry points, test dirs, config files), a pointer to AGENTS.md for full detail.

What does NOT belong here: exhaustive command lists (that's AGENTS.md), full architecture diagrams (.agents/architecture.md), long convention catalogues (.agents/conventions.md).

Step 2 — Generate AGENTS.md

The full team reference. Every role reads it on-demand. Use the template in references/templates.md and fill it with actual findings.

Key sections: project overview (1 paragraph), tech stack, repository structure (directory tree with annotations), build & run commands (install, dev, test, lint, deploy), coding conventions (detected from codebase), testing (framework, commands, patterns), CI/CD, environment.

Rules:

• Only document what you've verified. Don't guess build commands.
• Include the ACTUAL commands from package.json scripts, Makefile targets, CI config.
• Note inconsistencies: "README says npm test but CI runs npx jest --ci".
• Keep it under 200 lines. Link to .agents/ files for details.
• Preserve factory blocks. If AGENTS.md already contains any <!-- FACTORY:<id> START --> … <!-- FACTORY:<id> END --> block (or the pre-rename <!-- BUNDLE:<id> START --> … <!-- BUNDLE:<id> END --> form on older installs), copy it through verbatim — it was installed by a team factory and holds that team's working agreements. Read existing AGENTS.md before regenerating; keep every factory block intact (placement doesn't matter — keep it whole). Never edit or drop the marker lines.

Step 2.5 — Scaffold .agents/knowledge/ (shared knowledge layer)

The committed counterpart to per-role memory. .agents/memory/<role>/ is local and role-scoped, so a fact one role paid for is invisible to every other role — and to the same role on another machine. This layer is where cross-role facts live so they are actually reachable.

Create the charter and folder scaffolding (skip any folder the project has no use for):

.agents/knowledge/
├── README.md            ← charter: admission tests + start-here index
├── architecture/        system shape, service boundaries, seams
├── services/            per-service invariants and surprising contracts
├── frontend/            client state, lifecycle, enforced UI rules
├── integrations/        external systems the project depends on
├── environment/         local setup and the dev loop
├── practices/           how we work: verification, migration hazards, review
├── testing/             suites and harness behaviour
└── security/            credential, auth and egress invariants

Each folder gets a README.md stating what belongs in it and what does not, plus an index of its notes. Empty folders are fine — a named home makes it likelier a hard-won fact gets written down at all.

The charter must state the admission tests, because a shared layer is only useful if it is trusted. A note is admitted only if it is cross-role, verified (with a stated method and date), durable, and costly to rediscover. Say plainly that an unverified claim here is worse than silence, since it is committed and therefore trusted.

Seed it from what you verified during onboarding — the facts that took real effort to establish and that more than one role will need (how to run the stack, what make dev does not set up, which invariants fail silently). Do not pad it: three trustworthy notes beat twenty uncertain ones.

Record the contract in CLAUDE.md and AGENTS.md (Steps 1 and 2) so agents know the layer exists and how to add to it — a knowledge layer nobody is told about is one nobody uses. In AGENTS.md, place it outside any <!-- FACTORY --> (or legacy <!-- BUNDLE -->) markers so factory regeneration cannot clobber it.

Ongoing curation is the knowledge-curation skill's job; seeding just creates the structure and the first entries.

Step 3 — Generate .agents/profile.md

Quick-reference card with YAML frontmatter (project, team, issue- tracker, default-branch, languages). See references/templates.md.

Step 4 — Generate .agents/conventions.md (if patterns detected)

Only create if you found clear patterns. Document what IS, not what should be. Cover naming, import ordering, error handling, code organization, comment/doc style.

Step 5 — Generate .agents/architecture.md (if complex)

Only for multi-service or non-trivial architectures: service/component map, data flow, API boundaries, database schema overview, infrastructure diagram (text-based).

Step 6 — Generate .agents/testing.md (if test infra exists)

QA engineer reads this. Include test framework and config, how to run tests (exact commands), fixture/setup patterns, test data strategy, CI test pipeline, coverage tools, known flaky areas.

Step 6.5 — Generate .agents/team-comms.md

Every project gets a scout-generated .agents/team-comms.md that names the host, the installed personas, and the exact invocation syntax.

Full procedure — host detection, persona enumeration, template selection, Copilot capability declaration, idempotence rules — lives in references/team-comms-workflow.md. Templates live in references/team-comms-templates.md.

Step 6.8 — Wire agent tool whitelists (restrictive hosts)

Hosts that default to a restrictive tool-permission model — notably GitHub Copilot CLI, where an agent with no tools: line only gets ['agent'] — need a per-agent tools: whitelist written into the installed agent frontmatter. Claude Code's permissive default means this step skips on that host.

Scout is fully autonomous at this step — no operator prompts, no per-agent capability manifest. It derives the whitelist from evidence already available: each skill's setup.yaml (dependencies.mcp[].name), .agents/test-automation.yaml (TMS mapping), live MCP servers on the host, and each agent's frontmatter.

Full procedure — host detection, skill-and-MCP matching, intent-based tool scoping, failure handling, idempotence rules — lives in references/agent-tools-wiring.md.

Step 6.9 — Role substitutions (missing roles)

Scout compares the workflow slots the project needs (from installed workflow skills + stated pipelines) against the installed agent roster. For any slot lacking a dedicated agent, scout picks the best-matching installed agent and injects per-project routing overrides into the AGENT.md files of the routing agents (PM, tech- lead, any other agent whose handoff prompts name specific agents).

Lightweight substitution (SCOUT-INJECTED marker-bracketed section) is the default; full persona rewrite (Step 7) is the escalation when the installed agent is too distant from the slot.

Runs automatically after Step 6.8. No-op when every needed slot has its dedicated agent installed.

Full procedure — role-similarity table, injection format, idempotence rules, per-agent injection locations, report format — lives in references/role-overrides.md.

Step 7 — Role customization (non-default stacks)

Only runs when the detected stack doesn't match the default role set (e.g. game engines, Rust CLIs, data science). Skip entirely if defaults fit.

Full procedure — SOUL.md / AGENT.md rewrites, role memory seeding — lives in references/role-customization.md.

Validation

After generating, verify:

# Core files exist
ls CLAUDE.md AGENTS.md .agents/profile.md

# CLAUDE.md is brief (auto-loaded — must not be bloated)
wc -l CLAUDE.md  # should be under 80 lines

# AGENTS.md is readable
wc -l AGENTS.md  # should be under 200 lines

# No secrets leaked anywhere scout wrote
grep -ri "password\|secret\|token\|api_key" CLAUDE.md AGENTS.md .agents/ 2>/dev/null || echo "clean"

# Factory blocks survived regeneration (paired START/END markers, if any;
# also check the legacy BUNDLE form on older installs)
grep -c "<!-- FACTORY:.* START -->" AGENTS.md 2>/dev/null  # must equal the END count
grep -c "<!-- BUNDLE:.* START -->" AGENTS.md 2>/dev/null   # legacy form, if present

# Agent tool whitelists wired (only expected under Copilot CLI / restrictive hosts)
if ls .github/agents/*.agent.md >/dev/null 2>&1; then
  grep -L "^tools:" .github/agents/*.agent.md | head || echo "all agent files declare tools:"
fi

# Memory files present and non-empty for all roles
ls .agents/memory/
find .agents/memory -name 'project_briefing.md' -exec wc -l {} +