# Project Guidance

> Seed, refresh, refine, or validate concise evidence-backed AGENTS.md guidance. Deterministic scripts own the managed block; model judgment may add only durable repository-specific invariants outside it.

- **Type:** Skill
- **Install:** `agentstack add skill-qingye-lab-rootloom-project-guidance`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [qingye-lab](https://agentstack.voostack.com/s/qingye-lab)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [qingye-lab](https://github.com/qingye-lab)
- **Source:** https://github.com/qingye-lab/rootloom/tree/main/plugins/rootloom/skills/project-guidance
- **Website:** https://qingye-lab.github.io/rootloom/

## Install

```sh
agentstack add skill-qingye-lab-rootloom-project-guidance
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```text

```

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

```text
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:

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

## Seed or refresh

Run the deterministic writer:

```bash
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:

```bash
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:

```bash
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](https://github.com/qingye-lab)
- **Source:** [qingye-lab/rootloom](https://github.com/qingye-lab/rootloom)
- **License:** MIT
- **Homepage:** https://qingye-lab.github.io/rootloom/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-qingye-lab-rootloom-project-guidance
- Seller: https://agentstack.voostack.com/s/qingye-lab
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.