# Seeding A Project

> Use when the user asks to 'seed the project', 'onboard this repo', 'generate project config', 'create AGENTS.md', or after the scout has explored the codebase. Generates AGENTS.md and .agents/ configuration files for a new project.

- Skill: `arozumenko/seeding-a-project` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add arozumenko/seeding-a-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arozumenko/seeding-a-project/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: arozumenko (https://skillmd.com/u/arozumenko)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/arozumenko/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](references/scout-survey.md)** —
  full Step 0.5 (PR sampling) + Step 0.7 (project-systems capture)
  procedure
- **[references/templates.md](references/templates.md)** — templates
  for every generated file (CLAUDE.md / AGENTS.md / profile /
  conventions / testing / architecture / role-memory seeding)
- **[references/team-comms-templates.md](references/team-comms-templates.md)**
  — `.agents/team-comms.md` templates by host
- **[references/team-comms-workflow.md](references/team-comms-workflow.md)**
  — full Step 6.5 procedure
- **[references/agent-tools-wiring.md](references/agent-tools-wiring.md)**
  — full Step 6.8 procedure (tool whitelists for restrictive hosts)
- **[references/role-overrides.md](references/role-overrides.md)** —
  full Step 6.9 procedure (role substitutions when agents are missing)
- **[references/role-customization.md](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](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](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:**

```bash
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](references/team-comms-workflow.md)**.
Templates live in
**[references/team-comms-templates.md](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](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](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](references/role-customization.md)**.

---

## Validation

After generating, verify:

```bash
# 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 {} +
```