/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, or /adlc:init on the plugin install, to vendor .adlc/ETHOS.md

Context

Run this block first, with your shell tool, and read its output before you continue. Each read prints a notice instead of failing when its file is absent.

# adlc-context
echo '--- Task template'
cat .adlc/templates/task-template.md 2>/dev/null || echo 'No task template found — run /init (/adlc:init on the plugin install) to vendor .adlc/templates'
echo '--- Active specs'
grep -rlx -e status:.draft -e status:.approved -e status:.in-progress --include requirement.md .adlc/specs 2>/dev/null || 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

The requirement is the argument: whatever follows /architect in the invocation (on Claude Code it can also arrive as an ARGUMENTS: line appended to this text), a REQ id such as REQ-023 or 23. With none, ask the user which requirement to architect.

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 (/adlc:init on the plugin install) 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 $ADLC_TOOLKIT_ROOT/agents/ with model selection (haiku for fast exploration) and read-only tool restrictions.

   If this harness can run subagents, dispatch these agents in parallel; if it cannot, or you are a subagent, run each checklist inline from .adlc/agents/<name>.md. Agent names are bare on the symlink install and adlc:-prefixed on the plugin install (adlc:<name>): before dispatching, check which form the Agent tool lists and use that one, and do not wait for an error, because a name it does not list can silently run a generic agent without the checklist; if neither form is listed, say which agent is missing and run its checklist inline. When .adlc/agents/ is absent, say that /init (/adlc:init on the plugin install) vendors it, then read $ADLC_TOOLKIT_ROOT/agents/<name>.md (the toolkit root is the parent of this skill's base directory) where your file tool can reach it; never improvise a checklist. An inline run of a review or audit agent is read-only: report findings, apply no fixes, and run no test runner, build tool, package manager or interpreter.

   • 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.

4. Escalated from the lite lane (REQ-652 BR-10)? If the spec carries lane_escalated, the branch already holds the lite implementation. Read it (git diff origin/<integrationBranch>...HEAD in the worktree) and treat it as the baseline to design around: tasks extend or correct that code rather than discard it, and the escalation's trigger names the line it crossed.

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.

# 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).
ADLC_TOOLKIT_ROOT="${CLAUDE_PLUGIN_ROOT}"; [ -n "$ADLC_TOOLKIT_ROOT" ] || [ ! -d "$HOME/.claude/skills/partials" ] || ADLC_TOOLKIT_ROOT="$HOME/.claude/skills"; [ -n "$ADLC_TOOLKIT_ROOT" ] || ADLC_TOOLKIT_ROOT=$(cat "$HOME/.claude/adlc/plugin-root" 2>/dev/null); export ADLC_TOOLKIT_ROOT="${ADLC_TOOLKIT_ROOT:-$HOME/.claude/skills}"
if [ -f .adlc/partials/forge.sh ]; then . .adlc/partials/forge.sh; else . "$ADLC_TOOLKIT_ROOT/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

• approved — the post-architecture REQ status written by step 1 below

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