---
name: architect
description: Design architecture and break requirement into tasks
argument-hint: REQ-xxx ID or requirement description
---

# /architect — Architecture & Task Breakdown

You are designing architecture and breaking a requirement into implementable tasks.

## Ethos

!`test -s .adlc/ETHOS.md && cat .adlc/ETHOS.md || echo No ethos found — run /init to vendor .adlc/ETHOS.md`

## Context

- Task template: !`cat .adlc/templates/task-template.md || echo No task template found — run /init to vendor .adlc/templates`
- Active specs: !`grep -rl -e status:.draft -e status:.approved -e status:.in-progress --include requirement.md .adlc/specs || echo No active specs`

**Context files loaded on demand**: `.adlc/context/architecture.md` and `.adlc/context/conventions.md` are loaded by Step 1 below — **skip the Read if they are already in the current conversation** (e.g., when invoked from `/proceed`, which preloads them at Phase 0).

## Input

Requirement: $ARGUMENTS

## Prerequisites

Before proceeding, verify that `.adlc/context/architecture.md` and `.adlc/context/conventions.md` exist. If either is missing, stop and tell the user: "The `.adlc/` structure hasn't been fully initialized. Run `/init` first to set up the project context."

## Instructions

### Step 1: Locate and Read the Requirement
1. If given a REQ ID, read `.adlc/specs/REQ-xxx-*/requirement.md`
2. If given a description, search `.adlc/specs/` for the matching requirement
3. Verify the requirement status is `draft` or `approved` (not already `complete`)
4. **Context files**: if `.adlc/context/architecture.md` and `.adlc/context/conventions.md` are NOT already in your conversation context (e.g., this skill is being run standalone, not from `/proceed`), Read them now. Otherwise skip — they're already loaded.
5. Check `.adlc/knowledge/assumptions/` for prior decisions that may affect design
6. **Lessons — grep first, then read only matches**: use the Grep tool on `.adlc/knowledge/lessons/` with patterns like `component:.*<affected-area>` or `domain:.*<domain>` to identify matching files. Then Read ONLY those matched files. Do NOT read all lessons. Note applicable lessons in your architecture rationale so past mistakes aren't repeated and proven patterns are reused.

### Step 2: Explore the Codebase
1. Launch 3 formal exploration agents in parallel using the Agent tool. Each agent is defined in `~/.claude/agents/` with model selection (haiku for fast exploration) and read-only tool restrictions.

   - **feature-tracer** agent — provide the requirement description and key terms to search for similar existing implementations
   - **architecture-mapper** agent — provide the requirement and current architecture.md to map all files and layers that will be affected
   - **integration-explorer** agent — provide the affected areas to identify extension points, tests, and integration surfaces

2. Read the key files identified by agents
3. **Retain the `architecture-mapper` affected-file list** (the first column of its "Files to
   Modify" + "Files to Create" tables, bare paths) as `$MAPPER_PATHS` — one path per line. This
   is NOT the footprint source anymore (tasks are, per REQ-484); it is kept only as the BR-4
   graceful-degradation fallback consumed by Step 5 when a task carries no file list.

> **Note (REQ-484):** footprint publishing has moved to **Step 5**, which runs AFTER task
> creation. Per-repo attribution is derived from the task files' `repo:` frontmatter, so the
> publish step MUST run once those files exist — not here during codebase exploration. The
> mapper output is retained (item 3) only as the BR-4 fallback.

### Step 3: Design Architecture (if needed)
1. If the requirement involves new architectural decisions, create `.adlc/specs/REQ-xxx-*/architecture.md`
2. Document:
   - **Approach**: High-level design and rationale
   - **Data model changes**: New Firestore collections/fields, GCS metadata
   - **API changes**: New or modified endpoints
   - **Service layer**: New or modified services
   - **Key decisions**: ADRs with rationale (follow the style in `.adlc/context/architecture.md`)
3. Propose any additions to `.adlc/context/architecture.md` with rationale

### Step 4: Break Into Tasks
1. Create `.adlc/specs/REQ-xxx-*/tasks/` directory
2. Determine the next TASK ID by checking existing tasks across ALL specs (not just this one)
3. **Detect repository mode**: check whether `.adlc/config.yml` exists in the primary repo and declares a `repos:` block with more than one entry.
   - **Single-repo mode** (no config or single entry): set `repo:` on each task to the primary repo id (or omit — `/proceed` will backfill). Files listed under "Files to Create/Modify" all live in the primary repo.
   - **Cross-repo mode** (config has siblings): **every task MUST declare a `repo:` field** naming one of the ids under `repos:`. Group files by repo — a single task should not modify files in multiple repos. If a piece of work spans repos (e.g., an API contract change requires matching backend and frontend edits), split it into at least two tasks with an explicit dependency between them.
4. Create `TASK-xxx-description.md` for each task using the template from `.adlc/templates/task-template.md`
5. Each task must specify:
   - **Frontmatter**: id, title, status (`draft`), parent REQ, created/updated dates, dependencies, `repo:` (required in cross-repo mode)
   - **Description**: What this task accomplishes
   - **Files to Create/Modify**: Specific file paths with descriptions of changes — all paths must live in the task's target repo
   - **Acceptance Criteria**: Concrete, testable criteria
   - **Technical Notes**: Implementation details, patterns to follow, edge cases. In cross-repo mode, call out any cross-repo contracts this task establishes or consumes.
   - **Dependencies**: Other tasks that must complete first — dependencies may cross repos (a frontend task can depend on a backend task)
6. Tasks must form a valid dependency graph (no cycles), even when spanning repos
7. Order tasks so foundational work comes first (data layer → service → routes → UI). In cross-repo mode, backend/API tasks typically precede their frontend consumers.

### Step 4.5: Emit Verification Obligations (REQ-595)

**Runs AFTER task creation (Step 4) and BEFORE the Step 5 footprint publish**, which
reads the same task files. Numbered 4.5 rather than renumbering Steps 5–7, because
`REQ-483` / `REQ-484` architecture docs reference `/architect` Step 5 by number.

Write a `## Verification` block into each task file created in Step 4, naming every
BR and AC that task discharges and the concrete artifact that proves each one. This
is the pre-commitment that makes an omitted rule visible at architecture time rather
than three phases later as a review finding — or never (LESSON-330: the Phase-5
panel's real catch is a numbered rule implemented as zero).

The block shape is defined in `.adlc/templates/task-template.md` (loaded in
`## Context` above) — a four-column table, `rule | kind | artifact | benign_path`.
Emit the columns in that order; `/validate`'s coverage gate reads positionally.

**1. Enumerate the rules.** Read the parent REQ's `## Business Rules` and
`## Acceptance Criteria`. `BR-<n>` uses the number as written. **`AC-<n>` is the
1-based ordinal** within the `## Acceptance Criteria` list — the requirement
template does not print AC numbers, so ordinal position is the addressing.

If the REQ has **zero numbered BRs**, emit a one-line notice and skip obligation
emission for BRs. Do not invent rules to map. An unnumbered legacy prose spec is
not gate-able and is not made gate-able by fabricating ids.

**2. Assign each rule to the task that discharges it.** A rule may map to more than
one task; a task may discharge many rules. Every numbered BR and AC should land
somewhere across the task set — that is exactly what `/validate` reports on.

**3. Resolve `kind` — surface first, stack for the artifact shape.**

- **All of the task's `## Files to Create/Modify` paths end in `.md`** →
  `kind: structural-check`. The artifact names the structural check(s) that
  actually run over that surface (in this toolkit, `tools/lint-skills` checks).
  Markdown skills have no test runner; a structural check is their real
  verification mechanism, not a lesser substitute for one. **No config read is
  attempted on this branch** — a repo without `.adlc/config.yml` resolves here
  silently, with no error and no test-file path emitted.
- **Any non-`.md` path** → `kind: test-case`. Resolve the *artifact shape* — which
  runner, which path and case-name convention — from that task's repo
  `.adlc/config.yml` `stack:` when the file exists and declares one; otherwise from
  the test layout already present in that repo.

`kind` is the closed two-value enum `test-case | structural-check`. `dogfood` is
deliberately excluded: it cannot report an executed-work count, which the
vacuous-run gate requires.

**Never hardcode a framework name.** Read the declared `stack:` values and use them
as written. Any runner name written as a literal into this skill is a name that is
wrong for the next project — the whole point of reading it from config is that the
skill does not know, and must not guess, which runner a consumer uses.

**4. Cross-repo (BR-9).** Resolution is per task, and a task's repo is its `repo:`
frontmatter — **absent means the primary repo**, matching the attribution Step 5
already applies to footprint paths. Each repo's `stack:` and test layout are read
from *that* repo, so obligations group per repo with per-repo artifact paths. Never
resolve a sibling's artifact path against the primary's layout.

**5. Detector-shaped rules need a benign path (BR-4).** Any rule describing
detection, refusal, or a halt must carry at least one obligation with
`benign_path: yes` — a case asserting the detector does **not** fire on the
legitimate actor. A detector validated only against adversarial inputs ships broken
and passes its own suite (LESSON-440). Match the rule text on case-insensitive
stems (`detect`, `refus`, `halt`, `reject`, `block`, `flag`), never `\b` word
anchors — BSD `grep -E` on macOS does not honor them and the check would silently
never fire (LESSON-013).

**6. Validate every row before it is written — regardless of origin.** This applies
to rows you authored and to any drafted by a delegate; the contract is
origin-agnostic on purpose, so it cannot be bypassed by changing who wrote the row:

- `rule` matches `^(BR|AC)-[0-9]+$` **and** that ordinal exists in the parent REQ.
  A row citing `BR-99` on a REQ with 11 BRs is **dropped**.
- `artifact` — reject any value containing `..`, then charset-validate. Reuse the
  same reject-then-validate pattern Step 5 applies to footprint paths rather than
  inventing a second one (LESSON-008: a cited path is untrusted input, and a
  traversal that merely fails to match must still be refused, not silently allowed).
- `kind` is one of the two enum values.

**Report every dropped row** with the reason. A silently swallowed drop looks
identical to a rule that was never mapped, which is the failure this step exists to
make visible.

**7. Write the block** into each task file, above `## Technical Notes`. A task with
genuinely nothing to declare may omit the section — it stays valid, and `/validate`
reports the gap as an advisory finding rather than blocking. Do not emit an empty
table.

### Step 5: Publish the File Footprint to the Draft PR(s) (REQ-483 BR-4 / REQ-484)

**Runs AFTER task creation** so per-repo `repo:` attribution from the task files is available
(REQ-484 ADR-2 / OQ-1). Under `/proceed`, a draft PR already exists per touched repo (Step 0),
each recorded in `pipeline-state.json` `repos[<id>].prNumber`. Publish **each repo's own**
footprint into **that repo's** draft PR — one fenced `adlc-footprint` block per PR, each line
repo-qualified `<repo-id>:<path-or-glob>` (the schema `/manifest` parses; see
`.adlc/specs/REQ-483-*/architecture.md` and `.adlc/specs/REQ-484-*/architecture.md`). Idempotent
(replace any prior block). Skip with a one-line note if there is no draft PR (standalone
`/architect`, no `/proceed`).

**Attribution (BR-1, BR-6, ADR-1).** A repo's footprint is the union of
`## Files to Create/Modify` paths across tasks whose `repo:` frontmatter equals that repo id. A
task with **no** `repo:` field attributes to the **primary** repo (single-repo projects omit
`repo:`), so single-repo REQs derive from tasks via this same path — NOT via the BR-4
mapper-fallback. A path is attributed to a repo solely by its task's `repo:` tag — never
broadcast to all PRs, never inferred from the path string.

**Iterate every PR (BR-2, BR-3).** Loop over every touched repo's `prNumber` from
`pipeline-state.json` — do NOT use `head -1`. Each PR receives only its own repo's lines. In
single-repo mode the loop degenerates to one repo / one PR / one block, with no separate code
path and no "coarse" flag.

**Sanitize on write (BR-5, LESSON-008).** Every emitted line MUST pass the same validation the
read side applies — reject any line containing `..`, then charset-validate
`^[A-Za-z0-9_.-]*:?[A-Za-z0-9_./*-]+$` — BEFORE it is written to any PR body.

**Graceful degradation, never error (BR-4).** A task with no file list, or a touched repo with
no tasks attributing files, falls back to the architecture-mapper paths attributed to the
**primary** repo, emitting a one-line `source: mapper-fallback` notice. A repo with genuinely
zero attributable files is skipped with a note — never publish an empty block silently.

```sh
# Forge adapter (REQ-520 BR-1): footprint publish reads/writes the PR body via
# pr_view/pr_edit, never direct gh. Sourced in THIS fence (shell state does not
# cross fences). GitHub backend forwards args verbatim, so the body read/write is
# byte-identical (BR-3).
if [ -f .adlc/partials/forge.sh ]; then . .adlc/partials/forge.sh; else . ~/.claude/skills/partials/forge.sh; fi

# Scope to THIS REQ's spec dir. $REQ is the REQ id (e.g. REQ-484) the skill is operating on.
# When $REQ is set, ONLY its own spec dir is consulted: a REQ with no pipeline-state.json is a
# standalone /architect run and skips here. It must NOT fall through to the any-REQ search below —
# that resolved a standalone REQ-611 run to REQ-544's state and would have published REQ-611's
# footprint into REQ-544's draft PR. The any-REQ fallback (the lone pipeline-state.json) is
# reached only when $REQ is unset.
# find, not ls globs: zsh errors on unmatched globs ("no matches found") instead of
# passing the pattern through, so a glob here breaks sh/bash/zsh parity.
state=""
if [ -n "$REQ" ]; then
  state=$(find .adlc/specs -type f -path "*/${REQ}-*/pipeline-state.json" 2>/dev/null | sort | head -1)
  [ -n "$state" ] || { echo "architect: no pipeline-state.json for $REQ — standalone run, skipping footprint publish"; exit 0; }
else
  state=$(find .adlc/specs -type f -path "*/REQ-*/pipeline-state.json" 2>/dev/null | sort | head -1)
  [ -n "$state" ] || { echo "architect: no pipeline-state.json — standalone run, skipping footprint publish"; exit 0; }
fi
specdir=$(dirname "$state")   # THIS REQ's spec dir — task glob is scoped here, not all specs.
tick=$(printf '\140\140\140')
tab=$(printf '\t')
# Primary repo id (tasks with no repo: attribute here). The parse targets the pretty-printed
# pipeline-state.json that /proceed writes (one JSON field per line; each repo object spans
# multiple lines). It also tolerates one-repo-object-per-line layouts. A repo-id opening
# (`"<id>": {`) sets the current repo; "primary"/"prNumber" bind to it (matched on the same line
# too, so a repo whose object opens and closes on its own line still resolves). POSIX awk only —
# no 3-arg match(), no perl dependency.
primary=$(awk '
  /"repos"[[:space:]]*:/ { inrepos=1 }
  inrepos && /"[A-Za-z0-9_.-]+"[[:space:]]*:[[:space:]]*\{/ {
    # take the key immediately before `: {` (the LAST quoted token before the brace), so a
    # compact line like `{ "req":"R", "repos": { "solo": {` still yields `solo`, not `req`.
    s=$(0); sub(/[[:space:]]*:[[:space:]]*\{.*/,"",s); sub(/"$/,"",s); sub(/.*"/,"",s)
    if (s!="repos" && s!="") cur=s
  }
  inrepos && cur!="" && /"primary"[[:space:]]*:[[:space:]]*true/ { print cur; exit }
' "$state" 2>/dev/null)
# Touched repo ids that have a prNumber, one TSV line per repo: "<repo-id><TAB><prNumber>".
# Each prNumber stays bound to its owning repo id (NOT head -1). Same dual-format awk.
repos_prs=$(awk -v TAB="$tab" '
  /"repos"[[:space:]]*:/ { inrepos=1 }
  inrepos && /"[A-Za-z0-9_.-]+"[[:space:]]*:[[:space:]]*\{/ {
    # take the key immediately before `: {` (the LAST quoted token before the brace), so a
    # compact line like `{ "req":"R", "repos": { "solo": {` still yields `solo`, not `req`.
    s=$(0); sub(/[[:space:]]*:[[:space:]]*\{.*/,"",s); sub(/"$/,"",s); sub(/.*"/,"",s)
    if (s!="repos" && s!="") cur=s
  }
  inrepos && cur!="" && /"prNumber"[[:space:]]*:[[:space:]]*[0-9]+/ {
    n=$(0); sub(/.*"prNumber"[[:space:]]*:[[:space:]]*/,"",n); sub(/[^0-9].*/,"",n);
    if (n!="") { print cur TAB n; cur="" }
  }
' "$state" 2>/dev/null)
[ -n "$repos_prs" ] || { echo "architect: no draft PR (no prNumber in state) — skipping footprint publish"; exit 0; }

printf '%s\n' "$repos_prs" | while IFS="$tab" read -r repo prnum; do
  [ -n "$repo" ] && [ -n "$prnum" ] || continue
  # Collect this repo's task-attributed file paths (first backtick token of each bullet under
  # "## Files to Create/Modify"); a task with no repo: attributes to $primary.
  lines=""
  # while-read over find, not a for-glob: zsh errors on unmatched globs ("no matches
  # found") instead of passing the pattern through. Heredoc (not a pipe) so $lines
  # accumulated in the loop survives it.
  while IFS= read -r tf; do
    [ -f "$tf" ] || continue
    trepo=$(sed -nE 's/^repo:[[:space:]]*([A-Za-z0-9_.-]+).*/\1/p' "$tf" | head -1)
    [ -n "$trepo" ] || trepo="$primary"
    [ "$trepo" = "$repo" ] || continue
    paths=$(awk '/^## Files to Create\/Modify/{f=1;next} /^## /{f=0} f && /^- /{print}' "$tf" \
      | sed -nE 's/^- *`([^`]+)`.*/\1/p')
    [ -n "$paths" ] && lines=$(printf '%s\n%s\n' "$lines" "$paths")
  done <<TASKS_EOF
$(find "$specdir"/tasks -name 'TASK-*.md' 2>/dev/null | sort)
TASKS_EOF
  # Repo-qualify, sanitize (reject .. then charset-validate), dedupe.
  safe=$(printf '%s\n' "$lines" | sed '/^$/d' \
    | while IFS= read -r p; do printf '%s:%s\n' "$repo" "$p"; done \
    | grep -vE '\.\.' | grep -E '^[A-Za-z0-9_.-]*:?[A-Za-z0-9_./*-]+$' | sort -u)
  if [ -z "$safe" ]; then
    # BR-4 fallback: architecture-mapper paths attributed to primary (only for the primary PR).
    if [ "$repo" = "$primary" ] && [ -n "$MAPPER_PATHS" ]; then
      safe=$(printf '%s\n' "$MAPPER_PATHS" | sed '/^$/d' \
        | while IFS= read -r p; do printf '%s:%s\n' "$primary" "$p"; done \
        | grep -vE '\.\.' | grep -E '^[A-Za-z0-9_.-]*:?[A-Za-z0-9_./*-]+$' | sort -u)
      [ -n "$safe" ] && echo "architect: repo=$repo source: mapper-fallback (no task file list)"
    fi
  fi
  if [ -z "$safe" ]; then
    echo "architect: repo=$repo has zero attributable files — skipping (no empty block)"
    continue
  fi
  tmp=$(mktemp "${TMPDIR:-/tmp}/footprint.XXXXXX") || continue
  if base=$(adlc_forge_pr_view "$prnum" --json body -q .body 2>/dev/null); then
    base=$(printf '%s\n' "$base" | sed "/^${tick}adlc-footprint/,/^${tick}/d")
    { printf '%s\n\n%sadlc-footprint\n' "$base" "$tick"; printf '%s\n' "$safe"; printf '%s\n' "$tick"; } > "$tmp"
    adlc_forge_pr_edit "$prnum" --body-file "$tmp" >/dev/null 2>&1 && echo "architect: published footprint for repo=$repo to PR #$prnum"
  fi
  rm -f "$tmp"
done
```

`$MAPPER_PATHS` holds the architecture-mapper affected-file list (bare paths, no repo column)
captured during Step 2 — used only for the BR-4 primary-repo fallback when a task carries no file
list. Other sessions read each block via `adlc_forge_pr_view --json body` (consumed by `/manifest`'s
ordering verdict). The block is split-free (newline iteration, no unquoted word-splitting) so it
behaves identically under `sh` and `zsh` (LESSON-329), and uses `mktemp` + cleanup per PR.

### Step 6: Update Requirement Status

<!-- retrieval-status: lifecycle-write -->
- `approved` — the post-architecture REQ status written by step 1 below
<!-- /retrieval-status -->

Declared for `tools/lint-skills`'s `retrieval-status-parity` check: any status
this skill writes must remain retrievable by `/spec` Step 1.6 (BUG-194).

1. Update the requirement's frontmatter status from `draft` to `approved`
2. Update the `updated` date

### Step 7: Present for Review
1. Display the architecture decisions (if any)
2. Display the task breakdown as a dependency graph
3. Summarize the implementation plan
4. Remind the user to run `/validate` before starting implementation

## Quality Checklist
- [ ] Architecture follows existing patterns (layered: routes → services → repositories)
- [ ] Tasks are small enough to implement in a single session
- [ ] Task dependencies form a valid DAG (no cycles), including cross-repo edges
- [ ] Every file to be modified is listed in at least one task
- [ ] Tests are included in task acceptance criteria
- [ ] Every numbered BR and AC in the REQ is cited by at least one task's
      `## Verification` block (Step 4.5) — an unmapped rule is the omitted-requirement
      class LESSON-330 names, and it is far cheaper to catch here than at review
- [ ] Every rule describing detection, refusal, or a halt carries at least one
      `benign_path: yes` obligation
- [ ] Every obligation's `kind` matches its task's surface, and no framework name is
      hardcoded — the artifact shape comes from the repo's declared `stack:` or its
      observed test layout
- [ ] No task has more than 3 dependencies
- [ ] In cross-repo mode: every task has a `repo:` field naming a valid repo id from `.adlc/config.yml`, and all files in that task live in that repo