---
name: project-guidance
description: Create, refine, or validate repository guidance on explicit user request; preserve real-path scope, managed ownership, and unrelated content.
---

# Project guidance

A user's explicit request to create, refresh, or refine guidance authorizes that work
within the stated file scope; the user need not name this Skill. Review/validation requests
are read-only. Ordinary coding tasks and natural-language repository guidance do not
authorize persistent edits. The SessionStart Hook is always read-only.

The existing repository-authored exception is the exact standalone marker:

```text
<!-- rootloom:refine-once version=1 -->
```

It permits one refinement of that marked file only. Remove it with the successful edit;
validation does not consume it. Preserve any explicit independent approval requirement.

## Existing guidance

Resolve each target's real path and symlink chain before editing. Read its applicable
global and root-to-target guidance and only the evidence needed for the requested change.
An entry pointing outside the authorized repository is external content: propose its diff
unless the user has separately authorized that real target. Preserve backups and unrelated
edits; do not reset or overwrite user work to simplify refinement.

For wording-only refinement, read [semantic-refinement.md](references/semantic-refinement.md)
and edit authorized unmarked content directly. No manifest/CI/module probe is needed.
Keep model judgment outside generated managed markers. Add only durable, supported rules
that change a real decision; remove redundant wording without dropping unique constraints.

## Generate or refresh project facts

Resolve this Skill directory and use its deterministic probe and writer:

```bash
python3 <skill-dir>/scripts/seed_project_guidance.py probe --cwd "$PWD"
python3 <skill-dir>/scripts/seed_project_guidance.py seed --cwd "$PWD"
```

The writer owns only its generated project block. It must not overwrite unmarked guidance,
`AGENTS.override.md`, symlinked or external targets, disabled projects, or vendor/cache trees.
Respect its skip reasons. Only after an exact `untrusted_project` response and the user's
explicit persistence request for this repository may it retry once with `--allow-untrusted`;
this does not change host trust or authorize other writes.

Either `.rootloom/disable-project-guidance` or legacy
`.codex/disable-project-guidance-seeding` disables session context and persistent seeding.
Use `--target path/to/module` only for a genuine manifest-backed boundary with distinct
commands, ownership, or contracts; create at most three nested files per pass within three
levels of the Git root. Do not mirror the directory tree.

## Verify

For edited unmarked guidance or blocks generated by this project seeder:

```bash
python3 <skill-dir>/scripts/seed_project_guidance.py validate --file path/to/AGENTS.md
```

The global working-agreement block belongs to Setup, even though it shares the marker
prefix. Compare that block with the Setup-owned template and use Setup's plan/status for
installation state; do not treat it as a generated project block or refresh it with this writer.

Check changed rules against the inherited chain and a concrete misuse scenario. Compare the
final diff with the authorized paths and preserve unrelated content. Report actual checks and
remaining gaps. Use no-cache verification where practical; remove only temporary artifacts
created by this task. Continue any independent authorized work after guidance verification.