scope-architect

Scope Architect (pure worker v1.0)

Slice by flow, never by directory — and write it as a contract a hook can enforce.

Groups a feature's tasks into independent, vertically-sliced scopes and writes each as a committed contract (shapeup/<slug>/scopes/<scope-id>.md) the rest of the harness enforces mechanically: the sandbox hook denies writes outside a substrate, t0-verify runs the fixtures, the evaluator asserts only against the affordance manifest. This skill is the sole writer of scope contracts — a distinct authority from the planner (task decomposition) and a distinct failure mode (directory-thinking, PA1) deserving its own the ship report's census table.

Input contract — the WorkOrder

Core process

1 SLICE    build an import/business-flow graph over the tasks' touched files (grep heuristic
           is fine; AST is an optimization). One scope = one call chain: the UI screen + the
           API route + the use case + the repository it drives. Scopes aligning 1:1 with a
           top-level directory (all-frontend, all-backend) FAIL — that is layer-thinking.
2 CLASSIFY topology_type: LAYER_CAKE (thin balanced UI+backend) | ICEBERG (complexity on one
           side) | CHOWDER (true strays with no shared flow — the one deliberate exception)
3 CONTRACT per scope, write scopes/<scope-id>.md — MARKDOWN (ADR-0001): frontmatter for
           scalars and [a, b] lists, a `## Affordances` table for affordance_manifest, and a
           short `## Why this slice` paragraph. A reviewer must be able to read the substrate
           in a PR; regeneration preserves prose under headings you do not own.
             scope_id, topology_type                         — the stable join key is the scope
             use_cases[]                                     — the UC ids this scope implements.
                                                               THE ONLY LINK YOU WRITE TO THE
                                                               WORK: never task ids. The contract
                                                               is committed and the board is not,
                                                               so a TASK-NNN here dangles on
                                                               every other clone (spec-lint
                                                               TIER-DIRECTION reds it). The
                                                               scope's tasks are re-derived from
                                                               the board's own use_case_refs
             covers[]                                        — optional REQ-ids from
                                                               requirements.md this scope answers
                                                               for; stable, never renumbered
             depends_on[]                                    — scope_ids this scope builds AFTER.
                                                               This is the build ORDER — declare
                                                               it whenever one scope consumes
                                                               another's output, or the two race
             allowed_file_substrate[]                        — exact globs; the sandbox hook's
                                                               write-whitelist; wrong here =
                                                               a legitimate ESCALATE later
             shared_substrate[]                              — files ≥2 scopes both touch;
                                                               every write there forces a full
                                                               seesaw run at the next gate
             affordance_manifest                             — from ux-behavior.md state
                                                               tables: every interactive
                                                               element as {test_id, role} +
                                                               required_states [idle, loading,
                                                               success, error, empty]
             e2e_verification_fixtures[]                     — the command(s)/spec file(s)
                                                               that drive this scope
                                                               end-to-end (T0 layer); too
                                                               speculative to fixture → mark
                                                               TBD and flag it, never invent
                                                               a fixture for unbuilt behavior
             hill_phase: "UPHILL_UNKNOWN"                    — ALWAYS; phase is derived from
                                                               T0/T1/seesaw facts later,
                                                               never authored
4 LINT     node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" verify spec --slug <slug>
           → PA1 (directory alignment), PA2 (>~15 files), DISJOINT (undeclared overlap),
           SCOPE-ANCHOR (empty/unresolvable use_cases), TIER-DIRECTION (a task id in a
           committed contract), SCOPE-DEPS (depends_on naming a scope that isn't here).
           Fix reds by re-slicing, not by silencing.
5 BOARD    regenerate scope-board.md — a VIEW of the contracts, nothing more:

             | scope_id | topology | use_cases | depends_on | files | lint |

           Every column restates a field the contract already declares, so the board can be thrown
           away and rebuilt. Do NOT add a `wave` column: waves are Kahn levels of `depends_on` and
           `probe resume` derives them at dispatch — a hand-written copy of a derived value drifts,
           which is exactly why `unlocks` stopped being authored. The BUILD ORDER lives in each
           contract's `depends_on`; the board only shows it.

           A `TASK-` id anywhere in a contract or the board — a column, a cell, or a sentence in
           the prose — is spec-lint TIER-DIRECTION red. The board is committed; ids are not.