setup

name	setup
description	Configure a repo for Code Factory — issue tracker, triage labels, domain docs, the company GitHub Project board, and the codebase-memory index. Run once per repo before any other Code Factory skill.
disable-model-invocation	true

Code Factory Setup

Stand up everything the other Code Factory skills assume exists:

• Issue tracker — where issues live (GitHub by default)
• Triage labels — the five canonical triage roles
• Domain docs — CONTEXT.md, ADRs, and the consumer rules for reading them
• Delivery board — the company's GitHub Project this repo feeds (created if absent)
• Codebase memory — the repo indexed into the bundled codebase-memory MCP

This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write. The user answers each section once; every later skill reads the answers from docs/agents/ instead of re-asking.

Process

1. Explore

Read the repo's actual starting state; present findings, not assumptions:

• git remote -v — is this a GitHub repo? Which org owns it? (The org determines the board.)
• CLAUDE.md / AGENTS.md at the root — does either exist? Is there already a ## Code Factory section?
• CONTEXT.md, CONTEXT-MAP.md, docs/adr/, src/*/docs/adr/
• docs/agents/ — has setup already run here? If so, this run is an update: load the existing answers as the new defaults.
• Monorepo signals — pnpm-workspace.yaml, a workspaces field, populated packages/* with own src/. Absence means single-context, which is almost every repo.
• Existing boards — gh project list --owner <org> (needs the project scope; on a scope error, run gh auth refresh -s project and retry). Note any Project that looks like the company board.
• Codebase-memory state — index_status for this repo via the codebase-memory MCP. Not indexed is the normal starting state.

Exploration is done when you can state, for each of the five sections below, either the settled answer or the question to ask.

2. Present findings and ask

Summarise what's present and what's missing, then take the sections in order — one section, one answer, then the next. Lead each section with the recommended answer so the user can accept it in a word. Skip a section entirely when exploration already settled it.

Section A — Issue tracker. Where issues live. If a git remote points at GitHub, propose GitHub; GitLab remote, propose GitLab; otherwise offer local markdown or a freeform description of another tracker (Jira, Linear, …). Record the choice in docs/agents/issue-tracker.md from the matching seed template:

• issue-tracker-github.md
• issue-tracker-gitlab.md
• issue-tracker-local.md

Section B — Triage labels. Ask exactly one question:

Do you want to keep the default triage labels? (recommended: yes)

Defaults are the five canonical roles, label string = role name: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. On yes, write triage-labels.md as-is. Only if the tracker already uses other names, collect the overrides so triage applies existing labels instead of creating duplicates.

Section C — Domain docs. Default to single-context — one CONTEXT.md + docs/adr/ at the root — and write it without asking; it fits almost every repo. Offer multi-context (CONTEXT-MAP.md + per-context files) only when exploration found monorepo signals. Seed: domain.md.

Section D — Delivery board. One GitHub Project per company/org, with only the actively-pushed repos linked — the board exists for team visibility, and a board per repo fragments it. So:

• Exploration found a Project that is plausibly the company board → propose linking this repo to it.
• No board found → propose creating one, and ask which other repos of this org should be linked (the user knows which few are actively pushed).
• No GitHub remote / user declines → skip the board; record "no board" so the PM skills know not to look for one.

Board mechanics (field setup, linking, epics) live in board.md — read it before creating or linking. Record org, project number, linked repos, and status/iteration field names in docs/agents/board.md.

A fresh board must not end the run empty — an empty board tells the team nothing and looks broken. Offer to import each linked repo's open issues as the starting Backlog (mechanics in board.md), then sweep: GitHub auto-adds sub-issues of added items with no status, so give every status-less item its honest one — closed → Done, open → Backlog.

Section E — Codebase memory. First check the server is available: the MCP tools respond, or command -v codebase-memory-mcp finds the binary. Missing → tell the user the plugin expects codebase-memory-mcp on PATH (install per the Code Factory README), record "not indexed — server not installed", and continue; setup must not dead-end on an optional dependency. Available → propose indexing the repo (index_repository). This is the default — every role queries the graph (Architect explores it, Engineer checks impact, Reviewer computes blast radius). Skip only if the user declines; then record "not indexed" in docs/agents/codebase-memory.md so agents fall back to grep.

3. Confirm and edit

Show the user a draft of the ## Code Factory block (step 4) and the contents of every docs/agents/*.md file about to be written. Let them edit before anything is written.

4. Write

Edit CLAUDE.md if it exists, else AGENTS.md; if neither exists, ask which to create. Never create the second file when one already exists. If a ## Code Factory block already exists, update it in place — never append a duplicate.

## Code Factory

### Issue tracker
[one line]. See `docs/agents/issue-tracker.md`.

### Triage labels
[one line]. See `docs/agents/triage-labels.md`.

### Domain docs
[one line — "single-context" or "multi-context"]. See `docs/agents/domain.md`.

### Delivery board
[one line — org + project, or "no board"]. See `docs/agents/board.md`.

### Codebase memory
[one line — "indexed" or "not indexed"]. See `docs/agents/codebase-memory.md`.

Then write the docs/agents/*.md files from the seed templates, create/link the board per board.md, and run the codebase-memory index.

On a shared/org repo, the writes go on a fresh branch off the default branch (code-factory/setup) and up as a PR — never onto whatever feature branch happens to be checked out, and never straight to a protected main. Restore the previously checked-out branch afterwards. A personal scratch repo can take the commit directly.

Writing is done when: every section that ran has its docs/agents/ file on disk, the ## Code Factory block references each one, the board exists with this repo linked (or "no board" is recorded), and index_status reports the repo indexed (or "not indexed" is recorded).

5. Done

Report what was configured, in one screen: tracker, labels, domain layout, board URL, index status. Mention that docs/agents/*.md can be edited directly later — re-running setup is only needed to switch trackers or boards.