Project Guidance

Project guidance

Use when the user explicitly asks to persist, refresh, refine, or validate project guidance, or when active repository guidance requests validation. The SessionStart Hook is read-only and never invokes a writer.

Persistent seed, refresh, or refinement requires explicit user intent. The only repository-authored exception is this exact standalone one-time marker in active guidance:

It authorizes one refinement of that marked file only. Remove it in the same successful write; validation does not consume it. Natural-language guidance alone never authorizes persistent refinement or any other write.

Route the mode

explicit seed request                  → seed
explicit refresh request               → refresh
explicit refinement or exact marker    → refine
user/repository validation request     → validate

Resolve this Skill directory and probe first:

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

Seed or refresh

Run the deterministic writer:

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

It derives observable facts from manifests, lockfiles, package scripts, Make/Just targets, canonical docs, CI, and bounded module discovery. It locks through the Git common directory, checks concurrent edits, writes atomically, and owns only its marked managed block.

Never overwrite an unmarked existing AGENTS.md, AGENTS.override.md, symlinked guidance, untrusted or disabled projects, temporary paths, vendor/cache trees, or evidence resolved outside the repository. Respect every script skip reason.

Refine

Read [references/semantic-refinement.md](references/semantic-refinement.md). Keep model judgment outside managed markers. Add only evidence-backed statements that change a future implementation, review, verification, or safety decision.

Nested guidance

Use module_candidates from the probe only when current work enters a genuine module with its own manifest and materially different commands, ownership, contracts, or invariants:

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

Create at most three nested files per pass and do not go deeper than three directories from the Git root. Never mirror the directory tree.

Validate

Run this for every created, refreshed, or inspected managed file:

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

Inspect the effective root-to-current-directory chain for contradictions, duplication, stale paths, broken commands, oversized context, placeholders, secrets, and rules that cannot be verified. Continue the user's original task after guidance work.

Before completion, compare the final worktree with the starting state and authorized paths. Verification must not leave caches, coverage, build output, or other generated artifacts. Prefer no-cache options; otherwise remove only artifacts created by this task, never pre-existing user work.

Source & license

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

• Author: qingye-lab
• Source: qingye-lab/rootloom
• License: MIT
• Homepage: https://qingye-lab.github.io/rootloom/

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