[JacobStephens2]

Summary

Four headless Factory skills for the Architecture review, copied from the interactive originals and embedded in the binary as thirdshift: plugin skills.

 skills/
 ├── code-review/
+├── codebase-design/                 # vocabulary; design-it-twice decides instead of presenting
+│   ├── SKILL.md
+│   ├── DEEPENING.md
+│   └── DESIGN-IT-TWICE.md
 ├── implement/
+├── improve-codebase-architecture/   # the Architecture review itself
+│   ├── SKILL.md
+│   └── REPORT.md                    # was HTML-REPORT.md: Markdown + Mermaid, in the issue
 ├── pr/
 ├── resolving-merge-conflicts/
 ├── tdd/
+├── to-spec/                         # publishes the Spec, `needs-triage`
+└── to-tickets/                      # publishes Tickets: sub-issues + "blocked by" links

What /thirdshift:improve-codebase-architecture tells the agent to do:

explore (focus from the Session prompt, else commit-history hot spots)
read the open issues
weigh candidates in the session; no report file, no browser
top recommendation =
  highest-ranked Strong candidate no open issue covers
    settle the design tree itself, each decision with its reason
    one session enough?  -> /thirdshift:to-tickets: one Ticket, needs-triage
    otherwise            -> /thirdshift:to-spec: Spec, needs-triage
                            /thirdshift:to-tickets: sub-issues, ready-for-agent, blocked-by links
  else highest-ranked candidate of all
    an open issue covers it -> file nothing
    otherwise               -> one needs-triage idea issue (report card + Mermaid before/after)
every other candidate is dropped
end with the final line the Session prompt asks for

Where each human step went:

Interactive	Headless
HTML report, opened with xdg-open	Markdown card with Mermaid before/after, in the issue
"Which of these would you like to explore?"	Takes the top recommendation; plans it only when Strong
Grilling loop	The agent walks the design tree and records each decision and its reason in the plan
to-spec checks seams with the user	Decides the seams and records them under Testing Decisions
to-tickets quizzes the user	Checks the breakdown itself
Edits CONTEXT.md / offers ADRs inline	Recorded as a Ticket's work; nothing is committed, pushed or branched
Local .scratch/ ticket files	Removed: GitHub issues only, with native links (what TICKETS_QUERY reads)

Strong is defined in the skill, since it gates unattended work: real friction in the code, passes the deletion test, the whole design can be settled without a human, and no ADR stands in the way (or the friction warrants reopening it).

The final-line format is not in the skills. The skill says to end with the line the Session prompt asks for, "defined there and nowhere else", so the format lives once, in the prompt module, next to the code that reads it (#230).

Also: skill_unit in the prompts page generator became skill_used_by, because the new skills belong to no press unit of a Run; the page was regenerated.

Evidence

• Before: with the two tests extended to the new skills

  loads_every_factory_skill_as_the_thirdshift_plugin ... FAILED
    skill improve-codebase-architecture missing from the plugin
  

  After:

  cargo test --test fresh_run --test packaging
    test result: ok. 12 passed; 0 failed
    test result: ok. 3 passed; 0 failed
  cargo test                                   # every suite: 0 failed
  cargo clippy --all-targets -- -D warnings    # clean
  cargo fmt --check                            # clean
  git diff origin/issue-27...HEAD -- .claude .agents   # empty: the interactive skills are unchanged
  

• Seams tested: the plugin a session is given (tests/fresh_run.rs), the crates.io package list (tests/packaging.rs) and the prompts page snapshot. The skills' wording isn't tested, as the Spec decided.
• Not run: no real claude session has used these skills yet. Nothing invokes them until thirdshift architect --plan-only: the Architecture review publishes a plan and thirdshift marks it ready #230 adds the Session prompt.

Merge Danger

Door: two-way

Skill text, two test lists and a generated page. Reverting removes them.

Blast Radius: small

The plugin is loaded into every session, so Implement and Review sessions now see four more skills. Their descriptions say "Only for an Architecture review", and no existing Session prompt names them.

Unaddressed findings

Standards

• "parent issue" and "integration branch" in to-tickets are glossary Avoid words. They are the upstream wording, and the skill runs in other repositories whose glossary isn't this one; the existing Factory skills keep upstream wording the same way.
• "idea issue" isn't in CONTEXT.md. It is Headless Factory skills for the Architecture review #229's and Architect run: thirdshift finds and implements a Strong deepening opportunity unattended #27's own term for the issue the review files; adding it to the glossary is not this Ticket's work.
• The skill relies on a Session prompt that doesn't exist yet. thirdshift architect --plan-only: the Architecture review publishes a plan and thirdshift marks it ready #230 adds it.
• Adding a Factory skill means editing three name lists (the page generator and two tests). The pattern predates this change; collapsing it is a separate refactor.
• The tracker-fallback paragraph and the needs-triage rule are repeated across the three publishing skills. Each skill is read on its own, so each carries what it needs.

Spec

• The final-line format is defined in zero places on this branch. Deliberate: it has to live where thirdshift reads it, and thirdshift architect --plan-only: the Architecture review publishes a plan and thirdshift marks it ready #230 owns that code. thirdshift architect --plan-only: the Architecture review publishes a plan and thirdshift marks it ready #230's work in progress defines it in the prompt module, which is what the skill defers to. The Spec review should confirm the two meet.
• "Skip any candidate already covered" is only applied when choosing a plan. When nothing uncovered is Strong and the top candidate of all is covered, nothing is filed, rather than filing the next idea down. That follows Architect run: thirdshift finds and implements a Strong deepening opportunity unattended #27's story 22 (nightly runs shouldn't pile up issues) and "or none if an open issue already covers it"; skipping first would file a weaker idea every night.
• A scan with no candidate at all ends without the final line, which Architect run: thirdshift finds and implements a Strong deepening opportunity unattended #27 makes a failed review. The Spec gives three outcomes and none fits; inventing a fourth line format here would not match what thirdshift architect --plan-only: the Architecture review publishes a plan and thirdshift marks it ready #230 reads. The skill now states the exception in both places so they agree. Worth a decision in the Spec review.
• gh label create for a missing triage label is a new tracker side effect. It replaces "tell the user to run /setup-matt-pocock-skills"; without it, publishing fails outright in a repository that lacks the labels.
• disable-model-invocation: false lets any session invoke the publishing skills. to-spec and to-tickets are invoked by the model from inside the review, so they need it, and improve-codebase-architecture follows implement's precedent. The descriptions now say "Only for an Architecture review".

Closes #229

🤖 Generated with Claude Code