Add update-project-guidance skill to agents package

[williamthorsen]

Problem

There's no reusable mechanism to generate or refresh .agents/PROJECT.md — each repo does it ad hoc. This skill was prototyped in devtools.afg (issue #183) and should be added to the agents package for permanent distribution.

Context

• The skill was developed interactively and tested against the devtools.afg repo
• It follows the standard skill format (SKILL.md with YAML frontmatter)
• It targets the .agents/PROJECT.md convention used across repos
• The skill is scope-aware: it reads ~/.agents/AGENTS.md to avoid duplicating global guidance

Solution

Add update-project-guidance to packages/agents/content/skills/ as a user-invocable skill.

Design rationale

The skill implements a 3-phase guided generation process:

1. Discover — Scan codebase sources (package.json, tsconfig, docs, existing guidance, ~/.agents/AGENTS.md)
2. Analyze & classify — Categorize each finding as repo-specific, universal, cross-cutting, or already covered globally
3. Generate — Produce .agents/PROJECT.md with a standard structure scaled to project complexity. Present recommendations for shared-file changes separately.

Key design decisions:

• Reads ~/.agents/AGENTS.md first as the "already covered" baseline — never duplicates global guidance
• Asks one clarifying question at a time when scope classification is ambiguous
• Handles legacy guidance files (AGENTS.md at root, .agents/AGENTS.md) by migrating content
• Ensures .claude/CLAUDE.md uses @.agents/PROJECT.md for auto-loading (not a prose pointer)
• Standard section template (overview, project structure, commands, architecture, code style, gotchas) — sections included only when they carry content

Skill content

The complete SKILL.md to add at packages/agents/content/skills/update-project-guidance/SKILL.md:

---
name: update-project-guidance
description: Generate or refresh .agents/PROJECT.md for a repository
user-invocable: true
---

# Update project guidance

Generate or refresh `.agents/PROJECT.md` — the repo-specific guidance file that gives AI agents the context they need to work effectively in the project.

**Announce at start:** "Using update-project-guidance to generate .agents/PROJECT.md."

## Arguments

- None (default): Full generation or refresh of `.agents/PROJECT.md`

## Overview

Explore the codebase, classify findings by scope, and produce a concise `.agents/PROJECT.md` that covers everything an agent needs to know about this specific project — and nothing more.

**Core principle:** Every line must merit its inclusion. Omit anything an agent would figure out on its own or that is already covered by global guidance.

## Process

### Phase 1: Discover

Gather project information from these sources (skip any that don't exist):

**Global baseline:**

- `~/.agents/AGENTS.md` — read first; this defines what's already covered globally and must not be duplicated

**Existing guidance (current state):**

- `.agents/PROJECT.md` — if it exists, this is an update; note what's already there

**Legacy and platform-specific files (migrate or flag):**

- `AGENTS.md` (repo root), `.agents/AGENTS.md` — legacy locations for project guidance; content should migrate to `.agents/PROJECT.md`
- `.claude/CLAUDE.md`, `.rovodev/` equivalents — platform-specific files. Retain only platform-specific guidance in these files; migrate everything else to `.agents/PROJECT.md`

**Project metadata:**

- `package.json` (root) — name, workspaces, scripts, engines, type
- `package.json` (each workspace package) — name, scripts, dependencies, exports
- `pnpm-workspace.yaml` / `lerna.json` / similar — monorepo structure

**Configuration:**

- `tsconfig.json` — compiler strictness, module system, paths, target
- Build configs — Vite, esbuild, webpack, Rollup, etc.
- Test configs — Vitest, Jest, Playwright, etc.
- `.editorconfig`, `.prettierrc*`, `eslint.config*` — formatting and quality rules
- CI configs — `.github/workflows/`, `.gitlab-ci.yml`, etc.

**Documentation:**

- `README.md` — project description, setup instructions
- `docs/` — architecture docs, conventions, guides

Collect findings as a flat list before moving to classification.

### Phase 2: Analyze and classify

For each finding, assign one of these scopes:

| Scope               | Destination                         | Examples                                                                                         |
| ------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Repo-specific**   | `.agents/PROJECT.md`                | Package descriptions, build order, architecture, repo-specific gotchas                           |
| **Already covered** | Omit                                | Anything `~/.agents/AGENTS.md` already states (style preferences, workflow rules, commit format) |
| **Universal**       | Recommend for `~/.agents/AGENTS.md` | Conventions that apply to all repos but aren't yet in global guidance                            |
| **Cross-cutting**   | Best judgment; ask if unclear       | Tool-specific guidance that applies to some repos (e.g., a shared CLI tool)                      |

**Rules:**

- Do not duplicate global conventions. If a repo-specific convention _extends_ a global one, include only the delta.
- When unsure about scope, ask the user — one question at a time, prefer multiple choice.
- Content that is obvious from reading the code (e.g., "this project uses TypeScript") adds no value. Include only what would save an agent from a wrong assumption or a slow discovery.

### Phase 3: Generate

Produce `.agents/PROJECT.md` using the standard structure below. Include only sections that carry content.

```markdown
# {Project title}

## Overview

{What the project is, what problem it solves, key technology. 2-4 sentences.}

## Project structure

{Monorepo layout, package descriptions with their purpose, key files worth knowing about. Use a compact format — not a full directory tree.}

## Commands

{Development, testing, build, and quality commands. Group by scope (root-level, package-level, package-specific). Omit commands that are obvious from package.json.}

## Architecture

{Build system, key patterns, data flow between components, dependency ordering. Focus on things that affect how an agent should approach changes.}

## Code style

{Repo-specific conventions not covered by global guidance. Omit if everything is already global.}

## Gotchas

{Non-obvious things that trip up agents: build order dependencies, tools with surprising behavior, naming inconsistencies, common mistakes.}
```

**Presentation:**

1. Present the draft `PROJECT.md` to the user for review.
2. Iterate until approved.
3. Write the file to `.agents/PROJECT.md` (create the directory if needed).
4. Ensure `.claude/CLAUDE.md` auto-includes the file via `@.agents/PROJECT.md` (not a prose pointer). Create or update the file if needed.
5. If there are recommendations for shared-file changes (`~/.agents/AGENTS.md` or new shared files), present them separately after the main file is approved.

## Quality checklist

Before presenting the draft, verify:

- [ ] `.agents/preferences.yaml` exists and has `project.slug` set — warn the user if missing
- [ ] No line duplicates content from `~/.agents/AGENTS.md`
- [ ] No section merely restates what's obvious from the code
- [ ] Commands listed are ones an agent would actually need (not exhaustive npm script listings)
- [ ] Each command group states where to run it (repo root, package directory, etc.) — don't assume the agent knows
- [ ] Architecture section focuses on decisions that affect how to make changes, not documentation for its own sake
- [ ] Gotchas are genuinely non-obvious — not things an agent would discover from a type error or linter warning

## Key principles

- **Conciseness over completeness** — a shorter file that covers the essentials is better than a comprehensive one that wastes context window
- **Scope-aware** — read global guidance first, never duplicate it
- **Interactive** — ask when classification is unclear, but don't overwhelm with questions
- **Portable** — this skill works in any repo that follows the `.agents/PROJECT.md` convention
- **Honest about uncertainty** — if something might belong in shared guidance, say so rather than silently including it

Acceptance criteria

• Skill exists at packages/agents/content/skills/update-project-guidance/SKILL.md
• Skill installs to ~/.claude/skills/update-project-guidance/SKILL.md via codeassembly-agents install
• Skill is user-invocable (/update-project-guidance)