Architect

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