Architect run: thirdshift finds and implements a Strong deepening opportunity unattended #27

Problem Statement

/improve-codebase-architecture finds real deepening opportunities, but every step after the scan needs a human: someone has to read the HTML report, pick a candidate, get grilled on it, then run /to-spec, /to-tickets and finally thirdshift <Spec URL>. So architecture upkeep only happens when someone sits down for a Day shift session. The factory can implement a Spec unattended, but it can't come up with one, even for a refactor so clearly worth doing that the human step adds nothing.

Solution

A new command, thirdshift architect, starts an Architect run from the Launch directory, with no Issue URL. Its Architecture review is a headless agent session in a worktree at the origin head of the Base branch. It scans the codebase for deepening opportunities, skips any already covered by an open issue, and takes the top recommendation:

• Strong: the review settles the design itself, records each decision and its reason in the plan, and publishes the plan labelled needs-triage. The plan is a Spec with Tickets, or a single standalone Ticket when one session is enough. thirdshift checks the plan, swaps needs-triage for ready-for-agent, and dispatches it exactly as thirdshift <Issue URL> would: a Spec run for a Spec, a Run for a Ticket.
• Worth exploring or Speculative: the review files it as one issue labelled needs-triage for the Day shift to flesh out, and nothing is implemented.
• Already filed: nothing new is filed.

--plan-only stops after the plan is published and marked ready. One command does one pass. The candidates that aren't chosen are dropped, so the next Architect run does a fresh analysis of the codebase as it is by then.

User Stories

1. As a thirdshift user, I want to run thirdshift architect from a clone with no Issue URL, so that the factory finds architecture work for itself.
2. As a thirdshift user, I want an Architect run to do the same preflight checks as a Run apart from those that need an issue (HEAD not detached, the Base branch exists on origin, my local copy is not ahead of it), so that the plan is based on exactly the code the work will branch from.
3. As a thirdshift user with launch pull on in my User config, I want an Architect run to bring the Launch directory's Base branch up to date first, as a Run does, so that the setting means the same everywhere.
4. As a thirdshift user, I want the Architecture review to run in its own worktree at the origin head of the Base branch, so that my checkout, its uncommitted changes and its untracked files are never touched or scanned.
5. As a thirdshift user, I want the Architecture review to be allowed throwaway edits in its worktree, such as a prototype, without any of them being committed or pushed, so that it can check an idea without changing the repository.
6. As a thirdshift user, I want the worktree removed when the Architecture review ends, whatever the outcome, so that nothing is left behind.
7. As a thirdshift user, I want to give thirdshift architect an optional focus, such as thirdshift architect "the Spec run", so that I can point the review at an area I know is painful.
8. As a thirdshift user, I want the review without a focus to weight the codebase's recent hot spots from the commit history, as the interactive skill does, so that deepening goes where it pays off.
9. As a thirdshift user, I want the review to use CONTEXT.md vocabulary for the domain and the codebase-design vocabulary for architecture, so that plans read like the rest of the project.
10. As a thirdshift user, I want the review to respect the ADRs and only propose reopening one when the friction is real, saying so in the plan, so that settled decisions aren't re-litigated overnight.
11. As a thirdshift user, I want the review to skip any candidate already covered by an open issue (a Spec, a Ticket or an idea issue), so that a waiting plan isn't duplicated.
12. As a thirdshift user, I want only a Strong top recommendation to be implemented, so that unattended refactors are ones the factory stands behind.
13. As a thirdshift user, I want the review to walk the design tree itself and write each decision with its reason into the plan, so that I and the Spec review can check its reasoning.
14. As a thirdshift user, I want the review to publish a Spec with Tickets when the change needs several sessions, and a single Ticket when one is enough, so that a small refactor isn't forced into a Spec.
15. As a thirdshift user, I want Tickets to carry their blocking edges as GitHub "blocked by" links, so that the Spec run works them in the right order.
16. As a thirdshift user, I want any glossary or ADR change the refactor needs to be part of a Ticket's work rather than written during the review, so that it lands through the pull request like the rest of the change.
17. As a thirdshift user, I want the plan published labelled needs-triage and marked ready-for-agent by thirdshift only after the review session ends cleanly and the plan passes its checks, so that a plan the review didn't finish publishing never looks ready.
18. As a thirdshift user, I want thirdshift to check that the plan issue was created during this Architect run, is open and isn't labelled with any other unready triage label, so that it never dispatches the wrong issue.
19. As a thirdshift user, I want thirdshift to dispatch the plan the same way thirdshift <Issue URL> would, a Spec run when it has sub-issues and a Run otherwise, so that an Architect run behaves like the commands I already know.
20. As a thirdshift user, I want thirdshift architect --plan-only to publish the plan, mark it ready, print its URL and stop, so that I can read or edit it before starting thirdshift <Issue URL> myself.
21. As a thirdshift user, I want a review with no Strong candidate to file its top recommendation as one issue labelled needs-triage, with its problem, solution, benefits and a Mermaid before/after diagram, so that the Day shift gets an idea to consider.
22. As a thirdshift user, I want a review whose top non-Strong idea is already filed to file nothing and say which issue covers it, so that nightly runs don't pile up duplicates.
23. As a thirdshift user, I want the candidates that weren't chosen to be dropped, so that the next Architect run starts from a fresh analysis instead of stale ideas.
24. As a thirdshift user, I want the plan and idea issues to use Markdown with Mermaid diagrams rather than an HTML report, so that the content lives where GitHub renders it.
25. As a thirdshift user, I want an Architect run that files an idea issue, files nothing, or finishes --plan-only to exit 0 and print the relevant issue URL, so that these count as success.
26. As a thirdshift user, I want an Architect run whose implementation is dispatched to end with that Spec run's or Run's outcome, exit status and printed PR URL, so that the result reads like any other Run.
27. As a thirdshift user, I want an Architect run whose Architecture review fails, is interrupted or reports no usable plan to end as a failure with a cause and the session log, so that I know what happened.
28. As a thirdshift user, I want a half-published plan to stay labelled needs-triage after a failed review, so that the Day shift can finish or close it and later Architect runs leave it alone.
29. As a thirdshift user, I want merge and no-merge, and the User config's merge default, to apply to the dispatched Spec run's Spec PR or Run's pull request, so that the flags mean the same as elsewhere.
30. As a thirdshift user, I want base-fix and no-base-fix, and the User config's base.fix, to pass through to the dispatched Spec run or Run, so that a red Base branch is handled as it is everywhere else (Inherited failures: fail fast on a red Base branch, or fix it with a Base fix #221).
31. As a thirdshift user, I want parallel <n> to pass through to a dispatched Spec run, so that I can bound the work as I do today.
32. As a thirdshift user who asked for a Run notification, I want one notification per Architect run covering the review's outcome and the dispatched run's outcome, with no separate notification from the dispatched run, so that I get one message per thing I asked for.
33. As a thirdshift user, I want progress lines for the review starting, the plan or idea it published, the label swap and the dispatch, so that a long run is never silent.
34. As a thirdshift user, I want thirdshift help and the README to document architect, its focus argument and --plan-only, and to say to run only one Architect run per repository at a time, so that I know how to use it and its limits.
35. As a thirdshift user, I want the Architecture review's Session prompt shown on the prompts page with the other Session prompts, so that I can read what the agent is told.

Implementation Decisions

• Command line: a new architect command, valid only as the first argument, takes an optional free-text focus and the flags --plan-only, merge/no-merge, email/no-email, parallel <n> and, once Inherited failures: fail fast on a red Base branch, or fix it with a Base fix #221 has landed, base-fix/no-base-fix. Contradictory pairs are rejected as they are for a Run. The parser gains a new Command variant; Run parsing is unchanged.
• No Origin match: there is no Issue URL, so the repository is the Launch directory's origin. The other preflight checks and the opt-in launch pull are reused as they are.
• Worktree: detached at the origin head of the Base branch, with no Issue branch. Nothing in it is committed or pushed, and it is removed when the review ends.
• Factory skills: headless copies of improve-codebase-architecture, to-spec, to-tickets and codebase-design are added to skills/, kept close to the originals so they can be re-synced. They drop every human step: the report is Markdown in the issue, not an HTML file opened with xdg-open; the review picks the top recommendation instead of asking; the grilling loop becomes the agent settling the design tree itself and recording each decision; to-spec doesn't check seams with a user. They write nothing to the repository; CONTEXT.md and ADR updates become Ticket work. References between them use the plugin namespace (ADR-0001).
• Labels: the review publishes the plan's top issue, the Spec or the single Ticket, labelled needs-triage. Tickets under a Spec get ready-for-agent from to-tickets as usual. thirdshift, not the agent, swaps the plan's needs-triage for ready-for-agent, as one deterministic step after the session ends cleanly and the checks pass, including under --plan-only.
• Session prompt: a new prompt in the prompt module names the Factory skills, the Base branch, the focus if any, and how to report. It ends by asking for one fixed-format final line: the plan's URL, the idea issue's URL, or the URL of the open issue that already covers the top idea. thirdshift reads only that line. A missing or malformed line is a failed review.
• Checks before dispatch: the plan issue was created after the Architect run started, is open, and has no unready triage label other than needs-triage. Any failure ends the Architect run as a failure and leaves the issue as it is.
• Dispatch: reuses the existing entry point's choice: a Spec run when the plan has sub-issues, otherwise a Run. Merge, email, parallel and base-fix are applied to it as if they were given to thirdshift <plan URL>. Its Run notification is suppressed, as for a Ticket's Run, and the Architect run sends the one notification.
• Outcomes: success (exit 0) for a dispatched run that succeeds, a --plan-only plan, an idea issue filed, or an idea already filed, printing the PR URL or the issue URL on stdout. Failure for a failed or interrupted review, a plan that fails its checks, or a failed dispatched run.
• Run notification: extended so its subject and body can describe an Architect run: the review's outcome and, when there was one, the dispatched run's outcome (for a Spec run, each Ticket's outcome as today).
• Concurrency: no lock. Two Architect runs on one repository at once may pick the same candidate; this is documented rather than prevented.
• Glossary: Architect run and Architecture review are added to CONTEXT.md, and Run now says an Architect run can start one.

Testing Decisions

• Tests check external behavior only: what the binary prints, its exit status, the gh calls it makes and the prompts it gives claude. They don't test internals.
• End-to-end seam: a new tests/architect_run.rs drives the thirdshift binary through the existing tests/support::Scenario with the fake claude and gh. The fake agent is scripted to create the plan issue, a Spec with Tickets or a single Ticket, and report its URL, or to file an idea issue, report one already filed, report nothing, or die partway. Cases include: dispatch to a Spec run; dispatch to a Run; --plan-only stopping after the label swap; the idea-issue and already-filed paths exiting 0 without dispatch; a failed review leaving needs-triage and exiting non-zero; a plan issue that's closed or not new being refused; merge, parallel, email and base-fix passing through; one Run notification. The fake gh gains what it needs, such as issue creation, listing and label edits. Prior art: tests/spec_run.rs, tests/merge_run.rs, tests/run_notification.rs, tests/preflight.rs.
• Prompts page: the Architecture review's Session prompt is pinned by the prompts page snapshot (UPDATE_PROMPTS=1 cargo test prompts_page), like every other Session prompt.
• Argument parser: unit tests for architect with and without a focus, --plan-only, contradictory flags and stray arguments, in the style of the existing parser tests.
• The Factory skills themselves aren't tested beyond what the end-to-end tests see through the prompt.

Out of Scope

• An opt-in loop that keeps running passes until no Strong candidate is left.
• Keeping the candidates that weren't chosen, in the plan or as issues.
• Any lock or other guard against two Architect runs at once on one repository.
• Refusing a Run or Spec run on an issue whose own triage label says it isn't agent work, in general: Refuse to start a Run or Spec run on an issue whose own triage label says it isn't agent work #228.
• The Base fix itself, which is Inherited failures: fail fast on a red Base branch, or fix it with a Base fix #221. This Spec only passes its flags and setting through.
• Changing the interactive /improve-codebase-architecture, /to-spec and /to-tickets skills in .claude/skills/.

Further Notes

• The base-fix pass-through depends on Inherited failures: fail fast on a red Base branch, or fix it with a Base fix #221 merging first; the Ticket for it should be blocked by Inherited failures: fail fast on a red Base branch, or fix it with a Base fix #221, or come after it.
• Decided in a grilling session on 2026-10-01; the glossary changes are in CONTEXT.md on the improve-codebase-architecture branch.