• New repo onboarding: Bootstrap agent-readable docs from scratch.
• After major refactors: Verify docs still match reality.
• Periodic health check: Catch doc rot before it compounds.
• Before handing a repo to agents: Confirm docs give a fresh agent enough to work independently.
• Multi-tool teams: Use

  --agents

  to generate adapter files for Cursor, Copilot, and Codex.

• Project identity (one sentence: what this is, what stack)
• How to install, run, test, deploy (commands only, no explanation)
• Key rules and constraints (things that break if violated)
• Pointers to

  docs/

  for deeper reference

• Architecture explanations (→

  docs/architecture.md

  )
• API reference (→

  docs/api.md

  )
• Config/env var tables longer than 5 rows (→

  docs/configuration.md

  )
• Runbooks or troubleshooting (→

  docs/runbook.md

  )
• History, context, or "why we built this" (→ README.md or nowhere)

docs/

wc -l CLAUDE.md

• docs/architecture.md

  — system boundaries, data flow, key abstractions, service map

• docs/api.md

  — routes, endpoints, request/response shapes

• docs/configuration.md

  — env vars, feature flags, config files with all options documented

• docs/workflows.md

  — dev workflow, CI/CD, deploy process, release steps

• docs/data-model.md

  — database schema, key tables, relationships

• docs/glossary.md

  — domain terms that aren't obvious from code (only if needed)

• docs/runbook.md

  — how to debug common issues, operational procedures

• One topic per file. If a file exceeds 200 lines, split it.
• File names must be self-descriptive — an agent picks which file to read based on the name.
• No

  docs/misc.md

  or

  docs/notes.md

  — if it doesn't have a clear topic, it doesn't belong.
• Link between doc files when concepts cross boundaries.

REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename $(git remote get-url origin) .git)
TODAY=$(date +%Y-%m-%d)
ITERATION=1
MAX_ITERATIONS=5
PASS_THRESHOLD=80

• --loop

  — run the full loop until pass rate >= 80% or max iterations

• --agents

  — generate agent adapter files (Phase 2.5)

• --canonical agents

  — make

  AGENTS.md

  the source of truth;

  CLAUDE.md

  symlinks to it

--agents

.cursor/

.github/copilot-instructions.md

--agents

• Entry points (

  main

  ,

  index

  ,

  app

  , CLI entrypoints)
• How to install, run, test (the commands, not just that they exist)
• API routes and endpoints
• Config files (env vars, feature flags, deploy config)
• Important abstractions (key classes, modules, patterns)
• Architecture (service boundaries, data flow, external deps)
• Dev workflow (CI, deploy, release process)
• Domain-specific terms that aren't obvious from code

CLAUDE.md

docs/architecture.md

docs/api.md

docs/configuration.md

docs/workflows.md

docs/data-model.md

docs/glossary.md

KNOWLEDGE_MAP="/tmp/popsicle-knowledge-$(date +%s).json"

python3 -c "
import json, sys
concepts = [
    {
        'id': 'concept-1',
        'category': 'architecture',
        'target_file': 'docs/architecture.md',
        'name': 'Short name',
        'description': 'What an agent should know about this',
        'evidence': 'Where you found it in the code (file:line)',
        'question': 'Question to ask the validation session',
        'nav_question': 'Which doc file would you read to learn about this?'
    },
    # ... 5-10 concepts
]
with open('$KNOWLEDGE_MAP', 'w') as f:
    json.dump({'repo': '$REPO_NAME', 'iteration': $ITERATION, 'concepts': concepts}, f, indent=2)
"

/tmp

Generated by popsicle on {TODAY} (iteration {N}). ✓ = documented ✗ = gap ~ = partial

• ✓

  src/index.ts

  — entry point, startup sequence
• ✓

  src/routes/

  — API routes (see docs/architecture.md)
• ✗

  src/workers/

  — background job processing (undocumented)
• ~

  src/models/

  — data models exist in README but schema not captured

• ✗

  scripts/deploy.sh

  — deployment procedure (gap)
• ✓

  .env.example

  — environment variables documented in CLAUDE.md

Rules:
- Use hierarchical file-tree order that mirrors the directory structure.
- Every file/area surfaced during discovery gets an entry.
- Do not fabricate entries for areas you did not scan.
- Mark `✓` only if a validation session could plausibly find the answer in docs. If uncertain, mark `~`.

Commit with doc changes (Phase 2 commit covers this file too).

---

CLAUDE.md

docs/

README.md

1. Does the target file exist? If not, create it with a

   # Title

   header.
2. Is the concept already documented in the right place? If yes, skip.
3. If documented in the wrong place (e.g., architecture details in CLAUDE.md), move it.
4. If missing, write it in the target file.

CLAUDE_LINES=$(wc -l < CLAUDE.md 2>/dev/null || echo 0)
if [ "$CLAUDE_LINES" -gt 80 ]; then
  echo "CLAUDE.md is $CLAUDE_LINES lines — over 80-line budget. Refactor."
fi

1. Identify sections that are reference material (tables >5 rows, detailed explanations, examples).
2. Move them to the appropriate

   docs/

   file.
3. Replace with a one-line pointer:

   See [docs/configuration.md](docs/configuration.md) for full env var reference.

4. Re-check the line count.

undefined

• Architecture — {one-line summary}
• Configuration — {one-line summary}
• API — {one-line summary}

undefined

Last updated by popsicle on {TODAY}.

docs/generated/

<!-- generated by popsicle on {TODAY} — do not edit manually -->

• docs/generated/env-vars.md

  — all environment variables found in the codebase (

  .env.example

  ,

  process.env.*

  ,

  os.environ

  , etc.)

• docs/generated/api-routes.md

  — all API routes extracted from router files

• docs/generated/db-schema.md

  — database schema summary (if ORM or migration files exist)

git add CLAUDE.md docs/
git commit -m "docs: popsicle iteration $ITERATION — structured agent docs

Concepts targeted: [list the concept names]
Coverage map updated. Health baseline updated."

Write `.cursor/rules/project.mdc`:

description: Project onboarding for {REPO_NAME} alwaysApply: true

**Adapter rules:**
- Adapters are thin pointers — no duplicated content.
- `CLAUDE.md` is always the source of truth (unless `--canonical agents` was set).
- Never overwrite existing custom configs (check for the `generated by popsicle` marker before writing).

Commit adapters (if any were written):

```bash
git add .github/copilot-instructions.md .cursor/rules/project.mdc 2>/dev/null
git diff --cached --quiet || git commit -m "docs: add agent adapter files (popsicle)"

• PASS (2/2): Both sessions answered correctly from docs.
• WEAK (1/2): One got it, one didn't.
• FAIL (0/2): Neither could answer.

• HIT: Agent pointed to the correct file (matches

  target_file

  from knowledge map).
• MISS: Agent pointed to wrong file or couldn't find it.

• PASS: Content PASS + Nav HIT
• PARTIAL: Content PASS + Nav MISS (info exists but hard to find), or Content WEAK + Nav HIT
• FAIL: Content FAIL (regardless of nav), or Content WEAK + Nav MISS

• Port numbers (e.g., docs say "port 3000" but code uses

  PORT=4000

  )
• Environment variable names (e.g., docs say

  DATABASE_URL

  but code reads

  DB_CONNECTION_STRING

  )
• File paths (e.g., docs reference

  src/server.js

  but it was moved to

  src/app.js

  )
• Command syntax (e.g., docs say

  npm start

  but

  package.json

  scripts changed)
• Version numbers (e.g., docs specify Node 16 but

  .nvmrc

  says 20)

STALE

{
  "type": "STALE",
  "doc_claim": "port 3000 (README line 42)",
  "actual": "PORT env var defaults to 4000 (src/config.ts:8)",
  "fix": "Update README to reference PORT env var"
}

SCORE=$((PASS_COUNT * 100 + PARTIAL_COUNT * 50))
PASS_RATE=$((SCORE / TOTAL_CONCEPTS))

• {concept}: {why it failed — what's missing or misplaced}
• ...

• {doc_claim} in

  {file}

  : actual value is

  {actual}

  . Fix: {fix}
• ...

• Business rules: {e.g., "pricing tiers defined in Notion, not in code"}
• External credentials: {e.g., "Stripe webhook secret — ask ops team"}
• Deployment procedures: {e.g., "staging deploy requires VPN + manual approval"}
• ...

• Updated

  CLAUDE.md

  : added {what}
• Updated

  docs/architecture.md

  : added {what}
• Updated

  docs/coverage-map.md

  : reflects new scan
• Updated

  docs/health-baseline.md

  : added {category} section
• Created

  docs/generated/env-vars.md

• ...

• hookshot — enforces doc freshness via commit hooks

  npx skills add fellowship-dev/dogfooded-skills/skills/ops/hookshot

• entropy-check — periodic doc drift sensor

  npx skills add fellowship-dev/dogfooded-skills/skills/ops/entropy-check

• trash-truck — removes dead/duplicate code that confuses agents

  npx skills add fellowship-dev/dogfooded-skills/skills/ops/trash-truck

• speckit — structured issue-to-PR pipeline for doc-gated features

  npx skills add fellowship-dev/dogfooded-skills/skills/ops/speckit

Commit the report:

```bash
git add "docs/popsicle-report-${TODAY}.md"
git commit -m "docs: popsicle report — iteration $ITERATION, ${PASS_RATE}% pass rate"

if [ "$PASS_RATE" -ge "$PASS_THRESHOLD" ]; then
  echo "Pass rate ${PASS_RATE}% >= ${PASS_THRESHOLD}%. Docs are agent-ready. Stopping."
  exit 0
fi

if [ "$ITERATION" -ge "$MAX_ITERATIONS" ]; then
  echo "Hit max iterations ($MAX_ITERATIONS). Pass rate: ${PASS_RATE}%. Review remaining gaps manually."
  exit 0
fi

ITERATION=$((ITERATION + 1))

1. Read the FAILed, PARTIAL, and STALE concepts from the report.
2. For nav MISSes: restructure — move content to a more discoverable location or rename the file.
3. For content FAILs: improve the docs in the target file. Fix STALE claims immediately.
4. Go back to Phase 2.

1. No rubric. The skill discovers what matters by reading the code. No upfront configuration needed.
2. Anti-cheat by architecture. Discovery artifacts live in

   /tmp

   . Validation sessions are fresh. The test is honest.
3. Docs get better every iteration. This isn't just measurement — it actively fills gaps.
4. Fresh sessions are the oracle. If a fresh agent can't learn it from docs, the docs are broken.
5. Loop-first. One iteration is useful. Five iterations with targeted fixes is transformative.
6. Agent-ready framing. Output is designed for autonomous agents, not just humans. Every doc should answer: "Can a fresh agent work independently in this repo?"
7. Coverage over completeness. A coverage map showing known gaps beats docs that claim completeness. Agents prefer honest gaps over false confidence.
8. Loose coupling. Each companion skill works independently. Popsicle generates artifacts (coverage-map.md, health-baseline.md) that other skills can optionally consume.