Seed Project Guidance

Seed Project Guidance

Build a useful project map from repository evidence while keeping code, tests, schemas, and manifests as the executable source of truth. Do not mirror every file or add mandatory file-header contracts.

Invariants

• Never overwrite an existing AGENTS.md that lacks the seeder-managed markers.
• Never modify AGENTS.override.md, symlinked guidance, untrusted projects, temporary paths, vendor/cache trees, or projects with .codex/disable-project-guidance-seeding.
• Never read evidence through a symlink or from a resolved path outside the selected repository scope.
• Keep the generated block deterministic. Route semantic notes outside the managed block to $refine-project-guidance.
• Do not add personality text, generic engineering advice, private-reasoning instructions, file inventories, speculative architecture, or L3 comments.
• Stay single-agent. This workflow does not justify delegation.

1. Probe and seed the repository root

Resolve this Skill directory, then run:

python3 /scripts/seed_project_guidance.py probe --cwd "$PWD"
python3 /scripts/seed_project_guidance.py seed --cwd "$PWD"

The script derives only observable facts from manifests, lockfiles, package scripts, Make/Just targets, canonical docs, CI files, and bounded module discovery. It serializes Rootloom writers through the Git common directory, verifies that AGENTS.md still matches its initial snapshot, writes atomically, and updates only its managed block. A concurrent edit causes a safe skip instead of an overwrite.

If the result is user_owned_guidance, override_exists, untrusted_project, disabled, or another skip reason, respect it. Do not bypass the gate unless the user explicitly asks to seed that exact project and the project has been reviewed as safe.

2. Hand off semantic refinement

For a non-trivial first task, invoke $refine-project-guidance when the generated facts are insufficient. That workflow may read the smallest relevant set of:

• the generated AGENTS.md;
• the nearest README or product document;
• manifests and CI named by the managed block;
• the task's source entry point and nearest tests.

Do not add semantic prose inside this workflow. Keeping deterministic collection and model judgment separate makes refreshes auditable and avoids rewriting user-owned guidance.

3. Seed nested guidance lazily

Use module_candidates from the probe. Create nested guidance only when the current work enters a module that has its own manifest and materially different commands, architecture, or invariants.

python3 /scripts/seed_project_guidance.py seed \
  --cwd "$PWD" \
  --target path/to/module

Create at most three nested guidance files in one repository pass and never go deeper than three directories from the Git root. Do not seed every candidate preemptively.

4. Validate before continuing

Run validation for every created or refreshed file:

python3 /scripts/seed_project_guidance.py validate \
  --file path/to/AGENTS.md

Validation must pass before treating the guidance as complete. It checks size, managed-block drift, placeholders, symlinks, and secret-like content.

Completion

Continue the user's original task after seeding. Mention project-guidance creation only when it changed the working tree or when a gate prevented seeding. Do not make the seeding process the main deliverable unless the user asked about it.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: liyanqing90
• Source: liyanqing90/rootloom
• License: MIT

Install and usage instructions live in the source repository linked above.