[PIR #909] Document area/* as the organizing axis for codev issues

AGENTS.md

@@ -119,6 +119,35 @@ Key locations:
 - **During implementation**: Use `porch status <id>` for detailed phase status
 - **After completion**: Close the GitHub Issue when PR is merged
 
+### Area Labels — the organizing axis for issues
+
+`area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees.
+
+**Labels**:
+
+| Label | Scope |
+|---|---|
+| `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` |
+| `area/vscode` | VSCode extension — sidebar views, panel-area views, commands, keybindings |
+| `area/dashboard` | Tower web dashboard — the `@cluesmith/codev-dashboard` React/Vite package, served by Tower and opened in a browser (distinct from any VSCode UI) |
+| `area/consult` | `consult` CLI and consultation tooling |
+| `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. |
+| `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` |
+| `area/porch` | Porch state machine / protocol orchestration |
+| `area/protocols` | Protocol definitions (`codev/protocols/`, `codev-skeleton/protocols/`) — distinct from `area/porch` (orchestration) |
+| `area/config` | `.codev/config.json` and workspace setup |
+| `area/terminal` | Terminal-specific — PTY, VSCode terminal pane |
+| `area/scaffold` | Install path — `codev init` / `adopt` / `update` / `doctor`, `codev-skeleton/`, the four-tier resolver |
+| `area/release` | Release tooling — version bumps, release protocol artifacts, release scripts |
+| `area/web` | Marketing site / web content — the `marketing/` directory |
+| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`, `packages/types`) |
+
+**Policy:**
+
+- **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels.
+- **No `type:*` labels.** Codev classifies issues by area only.
+- `area/` uses **slash**. Other label families (if ever introduced) would keep colons.
+
 **🚨 CRITICAL: Two human approval gates exist:**
 - **conceived → specified**: AI creates spec, but ONLY the human can approve it
 - **committed → integrated**: AI can merge PRs, but ONLY the human can validate production

CLAUDE.md

@@ -119,6 +119,35 @@ Key locations:
 - **During implementation**: Use `porch status <id>` for detailed phase status
 - **After completion**: Close the GitHub Issue when PR is merged
 
+### Area Labels — the organizing axis for issues
+
+`area/*` is the **primary axis** for organizing GitHub Issues in this repo. When users ask to group, edit, audit, or bulk-move issues, treat `area/*` as the grouping dimension first — not `type:*` (we don't use them), not milestones, not assignees.
+
+**Labels**:
+
+| Label | Scope |
+|---|---|
+| `area/docs` | Documentation — this repo, CLAUDE/AGENTS, role files, `codev/resources/` |
+| `area/vscode` | VSCode extension — sidebar views, panel-area views, commands, keybindings |
+| `area/dashboard` | Tower web dashboard — the `@cluesmith/codev-dashboard` React/Vite package, served by Tower and opened in a browser (distinct from any VSCode UI) |
+| `area/consult` | `consult` CLI and consultation tooling |
+| `area/tower` | Tower server + `afx` / agent-farm CLI. **No separate `area/agent-farm`** — afx work goes here. |
+| `area/cross-cutting` | Multi-area work — used **alone**, never alongside another `area/*` |
+| `area/porch` | Porch state machine / protocol orchestration |
+| `area/protocols` | Protocol definitions (`codev/protocols/`, `codev-skeleton/protocols/`) — distinct from `area/porch` (orchestration) |
+| `area/config` | `.codev/config.json` and workspace setup |
+| `area/terminal` | Terminal-specific — PTY, VSCode terminal pane |
+| `area/scaffold` | Install path — `codev init` / `adopt` / `update` / `doctor`, `codev-skeleton/`, the four-tier resolver |
+| `area/release` | Release tooling — version bumps, release protocol artifacts, release scripts |
+| `area/web` | Marketing site / web content — the `marketing/` directory |
+| `area/core` | Shared core library / forge abstraction (`packages/core`, `packages/codev/src/lib`, `packages/types`) |
+
+**Policy:**
+
+- **Exactly one** `area/*` per issue. Multi-area work uses `area/cross-cutting` *alone* — never two `area/*` labels.
+- **No `type:*` labels.** Codev classifies issues by area only.
+- `area/` uses **slash**. Other label families (if ever introduced) would keep colons.
+
 **🚨 CRITICAL: Two human approval gates exist:**
 - **conceived → specified**: AI creates spec, but ONLY the human can approve it
 - **committed → integrated**: AI can merge PRs, but ONLY the human can validate production

codev-skeleton/roles/architect.md

@@ -257,6 +257,33 @@ gh issue view 42
 Update status as projects progress:
 - `conceived` → `specified` → `planned` → `implementing` → `committed` → `integrated`
 
+## Working with Project Labels
+
+If your project uses prefix-structured labels (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, the recipes below are the architect-specific bulk operations — substitute `<prefix>` and `<value>` for your project's actual labels. (Skip this section if your project doesn't use prefix-structured labels.)
+
+**Operational recipes:**
+
+```bash
+# Confirm the current label vocabulary (use before any label op to catch drift)
+gh label list --search "<prefix>/"
+
+# Group: tally open issues by <prefix>/* label
+gh issue list --state open --limit 500 --json number,title,labels --jq \
+  'group_by([.labels[].name | select(startswith("<prefix>/"))]) | .[] | "\(.[0].labels[] | select(.name | startswith("<prefix>/")).name): \(length)"'
+
+# Edit: change a label on a single issue
+gh issue edit <N> --remove-label <prefix>/<old> --add-label <prefix>/<new>
+
+# Audit: find open issues with no <prefix>/* label
+gh issue list --state open --limit 500 --json number,title,labels \
+  --jq '.[] | select([.labels[].name] | any(startswith("<prefix>/")) | not) | "#\(.number) \(.title)"'
+
+# Bulk-move: relabel all open <prefix>/<old> issues to <prefix>/<new>
+for n in $(gh issue list --state open --limit 500 --label <prefix>/<old> --json number --jq '.[].number'); do
+  gh issue edit "$n" --remove-label <prefix>/<old> --add-label <prefix>/<new>
+done
+```
+
 ## Handling Blocked Builders
 
 When a builder reports blocked:

codev-skeleton/templates/AGENTS.md

@@ -47,6 +47,28 @@ This succeeds if the protocol is registered (including via the skeleton fallback
 - **Reviews**: `codev/reviews/` - Reviews and lessons learned
 - **Protocols**: `codev/protocols/` - Development protocols
 
+## Working with Project Labels
+
+If your project uses GitHub labels with a structured prefix (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, treat them as the primary axis when users ask about grouping, editing, or auditing. Run `gh label list` to discover what your project uses, infer the convention from how existing issues are labeled, and ask the user to confirm before applying broad changes.
+
+**Discover the convention:**
+
+```bash
+# List all labels (skim for structured prefixes)
+gh label list
+
+# Filter to a specific prefix family
+gh label list --search "<prefix>/"
+```
+
+**Inferring policy:** conventions vary across projects. Common patterns:
+
+- **One label per axis.** Many projects allow only one `<prefix>/*` label per issue, with a dedicated multi-axis fallback (e.g. `<prefix>/cross-cutting`).
+- **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`).
+- **Separator style.** `<family>/<value>` and `<family>:<value>` both exist in the wild — respect whatever convention the project already uses.
+
+Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume.
+
 ## Quick Start
 
 1. For new features, start with the Specification phase

codev-skeleton/templates/CLAUDE.md

@@ -45,6 +45,28 @@ This succeeds if the protocol is registered (including via the skeleton fallback
 - **Reviews**: `codev/reviews/` - Reviews and lessons learned
 - **Protocols**: `codev/protocols/` - Development protocols
 
+## Working with Project Labels
+
+If your project uses GitHub labels with a structured prefix (e.g. `area/*`, `team/*`, `priority/*`) to organize issues, treat them as the primary axis when users ask about grouping, editing, or auditing. Run `gh label list` to discover what your project uses, infer the convention from how existing issues are labeled, and ask the user to confirm before applying broad changes.
+
+**Discover the convention:**
+
+```bash
+# List all labels (skim for structured prefixes)
+gh label list
+
+# Filter to a specific prefix family
+gh label list --search "<prefix>/"
+```
+
+**Inferring policy:** conventions vary across projects. Common patterns:
+
+- **One label per axis.** Many projects allow only one `<prefix>/*` label per issue, with a dedicated multi-axis fallback (e.g. `<prefix>/cross-cutting`).
+- **Layered families.** Some projects use multiple prefixes together (`area/*` + `team/*` + `priority/*`).
+- **Separator style.** `<family>/<value>` and `<family>:<value>` both exist in the wild — respect whatever convention the project already uses.
+
+Before bulk-applying labels or relabeling issues, ask the user to confirm the convention — don't assume.
+
 ## Quick Start
 
 1. For new features, start with the Specification phase