lodestar-docs

You are running lodestar-docs. The job is to harvest, then delete leftover writeups so the docs tree stays small. Historical record is not a goal. Git history is the archive.

This skill is optional. The other skills do not depend on it (the other six can run without it). It does not modify application source — only markdown (and, if the user ticks it, an existing Docs map in AGENTS.md).

Scripts live beside this SKILL.md under scripts/. Invoke node <this-skill>/scripts/scope.mjs survey --root <repo> (add --full or --tree <path> when the user widened scope).

Load references one hop from this file. Do not copy their procedures back here.

How to talk to the user

Anything you print or ask is read by a person who is skimming.

• Ask one clear question at a time. Say what happens for each answer.
• Name a file by its path, not by an internal key.
• Never trim or postpone a warning. A live audit run, a harvest with no home, or a spec-vs-code clash stays in.
• Point first. Bullets, not paragraphs. Blank line between blocks.
• Bold the first few words of each bullet.

Milestones

Concise chat progress — not diagnostic logs or run files:

• Opening — docs scope, homes, checks, mutation/commit policy
• Before long work — survey / propose / harvest / delete
• At boundaries — proposed counts and next step
• Closing — harvested/deleted paths, protected skips, actionable failures

Inputs

If .agents/lodestar/context.md is missing, follow references/discover-context.md and continue — observe docs trees the same way setup would. A named --tree or --full also proceeds without context. Do not invent docs/audit as a fallback when nothing is observed and the user named no folder.

When context exists, it is the primary file for repo facts. Do not read AGENTS.md for layout, output-root, or commit policy.

Capture from the survey JSON:

• <output-root>, <architecture-root>, <commits>
• <docsLayout> — recorded (or observed) path/role rows
• <homes> — markdown under home rows
• <trees> — directories and loose files in this run
• <files> — each path, size, last commit, protected

Protected rows are out of scope. Never propose deleting them.

Keep-bar

For every file, ask:

Would an agent starting fresh work tomorrow be worse off without this?

The default answer is no. The default action is delete.

A file survives only when you can name the concrete future task it helps. "Someone might want to know how we got here" is not such a task.

Steps

Work in order. Load the named reference before each step.

1. Scope — references/scope.md. Run the survey.

Say what you are covering and why. If the tree is already tight, say so and stop.

1. Homes — references/homes.md. Route harvested

facts only into <homes>. Never create a new home.

1. Triage — references/operations.md. One

operation per file.

1. Propose, then mutate — references/workflow.md.

One written proposal. Wait for OK. Harvest commit, then delete commit, honoring <commits>.

Never

• Application source (packages/**, src/**, or the equivalent in

Package Layout).

• .agents/lodestar/context.md.
• Skill definition files (.agents/skills/, .cursor/skills/,

.claude/skills/). If pruning invalidates a skill's assumptions, report that at the end and do not edit the skill.

• Live audit runs (INDEX.md plus NNN-*.md in the run root).
• In-flight plans (anything under docs/plans/ except done/ and

abandoned/).

• Silently updating a spec to match the code when they disagree. Ask

"spec or code?" with file:line on both sides.