setup · git:20260702.3e0422e · 2026-07-02 · sha256 66feac5dac96c1ec

setup git:20260702.3e0422eA

Immutable. This exact content never changes and is served at /api/v1/blob/66feac5dac96c1ec.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_wujxop25yha3ztjc/66feac5dac96c1ec48fac14db7a4a4f7ab3831d5c1e504ac08c03eabe5f42bfe.json

Then /plugin install setup@markdownregistry-wujxop25yha3ztjc in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: setup
description: Scaffold the agent-orch project-memory system into THIS repository (new or existing) — copies the template tree into .agent-orch/, then runs a guided discovery pass that drafts a real STATUS, MAP, TECH_STACK, and PRODUCT from the actual codebase and confirms with the user before saving. Use when the user says "set up agent-orch", "initialize agent-orch", "add project memory", or when a repo has no .agent-orch/ and the user wants one. Run once per repo.
---

# Set up agent-orch in this repo

Scaffold the durable project-memory system, then populate it from the real
codebase so it ships useful — not blank. **Discovery drafts; the user confirms
before anything is saved.** Never invent project facts (RULES rule 5).

## 0. Locate templates & detect existing install
- The template tree is bundled with this plugin at `../../templates/` relative
  to this skill file (i.e. `<plugin-root>/templates/`). Resolve that absolute path.
- Check whether `.agent-orch/` already exists in the project root:
  - **Exists** → do NOT overwrite. Tell the user it's already set up; offer to
    *refresh* specific files (e.g. re-run discovery for STATUS/MAP/TECH_STACK)
    or seed a CONTEXT.md. Stop here unless they choose a refresh.
  - **Absent** → continue.

## 1. Copy the template tree
Copy the bundled `templates/` into the project as `.agent-orch/`, preserving
structure (BOOT, RULES, STATUS, MAP, CHANGELOG, context/, docs/ with
SKILL-WORKFLOW.md, tasks/ with inbox/now/done). Keep the `.gitkeep` files.
Do not edit RULES' universal section.

## 2. Guided discovery (read the repo — do not guess)
Read what actually exists, quietly:
- Build/manifest files: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`,
  `composer.json`, `Gemfile`, Makefile, CI config, framework config files.
- Top-level directory layout and the largest/most-central source folders.
- `git log --oneline -20` and current branch for recent direction.
- Any existing README for product intent.
Derive: project name, type, primary stack, common commands (build/dev/test/lint),
deploy target, and the **verify commands** for RULES rule 10.

## 3. Draft, then CONFIRM before saving
Present concise drafts for the user to correct:
- **STATUS.md** — Current State (where the repo stands now), Active Work (none
  unless evident), Blockers (none unless evident). Keep ≤ 25 lines.
- **context/TECH_STACK.md** — stack, commands, env vars, deploy, verify commands.
- **MAP.md** — entry points, key directories, where to make common changes.
- **context/PRODUCT.md** — only if a README/product intent is discoverable;
  otherwise leave the template prompts and say so.
- Replace the `<PROJECT_NAME>/<PROJECT_TYPE>/<PRIMARY_STACK>` placeholders in BOOT.md.
**Wait for the user's confirmation/edits. Only then write the files.** For
anything you cannot determine from the repo, leave the template prompt in place
rather than inventing — and tell the user what you left blank.

## 4. Seed folder-level CONTEXT.md (offer, then confirm)
Identify the 1–3 folders with the most local architecture or conventions a
future session should read before editing (e.g. a design-system dir, a core
domain module). Propose a short CONTEXT.md for each (structure, conventions,
gotchas — not a file listing). Save only the ones the user approves. These are
auto-injected by the PreToolUse hook on first edit in that folder.

## 5. Thin-fallback CLAUDE.md
The plugin's hooks load full state when installed, but a clone opened WITHOUT
the plugin needs a minimal fallback. In the project root:
- If `CLAUDE.md` exists, append (don't duplicate) a short block. If it doesn't,
  create one. Never create `AGENTS.md` if `CLAUDE.md` exists, or vice versa —
  edit whichever is present.
- The block:

```markdown
## Project memory (agent-orch)
This repo uses agent-orch. With the plugin installed, the SessionStart hook
auto-loads `.agent-orch/STATUS.md` + `RULES.md`. If hooks are off, read those
two first. Hard rules (always apply):
- Preserve user work; never delete/overwrite/revert changes unless asked.
- Never `git add -A` / `git add .` for a scoped commit — stage only what you changed.
- Verify with the commands in `.agent-orch/context/TECH_STACK.md` before claiming done.
- Update `.agent-orch/STATUS.md` + `CHANGELOG.md` whenever code or config changes.
```

## 6. Finish
Tell the user: setup is complete; the SessionStart hook will load STATUS+RULES
from the next session; the PreToolUse hook injects any folder's CONTEXT.md on
edit; the Stop hook nudges state updates. They can edit `.agent-orch/*` directly
anytime. Re-run this skill only to refresh discovery or start over.

Add a dated line to `.agent-orch/CHANGELOG.md`: "Project initialized with agent-orch."