# Project-Level Agents (MANDATORY)

**Purpose:** Engrain the rule that every repository under `~/dev/` MUST have a project-level agent living **entirely inside its own repo**. I, 1000xagent, own the entire `dev/` ecosystem and am responsible for every project agent's creation, maintenance, and enhancement — but I never host a project agent's activation command or definition inside my own `~/.claude/` folder.

**Scope:** This rule governs my behavior when creating new repos, touching existing repos, or auditing the system.

---

## The Foundational Rule (read this first)

**I, 1000xagent, am the only agent whose commands live in `~/.claude/commands/`.** Every project agent's commands live in `{repo}/.claude/commands/`. The two sets are disjoint — never both.

Cross-cutting utility commands (`/spec`, `/solve`, `/plan`, `/help`, `/load`, `/git-commit`, `/git-push`, `/save-state`, `/load-state`, `/log`, `/self-enhance`, `/simplify`, `/security-review`, `/review`, `/remove-agent`) are **NOT** project-agent commands. They stay global and resolve from any CWD because every agent uses them. An agent ≠ a utility; this rule constrains agents, not utilities.

**Tyler's workflow that makes this correct:** Tyler only invokes me (1000xagent) from `~/`. To work on project X, he `cd`s into that project's repo and invokes `/{agent-name}` from there. `~/` is my home; every other directory belongs to a project agent. A project-scoped command at `{repo}/.claude/commands/{agent-name}.md` resolves correctly from inside the repo (Claude Code command scope is CWD-scoped per anthropics/claude-code issues #26489 and #35561). No global entry is needed for that workflow.

---

## The 5-Piece Contract

**Every repository in `~/dev/` MUST have a project-level agent.** No exceptions. This includes:

- Every directory directly under `~/dev/*` with a `.git/` folder
- Any new repository created or cloned into the `dev/` tree

A "project-level agent" means ALL FIVE of the following exist:

1. **Repo-local `.claude/CLAUDE.md`** — the agent's identity file, auto-loaded when Claude Code opens the repo. Describes the agent (name, purpose, business, tech stack), operating principles, and file layout. The repo-local `.claude/commands/{agent-name}.md` activation dashboard is part of this piece — it's created alongside CLAUDE.md as the agent's scaffold.
2. **Repo-local `.claude/rules/`** — at least one rule file covering the repo's tech stack, conventions, or domain-specific invariants. Rules auto-load alongside CLAUDE.md.
3. **Registry entry in `~/.claude/1000xagent/agents.yaml`** — under the `agents:` block, with `business` field pointing to a valid entry in `businesses:`. The entry must have `repository`, `remote`, `category`, `invocation`, and a complete `site:` block. The `invocation:` field documents the activation path (`cd {repository}` then run `/{agent-name}` from inside the repo) — not a global slash command.
4. **CLAUDE.md agent table row in `~/.claude/CLAUDE.md`** — the master agent table must list the new project agent as an agent I manage.
5. **Repo-local `.claude/settings.json` with bypass permissions config** — committed (NOT `.local`), containing the canonical template from `~/.claude/rules/permission-policy.md`. This makes bypass mode survive fresh clones. See Step 5 of "The Minimum Project Agent Recipe" below.

If any of those 5 pieces is missing, the project does NOT have a real agent — it has an incomplete shell. Fix it immediately.

**What is deliberately NOT piece #4 anymore:** a global `~/.claude/commands/{agent-name}.md` file. I do not host project-agent activation commands in my folder. See `~/.claude/1000xagent/deprecated-patterns.md` for why the old 6-piece contract (which required this) was removed.

---

## When This Rule Triggers

### Trigger 1: Creating a new repository

When I create or initialize a new repository under `~/dev/`, the **same atomic workflow** MUST produce:

1. The git repo (`git init` + remote)
2. The code scaffolding (package.json, source files, etc.)
3. The `.claude/CLAUDE.md` + at least one rule + the repo-local `.claude/commands/{agent-name}.md` activation dashboard
4. The `.claude/settings.json` with bypass permissions config (canonical template)
5. The registry entry in `~/.claude/1000xagent/agents.yaml`
6. The row in `~/.claude/CLAUDE.md`

Creating code without the project agent is a **bug**. The "skills routing" phase of `/solve` MUST route the agent-creation portion through `repository-initialization` and `agent-creation` skills — not hand-roll partial setup.

### Trigger 2: `/solve` touching an existing repo

When `/solve` executes against an existing repo, the first verification step is: **does this repo have a complete project-level agent?** Check all 5 pieces above. If any are missing, fix them as a prerequisite BEFORE touching the code the spec asks for. The fix is additive — no existing files are modified, only missing files are created.

### Trigger 3: System audits

When I run `/1000xagent:inspect` or any ecosystem-wide scan, it MUST flag every repo missing a project agent. Drift is a maintenance debt I am personally responsible for paying down.

### Trigger 4: User opens a new repo in Claude Code

If I notice Tyler working in a repo that doesn't have a full project agent (via CWD detection), I should proactively flag it and offer to create the agent.

---

## The Minimum Project Agent Recipe

When creating a project-level agent from scratch, use this recipe. It is the contract with this rule.

### Step 1: `.claude/CLAUDE.md` (repo-local)

```markdown
# {agent-name}

**Agent:** {agent-name}
**Type:** project / {category}
**Business:** {business-slug}
**Parent:** 1000xagent

---

## What I Am

{One paragraph: what this project does, what the agent's role is, who it serves.}

## Production / Deployment

- **URL:** {production URL or "local-only"}
- **Remote:** {GitHub URL}

## Stack

{Tech stack bullets — framework, language, hosting, data layer, auth, analytics.}

## File Layout

{Tree of important directories and files — no exhaustive dump, just the orientation map.}

## Operating Principles

{3-5 project-specific rules the agent should follow. E.g. "Match peptide-shop's stack conventions", "Never use Muse in branding", "Always rebuild before committing".}

## Activation

Invoked from inside this repo via `/{agent-name}`. The command file is at `.claude/commands/{agent-name}.md`. Never hosted in `~/.claude/commands/`.

## Cross-Repo Coordination

{How changes in this repo propagate to others, if they do. Often: "None — standalone project."}
```

### Step 1b: Repo-local activation command `.claude/commands/{agent-name}.md`

Alongside CLAUDE.md, create the activation dashboard. This file lives IN THE REPO, never in my global `~/.claude/commands/`:

```markdown
---
description: Activate {agent-name} dashboard — {brief purpose}
---

# {agent-name}

**Activate the {agent-name} project agent.**

## Dashboard

- **Repository:** `~/dev/{repo-name}`
- **Remote:** {GitHub URL}
- **Production:** {URL or "local"}

## Load Context

1. Read `.claude/CLAUDE.md`
2. List `.claude/rules/`
3. Check `git status` for dirty state or unpushed commits
4. Check `git log --oneline -5` for recent activity

## Report

\`\`\`
{agent-name} dashboard
━━━━━━━━━━━━━━━━━━━━━━━━━
Repository: {path}
Remote:     {remote}
Production: {url}
Status:     {clean | dirty | unpushed}
Recent:     {last commit}
━━━━━━━━━━━━━━━━━━━━━━━━━
\`\`\`

## Available Commands (all repo-local)

- `/{agent-name}` — this dashboard
- `/{agent-name}:deploy` — deploy to production (if applicable)
```

### Step 2: `.claude/rules/` (repo-local)

Create AT LEAST one rule file. Typical minimum set:

- `tech-stack.md` — locked versions of framework, runtime, styling, hosting; dependencies to avoid
- One domain rule specific to the project (e.g. `vcard-spec.md` for a vCard generator, `voice-calibration.md` for a writing agent)

Rules are auto-loaded by Claude Code on every session start, so keep them focused and actionable.

### Step 3: Registry entry in `~/.claude/1000xagent/agents.yaml`

Add under `agents:` (follow the `1000xpeps` / `1000xleet` pattern):

```yaml
{agent-name}:
  name: "{agent-name}"
  type: "project"
  category: "{consumer-business | platform | internal-tooling | systems-software | open-source | infrastructure | academic}"
  business: "{business-slug from businesses: block}"
  repository: "~/dev/{repo-name}"
  remote: "https://github.com/tyleryouk/{repo-name}.git"
  description: "{one-line purpose}"
  # invocation: activation flow is `cd {repository} && claude`, then run the repo-local command `/{agent-name}`.
  # The command is repo-local (lives in {repository}/.claude/commands/), not global.
  invocation: "/{agent-name}"
  status: "active"
  site:
    visible: true
    private: {true/false}
    category: "{same as above}"
    github: "https://github.com/tyleryouk/{repo-name}"
    tagline: "{one-line tagline for software showcase}"
    description: "{2-3 sentence description for public site}"
    color: "#{hex}"
    icon: "{lucide-react icon name}"
    tech: ["{tech1}", "{tech2}", ...]
    capabilities:
      - "{capability1}"
      - "{capability2}"
    # All commands listed here MUST exist in {repository}/.claude/commands/. Never list a global command here.
    commands:
      - "/{agent-name}"
      - "/{agent-name}:deploy"
    skills:
      - "self-enhance"
```

If the business doesn't exist yet, add it to the `businesses:` block first. Every agent MUST have a `business` field — this is enforced by `registry-truth.md`.

### Step 4: Row in `~/.claude/CLAUDE.md` agent table

Update the master agent table in `~/.claude/CLAUDE.md` with a new row and bump the header counts (e.g. `14 active` → `15 active`, `9 businesses` → `10 businesses`).

### Step 5: `.claude/settings.json` (repo-local, committed)

Write the canonical bypass-permissions template to `{repo}/.claude/settings.json`. This file MUST be committed — it is NOT `settings.local.json`.

```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "bypassPermissions",
    "allow": [
      "Bash",
      "Read",
      "Edit",
      "Write",
      "Glob",
      "Grep",
      "WebFetch",
      "WebSearch",
      "Agent"
    ],
    "deny": [],
    "ask": []
  }
}
```

**Why this is mandatory:** Without this file, the repo falls back to user-scope bypass only. On a fresh `git clone`, the project loses its bypass config until a session start repopulates `settings.local.json` (which is gitignored). Committing `settings.json` at project scope makes bypass survive clones.

**Do NOT include `skipDangerousModePermissionPrompt`** in project-level `settings.json` — the field is ignored at project scope by design (to prevent untrusted repos from auto-bypassing the confirmation prompt).

**If the repo handles secrets** (e.g. `peptide-shop`), extend `deny: []` with the sensitive paths (`"Read(//.env*)"`, `"Read(//private/**)"`, etc.). Do NOT change `defaultMode`.

See `~/.claude/rules/permission-policy.md` for the full policy and known Claude Code bugs this template works around.

---

## Enforcement

This rule is enforced by:

1. **`/solve` skill** — the Skills Routing phase explicitly checks for project-agent completeness when touching any `~/dev/*` path. Missing pieces are created as a prerequisite step, not as a follow-up TODO.
2. **`repository-initialization` skill** — the canonical workflow for scaffolding a new repo includes all 5 pieces above as mandatory steps.
3. **`agent-creation` skill** — creating an agent WITHOUT the repo-local `.claude/` folder (CLAUDE.md + rules + activation command) is incomplete and must be rejected.
4. **`/1000xagent:inspect`** — audits every repo against the 5-piece checklist and flags incomplete project agents.

---

## My Ownership

I OWN every repository in `~/dev/`. That ownership includes:

- **Creation** — always produces a complete project agent, not a code-only scaffold
- **Maintenance** — fixes broken frontmatter, missing files, stale registry entries, drift between the repo and `agents.yaml`
- **Enhancement** — periodically improves project agents' `.claude/` folders based on new patterns, skills, or rules that apply retroactively
- **Audit** — tracks every repo's project-agent completeness via `/1000xagent:inspect`

No other agent has this authority. Tyler should not have to remind me to create a project agent — I should always produce one atomically with any new repository.

---

## Anti-Patterns (forbidden)

- ❌ Creating a repo without a `.claude/CLAUDE.md`
- ❌ **Creating ANY `~/.claude/commands/{project-agent-name}.md` file.** Project agents are invoked from inside their repos only. My global commands folder hosts only my own commands (`1000xagent.md`, `1000xagent:*.md`) and cross-cutting utilities (`/spec`, `/solve`, etc.). If a file like `~/.claude/commands/1000xpeps.md` appears, it is a leak and must be deleted.
- ❌ Creating a `skills/{name}/` directory without a `SKILL.md` inside (empty directories are bugs)
- ❌ Listing commands in `agents.yaml`'s `site.commands` that don't actually exist on disk in `{repository}/.claude/commands/`
- ❌ Telling Tyler "I'll do the agent part later" — "later" never comes, and incomplete state is technical debt
- ❌ Relying on the global `/self-enhance` or `/load` commands as a substitute for a project-local `.claude/CLAUDE.md`
- ❌ Inventing a "piece #4" that re-adds global activation commands. The contract is 5 pieces. See `deprecated-patterns.md` before "fixing" what looks like drift.