Skip to content

Chief v5 — Story/Ticket Model, No More Subagent Roster - #18

Open
mildronize wants to merge 34 commits into
mainfrom
design/v5-ai-workflow
Open

Chief v5 — Story/Ticket Model, No More Subagent Roster#18
mildronize wants to merge 34 commits into
mainfrom
design/v5-ai-workflow

Conversation

@mildronize

@mildronize mildronize commented Sep 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Chief v5 — Story/Ticket Model, No More Subagent Roster

Summary

Breaking rewrite of Chief's planning pipeline, adapting ideas from
mattpocock/skills (wayfinder, implement, code-review,
the configurable-tracker pattern) into Chief's own story/goal/contract model. Full rationale
and decision trail: docs/design/v5-ai-workflow.md.

  • "Milestone" renamed "story" — the unit was mis-scaled from the start (sized like one
    tracker issue, not a multi-week Milestone/Epic/Sprint).
  • _plan/_todo.md + task specs → _tickets/ frontier — vertical-slice tickets with
    explicit blocking edges, worked by /chief-loop//chief-autopilot as a frontier instead of
    a fixed 3–5 batch.
  • New skills: /chief-wayfinder (map a story's open decisions before planning),
    /chief-build and /chief-test (replace builder-agent/tester-agent as skills, not
    agent files), /chief-review-code (two-axis diff review), /chief-explain and /ask-chief
    (agent- and human-facing replacements for what used to be baked into AGENTS.md),
    /chief-migrate (converts an in-progress v4 milestone into a v5 story),
    /setup-agent-behavior (opt-in, not Chief-specific).
  • chief-install/chief-upgrade removed entirely — once the subagent roster was gone,
    nothing was left for a dedicated install/upgrade skill to do (see design doc, "Round 2
    follow-up"). Getting the skills (npx skills add thaitype/chief) is the only setup step;
    Chief writes nothing to AGENTS.md for any project. template/ is deleted along with it.
  • No more subagent roster — .agents/agents/ (chief-agent, builder-agent,
    tester-agent, answer-verifier-agent) is gone entirely; archived under
    deprecated/agents/ for backward-compat reference, same as review-plan-agent was in v4.
  • No more scripts/setup.sh — it only ever did a small AGENTS.md merge, better suited
    to an agent's diff-then-confirm loop than a blind script; moot anyway once the skill that
    would have called it (chief-install) was also removed.
  • AGENTS.md is now entirely optional and entirely yours — Chief never creates or
    writes to it. The directory diagram, skill table, and responsibility-boundary content that
    used to load into it either moved to /chief-explain (on demand) or was already duplicated
    inside individual skills.
  • Storage location no longer hardcoded to .chief/ — .chief.config.md at the repo root
    can point elsewhere; every chief-* skill checks it first, absence still defaults to
    .chief/.

Breaking changes

  • .chief/milestone-N/ → .chief/story-N/, no automated content migration (see
    /chief-migrate if you want one, or finish in-flight work on a pinned v4.0.0).
  • .agents/agents/*, scripts/setup.sh, chief-install, and chief-upgrade are all gone.
    Getting/refreshing skills (npx skills add thaitype/chief) is the only setup step now;
    see docs/manual/how-to/upgrade.md#upgrading-from-v4 for what a v4 user should know.

Test plan

  • Cut release/v4 from current main before merging (per the design doc's "Versioning
    and migration" section) so existing v4 users can keep pinning it — not yet done as part
    of this branch, by request.
  • npx skills add thaitype/chief into a clean project, confirm every chief-* slash
    command works immediately with no AGENTS.md in sight
  • /chief-init on a clean project, and again on one with an existing .chief/project.md
  • /chief-plan → /chief-wayfinder hand-off and back
  • /chief-build on a real ticket, verify /chief-review-code runs before commit
  • /chief-loop//chief-autopilot working a multi-ticket frontier to completion
  • /chief-migrate against a real in-progress v4 milestone
  • Claude Code plugin install via the updated .claude-plugin/marketplace.json

🤖 Generated with Claude Code

https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD

mildronize and others added 22 commits September 13, 2026 17:33
@mildronize @claude
docs: draft Chief v5 AI workflow redesign
04b496c 
Design doc from a grill-design consultation session covering the
ticket-frontier model (replaces _todo.md), an optional /chief-wayfinder
stage feeding /chief-plan, a configurable storage backend abstraction
(local-only for v5), /chief-build and /chief-test replacing the
persistent builder-agent/tester-agent subagents, /chief-review-code
adopting matt's two-axis code review, and the breaking v4 -> v5
migration plan. Nothing implemented yet — draft for approval.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
docs: rename milestone -> story, resolve remaining v5 design TBDs
08dbde5 
- Renamed "milestone" to "story" throughout the design: the unit is
  sized like one issue/ticket in any tracker (proven by the repo's own
  tutorial example, "Implement user listing endpoint"), not like a
  GitHub Milestone/Epic/Sprint that groups many issues.
- Locked ticket file shape: .chief/story-N/_tickets/<story>-<seq>-slug.md
  with Type (wayfinder:* | implementation) and Status
  (open/claimed/resolved) fields; tickets are git-tracked like the
  rest of .chief/, no gitignore exception.
- Placed matt's missing to-spec sections: Out of Scope in goal.md,
  Testing Decisions in contract.md (needs the contract's module shape
  to be concrete).
- Considered and rejected a global backlog store for unassigned
  tickets - a ticket belongs to exactly one story.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
docs: fix storage-backend pointer to not presuppose .chief/ exists
7e34f04 
Caught a self-contradiction: the first draft said the storage
directory name isn't hardcoded, then put the pointer file that names
it inside .chief/ itself - a bootstrap paradox (can't find the
directory name by looking inside the directory whose name you don't
know yet). Fixed to a fixed-location .chief.config.md at repo root
(outside any configurable directory, same fix matt uses for
docs/agents/issue-tracker.md living outside .scratch/), defaulting to
storage-root: .chief/ when absent.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
docs: add two-tier config, scope the second tier to local backend only
aede7f0 
.chief.config.md (root, fixed) answers "where/which backend" for any
backend. A second file inside the resolved storage root
(.chief/config.md by default) holds everything else - but that only
makes sense for a local-filesystem backend; a future remote backend
has no local directory for a second file to live inside and would
need its own equivalent.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
docs: clarify the common case needs zero or one config file, not two
f924505 
.chief.config.md's absence already means "use the default .chief/" -
make explicit that most projects never create it at all, and only
the rare rename case brings it into existence. No design change, just
removing an ambiguity in how the two-tier config reads.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
feat(v5): add chief-build, chief-test, chief-review-code, chief-wayfi…
edc51c4 
…nder; remove deprecated agents

New skills, per the v5 design doc (docs/design/v5-ai-workflow.md):

- chief-build: replaces builder-agent, absorbs matt/implement's 5-beat
  recipe (TDD at seams, typecheck, single test file, full suite, code
  review, commit). Not an orchestrator - builds one ticket, dual
  invocation (direct or spawned by chief-loop/chief-autopilot).
- chief-test: replaces tester-agent, same dual-invocation pattern, for
  long-running/integration/external validation only.
- chief-review-code: adopts matt/code-review's two-axis (Standards +
  Spec) review, mapped onto .chief/_rules/_standard and story
  goal/contract instead of matt's issue-tracker vocabulary.
- chief-wayfinder: adopts matt/wayfinder's map + decision-ticket model,
  scoped to one story instead of spanning many, sharing the same
  _tickets/ store as implementation tickets. Answer-verifier-agent's
  per-answer codebase check is folded inline into its grilling-ticket
  resolution rather than kept as a separate persistent agent.

Removes the four persistent subagent definitions
(chief/builder/tester/answer-verifier-agent) they replace - v5 has no
.agents/agents/ roster. chief-install and the setup/upgrade scripts
still reference these paths and need updating next; this commit is
intentionally not yet a working install.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
feat(v5): rewrite chief-plan/loop/autopilot/init/grill/retro/rule for…
4879773 
… story+ticket model

- chief-plan: Phase 0 now offers grill-vs-/chief-wayfinder as an
  explicit choice; Phase 3 writes to-tickets-style vertical-slice
  tickets under _tickets/ instead of _plan/_todo.md +
  optional task specs. goal.md gains an Out of Scope subsection;
  contract.md gains a Testing Decisions subsection.
- chief-loop/chief-autopilot: work the ticket frontier
  (open+unblocked, in _tickets/) instead of a fixed 3-5 batch,
  delegating each ticket to /chief-build as its own subagent instead
  of builder-agent. Termination check (goal met AND contract
  satisfied) is unchanged - kept explicit as Chief's own logic, since
  neither matt's implement nor implement-spec provide an equivalent.
- chief-init: confirms the storage location up front (writes
  .chief.config.md only if the user picks a non-default name; most
  projects end up with zero extra files from this step).
- chief-grill: answer-verifier-agent's prompt is now inlined as an
  appendix, spawned as a plain throwaway Agent call instead of a
  registered subagent_type.
- chief-retro: scope detection now reads the ticket frontier instead
  of _plan/_todo.md's checkbox state; "batch" retro renamed "round"
  retro to match (there's no more fixed batch size to name it after).
- chief-rule: milestone -> story terminology only, no structural
  change.

"milestone" -> "story" throughout (see docs/design/v5-ai-workflow.md
for the rationale - the unit is sized like one tracker issue, not
like a GitHub Milestone/Epic/Sprint).

Still pending: chief-install + scripts/setup.sh + scripts/upgrade.sh
(still reference the deleted .agents/agents/* roster - broken until
next commit), template/AGENTS.md, and the docs/manual/** tree.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
feat(v5): retire the agent-roster install path, simplify setup/upgrade
2f8158d 
- chief-install / scripts/setup.sh: only AGENTS.md (+CLAUDE.md
  pointer for Claude Code) gets installed now - no .agents/agents/,
  no .claude/agents/ or .github/agents/ symlink farm, no model
  placeholder prompts. There's nothing left to install per-agent
  since chief-build/chief-test are skills, not registered subagent
  types.
- chief-upgrade: detects a pre-v5 install (.agents/agents/chief-agent.md
  present) and explains the v4->v5 jump is a major, one-way breaking
  change before doing anything - no automated .chief/milestone-N/
  migration, matching the design doc's decision. Routine v5->v5
  refreshes now just diff/merge AGENTS.md directly; retired
  scripts/upgrade.sh since there's no more per-agent-file diffing for
  a script to do.
- template/AGENTS.md: milestone -> story, replaces the 3-agent
  architecture table with the chief-* skill family table, adds the
  storage-location pointer note (.chief.config.md).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
docs(v5): rewrite manual docs for story/ticket model, retire agent ro…
7c08bb9 
…ster docs

- directory-structure.md, rules-hierarchy.md: story-N/, _tickets/,
  _map.md, .chief.config.md storage-root pointer.
- reference/agents.md, explanation/three-agent-model.md: rewritten
  around the chief-* skill family (chief-build/chief-test/
  chief-review-code/chief-wayfinder) replacing the four persistent
  subagents; kept the same file paths to avoid link rot even though
  the "three/four agent" framing no longer fits.
- explanation/why-chief.md, pre-coding-first.md: milestone -> story,
  builder-agent -> /chief-build, tester-agent -> /chief-test.
- tutorials/your-first-milestone.md -> your-first-story.md (renamed,
  rewritten for the wayfinder-choice + goal/contract/ticket flow).
- reference/skills.md: full rewrite - adds chief-wayfinder,
  chief-build, chief-test, chief-review-code entries, updates
  chief-plan/loop/autopilot/grill/retro descriptions.
- how-to/install.md, upgrade.md, write-agents-md.md,
  pick-the-right-skill.md, stress-test-a-design.md, capture-a-rule.md,
  manual/index.md: milestone -> story, subagent references -> skill
  references throughout; upgrade.md gains a "v4 breaking change"
  section matching chief-upgrade's new detection step.
- Root AGENTS.md (this repo's own, used for dogfooding): synced with
  the rewritten template/AGENTS.md, and its Project Rules section no
  longer points at the now-deleted template/.agents/agents/.

Left untouched: docs/directory.md, docs/philosophy.md,
docs/rules-hierarchy.md, docs/writing-agents-md.md - orphaned, not
linked from README or docs/manual/ (predate that restructure).
.chief/milestone-1/_report/* - this repo's own historical dogfooding
records, left as-is rather than rewritten as if they always said
"story."

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
docs(v5): README rewrite (v5.0.0), example-chief rename, fix stale do…
2416a8c 
…gfood state

- README.md / README.th.md: version badge v4.0.0 -> v5.0.0, new
  skills table (chief-wayfinder/chief-build/chief-test/
  chief-review-code), "no more subagent roster" section replacing the
  old Agents table, v5 changelog entry, release/v4 branch listed,
  acknowledgement to mattpocock/skills' wayfinder/implement/code-review
  for what v5 adapted from them.
- docs/example-chief/milestone-1/ -> story-1/, _plan/_todo.md removed,
  _tickets/ added with a placeholder ticket showing the file shape.
- .chief/project.md (this repo's own dogfooded project context) was
  describing a stale pre-lazy-install architecture with a root-level
  .agents/ that doesn't actually exist and a template/.agents/ that's
  now deleted - rewritten to match current reality.
- Small correctness fixes: docs/example-chief/project.md's stray
  "chief-agent framework" wording, chief-rule's "chief-agent will pick
  up this rule" (no such entity anymore), dump-commit's example
  message referencing deleted files.

This closes out the "milestone" -> "story" and agent-roster-removal
sweep across the whole live doc tree (README, docs/manual/**,
docs/example-chief/**, AGENTS.md, skill files). Remaining "milestone"/
agent-roster mentions in the repo are all intentional: historical
explanations of what changed (docs/manual/how-to/upgrade.md's "v4"
section, chief-plan/chief-upgrade explaining the rename/migration),
this repo's own pre-v5 dogfooding records under
.chief/milestone-1/_report/, deprecated/agents/ (already marked
deprecated), and docs/*.md root files orphaned since before the
docs/manual/ restructure (not linked from anywhere live).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
fix(v5): drop story-number prefix from ticket IDs, clarify wayfinder:…
f291cc9 
…task vs implementation

- Ticket IDs go from <story>-<seq> (e.g. "1-3") to plain <seq> (e.g.
  "3"). The prefix existed only to survive a hypothetical promotion
  out of a .chief/backlog/ store into a story - that concept was
  considered and rejected in the same design conversation, so nothing
  ever produces a ticket outside its story folder and the prefix has
  no remaining reason to exist. .chief/story-N/_tickets/ already
  scopes every ticket to its story.
- Design doc: documented why Type: implementation (a value matt's own
  vocabulary has no equivalent for) was reconsidered against matt's
  actual mechanism (presence/absence of the Type field) and then kept
  anyway for robustness, and added a wayfinder:task vs implementation
  comparison table (same "do work" shape, different purpose: task
  unblocks a decision pre-goal/contract and never counts toward story
  completion, implementation delivers the goal post-approval and does).
- Added a "Future ideas" section capturing /chief-triage (matt's
  /triage - only relevant if Chief ever ingests externally-filed bug
  reports, which it doesn't today) as a deferred, undecided idea,
  explicitly linked to the Status vocabulary decision it would affect.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
feat(v5): add chief-migrate-to-v5, chief-explain, ask-chief, setup-ag…
aa4932e 
…ent-behavior

Four new skills from the second grill-design round:

- chief-migrate-to-v5: optional companion to chief-upgrade (which
  deliberately never touches .chief/milestone-N/ content). Migrates
  only open milestones (closed ones are historical, left alone),
  converts _todo.md + task specs into tickets 1:1 without inventing
  blocking edges (tagged Migrated-from: for traceability), asks
  separately before deleting the old milestone directory.
- chief-explain: self-contained agent-facing structural reference
  (directory layout, storage-location resolution, the chief-* skill
  family, _rules/ writing rules). Self-contained because docs/manual/
  is never installed into a consuming project (only skills/ is, per
  .claude-plugin/marketplace.json) - a thin pointer to those files
  would be broken for real users. Model-invocable, unlike most other
  skills here, since it replaces content that used to auto-load via
  AGENTS.md every session.
- ask-chief: human-facing router modeled on mattpocock/skills'
  ask-matt, disable-model-invocation: true. Maps situations to the
  right chief-* skill; defers to chief-explain for structural detail
  rather than duplicating it.
- setup-agent-behavior (skills/setup/, no chief- prefix - content
  isn't Chief-specific): opt-in skill that writes the general
  agent-conduct block (think-before-acting, simplicity-first, etc.)
  into AGENTS.md on request, show-then-confirm, instead of it being
  baked into every AGENTS.md unconditionally.

Together these let AGENTS.md shrink to just Project Rules + a
pointer - the explanatory bulk moves to on-demand skills instead of
loading into every session. Not yet wired up: AGENTS.md itself still
has the old content, chief-install still shells out to scripts/setup.sh
(next commits), and marketplace.json is still missing several skills
from both this round and the previous one.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
feat(v5): retire scripts/setup.sh, rewrite chief-install to write AGE…
f7d0306 
…NTS.md directly

Per the round-2 grill: no CI/non-agentic use case ever motivated the
script, and the one thing it still did (merge into a possibly
pre-existing AGENTS.md) is exactly the kind of judgment-sensitive
write that should go through an agent's diff-present-confirm-write
loop rather than a blind script - the same pattern chief-upgrade
already uses. chief-install now does that directly: clone the target
version, present what would be written (fresh copy, or a diff against
the existing file split at the chief-framework markers), confirm,
write, then handle the Claude Code CLAUDE.md pointer.

AGENTS.md (both root and template) shrink to a two-line "Chief
Framework" marker block pointing at /chief-explain and /ask-chief,
plus Project Rules and the project.md pointer - everything else that
used to live here (storage location, rules hierarchy, directory
structure, the 3-agent table, responsibility boundary) either moves
to chief-explain/ask-chief, or was already duplicated inside each
individual skill's own instructions and is just dropped as redundant.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
feat(v5): add storage-location pointer-check to every chief-* skill
d87fe90 
Matches matt's own hard-dependency pattern (to-tickets, to-spec,
code-review, wayfinder each carry their own one-liner rather than
relying on a central doc) - verified against the actual skill files,
not assumed. Every chief-* skill (plan, loop, autopilot, build, test,
review-code, wayfinder, grill, retro, rule, migrate-to-v5) now
resolves .chief.config.md before touching any .chief/ path, instead
of only chief-init and AGENTS.md's now-removed "Storage location"
section knowing about it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
fix(v5): add missing skills to marketplace.json
1d06d7d 
Was still listing only the v4 skill set - missing all four skills
added earlier this session (chief-build, chief-test,
chief-review-code, chief-wayfinder) plus the four from this round
(chief-migrate-to-v5, chief-explain, ask-chief,
setup-agent-behavior). Without this fix none of the new skills were
installable via the Claude Code plugin path.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
docs(v5): README + skills.md + install.md for the round-2 skill set
73b9a28 
- README.md / README.th.md: skills table gains chief-explain,
  ask-chief, chief-migrate-to-v5, setup-agent-behavior; "no subagent
  roster" section renamed/expanded to also cover the now-minimal
  AGENTS.md and the removed scripts/setup.sh; v5 changelog and
  Upgrading section updated to match.
- docs/manual/reference/skills.md: added entries for all four new
  skills in their respective sections.
- docs/manual/how-to/install.md: replaced the scripts/setup.sh-based
  "Manual install (no npx)" instructions with the new reality - an
  agent session is required either way now (chief-install writes
  AGENTS.md directly), with a genuinely hand-rolled fallback for
  anyone who wants zero agent involvement at all.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
docs: append Round 2 design record to v5-ai-workflow.md, update status
3ce15b5 
Documents the four new skills (chief-migrate-to-v5, chief-explain,
ask-chief, setup-agent-behavior), the AGENTS.md slimdown and the
audience-split reasoning behind it, why scripts/setup.sh got retired
after all (the CI use case it was kept for turned out not to be a
real one), and two corrections caught during this round's own review
(the ticket ID story-prefix and the Type: implementation value, both
already fixed in the shipped skills, now explained here too).

Status line updated - both rounds are now actually implemented on
this branch, not just designed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
fix: .chief/project.md still referenced deleted scripts/setup.sh
c7a1d36 
Missed this file when scripts/setup.sh was retired earlier in the
session - the previous project.md update (during the same removal)
happened before the final decision to drop the script entirely, so it
went stale again. Final sweep caught it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
docs: archive the four removed v5 agent files under deprecated/agents/
99232ec 
Retrieved from ca4b7f4~1 (their content before this branch deleted
them from template/.agents/agents/). Matches the existing precedent
already in this repo - review-plan-agent.md was archived the same way
when deprecated in v4 (kept for backward compatibility with existing
installs, not used by anything current). Each file gets the same
treatment: a DEPRECATED line prepended to its description naming the
v5 replacement, and a blockquote under the H1 pointing at
docs/design/v5-ai-workflow.md.

- chief-agent.md -> folded into chief-plan/chief-loop/chief-autopilot
- builder-agent.md -> /chief-build
- tester-agent.md -> /chief-test
- answer-verifier-agent.md -> inlined into chief-grill/chief-wayfinder

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
refactor: extract setup-agent-behavior's block into template.md
c1742b5 
Matches the pattern chief-install/chief-upgrade already use
(template/AGENTS.md, separate from their own step-by-step
instructions) and the one setup-matt-pocock-skills uses for its own
seed templates (issue-tracker-local.md etc. living next to its
SKILL.md). The content is now skills/setup/setup-agent-behavior/
template.md; SKILL.md reads and writes it rather than embedding it
inline, so the actual installed content has one source of truth
separate from the procedure that installs it. Renumbered the
now-4-step process accordingly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
refactor: rename chief-migrate-to-v5 -> chief-migrate
649d5f8 
The skill's Steps are hardcoded to the v4->v5 shape change and will
need rewriting (not extending) whenever a future version changes
.chief/'s shape again - but the NAME doesn't need to change each
time, matching chief-upgrade's own already-version-agnostic naming.

Added a scope note at the top of the skill file making this explicit
for future maintainers: no generic "migrate from anything" logic
exists here, just a stable identity; git log -p on the file is the
actual historical record of how past migrations worked, deliberately
not a separately maintained changelog (which would just duplicate
what git already tracks, with more drift risk).

Rewrote the description field to be genuinely version-agnostic too,
after a first draft was caught still leaking v5-specific vocabulary
("tickets") even after the version numbers themselves were removed -
it now names neither a version nor any terminology newer than "an
old .chief/ layout" / "the current one," and says outright that it's
intentionally vague, pointing to the skill's own Steps for specifics.

Updated all references (marketplace.json, README.md/README.th.md,
docs/manual/reference/skills.md, chief-explain, ask-chief,
docs/design/v5-ai-workflow.md) and appended a "Round 2 follow-up"
section to the design doc recording the rename and why.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize @claude
feat(v5): remove chief-install and chief-upgrade entirely
2c304f4 
Triggered by noticing setup-agent-behavior already handles
"install or update this block" as ONE skill, while chief-install/
chief-upgrade did the structurally identical operation (diff/present/
confirm/write a block in AGENTS.md) as TWO - an inconsistency with no
real justification once the .agents/agents/ subagent roster (their
original reason to exist, and the bulk of their complexity - model
placeholders, symlink farms, per-agent integration) was already gone.

Re-examined what either skill still did and found nothing left worth
keeping as a dedicated skill:
- The "Chief Framework" AGENTS.md pointer block was redundant -
  chief-explain/ask-chief are already visible via their own skill
  descriptions the moment they're installed, and chief-explain is
  model-invocable besides.
- CLAUDE.md -> AGENTS.md symlinking for Claude Code is the one piece
  with genuine non-redundant value, but skills don't depend on
  AGENTS.md/CLAUDE.md existing to be invocable - only a user's own
  Project Rules being recognized needs it. Explicitly NOT relocated
  into chief-init or anywhere else, by request - users who want it
  set it up themselves now.
- Pre-v5 detection + breaking-change explanation stopped earning an
  agent-driven proactive check once there was no subagent roster left
  to clean up - a leftover .agents/agents/chief-agent.md is now just
  inert dead weight, not something that breaks anything by existing.
  Documentation (docs/manual/how-to/upgrade.md, "Upgrading from v4")
  covers this for whoever hits it instead.

template/ (existed solely to be copied by chief-install) is deleted
entirely - template/AGENTS.md had no remaining reader. "Upgrading"
Chief is now just npx skills add, which was already idempotent and
version-pinnable on its own.

Rewrote every doc that assumed an install/upgrade skill existed:
README.md/README.th.md (Quickstart, Upgrading, Compatibility,
changelog, Development), docs/manual/how-to/install.md (retitled and
slimmed to "get the skills", with AGENTS.md/CLAUDE.md now covered as
optional/manual), docs/manual/how-to/upgrade.md (one-step refresh,
"Upgrading from v4" reframed as pure documentation, not agent-
enforced detection), docs/manual/reference/{agents,skills,
directory-structure}.md, docs/manual/tutorials/your-first-story.md
(renumbered), chief-explain, ask-chief, chief-migrate (no longer
"separate from chief-upgrade" since chief-upgrade doesn't exist),
setup-agent-behavior (its own AGENTS.md-existence check no longer
redirects to a now-nonexistent chief-install), root AGENTS.md and
.chief/project.md (this repo's own dogfooded files, both were
pointing at the now-deleted template/ and description of chief-install's
steps).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wNZjehJSPGH6YhdCtMsBD
@mildronize
mildronize force-pushed the design/v5-ai-workflow branch from 3767baa to 2c304f4 Compare September 13, 2026 17:39
mildronize and others added 6 commits September 15, 2026 04:43
@mildronize @claude
fix(v5): restore multi-file goal/contract buckets, add version marker
a144487 
Two gaps found while dogfooding chief-migrate on design/v5-ai-workflow:

1. chief-plan's Phase 1/2 narrowed goal/contract to a single file per
   story. The design doc's actual decision ("Goal/contract stay two
   files") was only about goal vs. contract as two separate gates, never
   about forbidding v4's per-bucket multi-file support (multiple goal or
   contract files for genuinely distinct scope). That capability is
   restored: goal.md/contract.md remain the required Phase 1/2 gate
   file, but now act as an index — linking any sibling files in the same
   bucket — instead of the only place content can live. chief-plan now
   verifies the index stays linked as part of its existing intra-bucket
   consistency check. chief-review-code's spec-source step now reads
   goal.md/contract.md's linked files too, not just the two named files.
   chief-migrate copies v4's files as-is (no renaming) and, when none is
   already named goal.md/contract.md, creates one holding only the empty
   Out of Scope/Testing Decisions heading plus a plain link list to the
   copied files — never a synthesized summary, to avoid misrepresenting
   the original content.

2. No installed skill carried a version marker, so an agent had no way
   to tell which build of Chief it was running — npx skills only copies
   skills/, never docs/ or git history, so git tags aren't visible from
   inside a consuming project. Added a hand-bumped `Chief version` line
   to chief-explain/SKILL.md (the one skill guaranteed to travel with
   every install), starting at v5.canary-1. Informational only, not an
   integrity check.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@mildronize @claude
fix(v5): drop fixed goal.md/contract.md filenames, default new sectio…
32626d8 
…ns to their own file

Revises the previous commit per user feedback: no filename is hardcoded
for goal/contract content at all (fully free-form again, like v4 — a
skill never assumes one specific name holds everything). Out of Scope
and Testing Decisions default to their own new file
(out-of-scope.md / testing-decisions.md) instead of living inside a
required index file, folded into an existing file only when the
story's scope is small enough that a separate file would be overkill
(a judgment call each time, not a rule the skill enforces).

Downstream effect: chief-review-code's spec-source step and its Spec
sub-agent prompt now read every file in the story's _goal/ and
_contract/ buckets, since there's no single named file to point at
anymore. chief-migrate drops the "which file becomes the gate" logic
entirely — it just adds Out of Scope/Testing Decisions as their own
new file by default.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@mildronize @claude
fix(v5): restore multi-file goal/contract buckets, add version marker (…
712dbb0 
…#24)

* fix(v5): restore multi-file goal/contract buckets, add version marker

Two gaps found while dogfooding chief-migrate on design/v5-ai-workflow:

1. chief-plan's Phase 1/2 narrowed goal/contract to a single file per
   story. The design doc's actual decision ("Goal/contract stay two
   files") was only about goal vs. contract as two separate gates, never
   about forbidding v4's per-bucket multi-file support (multiple goal or
   contract files for genuinely distinct scope). That capability is
   restored: goal.md/contract.md remain the required Phase 1/2 gate
   file, but now act as an index — linking any sibling files in the same
   bucket — instead of the only place content can live. chief-plan now
   verifies the index stays linked as part of its existing intra-bucket
   consistency check. chief-review-code's spec-source step now reads
   goal.md/contract.md's linked files too, not just the two named files.
   chief-migrate copies v4's files as-is (no renaming) and, when none is
   already named goal.md/contract.md, creates one holding only the empty
   Out of Scope/Testing Decisions heading plus a plain link list to the
   copied files — never a synthesized summary, to avoid misrepresenting
   the original content.

2. No installed skill carried a version marker, so an agent had no way
   to tell which build of Chief it was running — npx skills only copies
   skills/, never docs/ or git history, so git tags aren't visible from
   inside a consuming project. Added a hand-bumped `Chief version` line
   to chief-explain/SKILL.md (the one skill guaranteed to travel with
   every install), starting at v5.canary-1. Informational only, not an
   integrity check.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(v5): drop fixed goal.md/contract.md filenames, default new sections to their own file

Revises the previous commit per user feedback: no filename is hardcoded
for goal/contract content at all (fully free-form again, like v4 — a
skill never assumes one specific name holds everything). Out of Scope
and Testing Decisions default to their own new file
(out-of-scope.md / testing-decisions.md) instead of living inside a
required index file, folded into an existing file only when the
story's scope is small enough that a separate file would be overkill
(a judgment call each time, not a rule the skill enforces).

Downstream effect: chief-review-code's spec-source step and its Spec
sub-agent prompt now read every file in the story's _goal/ and
_contract/ buckets, since there's no single named file to point at
anymore. chief-migrate drops the "which file becomes the gate" logic
entirely — it just adds Out of Scope/Testing Decisions as their own
new file by default.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
@mildronize @claude
fix(v5): split chief-loop into fast (default) / strict modes, fix app…
c76a157 
…roval-gate stall

User-reported: chief-loop feels slower than v4. Structural comparison
against v4's chief-loop/builder-agent found four real differences:

1. Bug: chief-loop's re-planning step (running /chief-plan Phase 3 when
   the ticket frontier runs dry) never overrode Phase 3's own approval
   gate, unlike chief-autopilot which explicitly does ("do NOT wait for
   approval on this — that's autopilot"). Since chief-loop's own rules
   say "NEVER stop for human input," this was a real contradiction that
   could stall an unattended run waiting on a human. Fixed: chief-loop
   now carries the same explicit no-wait override chief-autopilot has,
   both when tickets don't exist yet and when re-planning after the
   frontier empties.

2. chief-build mandates a TDD-driven build recipe and a mandatory
   two-subagent /chief-review-code pass on every single ticket. v4's
   builder-agent had neither — implement, fix fallout, recheck, commit.

3+4. Combined effect of the above two: chief-loop got noticeably
   heavier per unit of work than v4's loop, without a real decision
   that the extra rigor was wanted on every run.

Fix: chief-build gains an explicit two-mode split (thorough/fast),
sharing everything except the recipe itself — required sources, story
scope, auto-fix policy, escalation format, and commit format are
identical either way. chief-loop gets a `fast`/`strict` argument
(matching chief-autopilot's existing `auto`/`safe` pattern instead of
forking into a separate skill file): fast is the new default and
restores v4's speed, strict opts into today's TDD+review-per-ticket
behavior. If the mode isn't given as an argument, chief-loop asks at
its existing Entry Confirmation gate; no answer defaults to fast.
chief-autopilot is updated to always build in fast mode too (v4
parity) — it has no argument to change this, only chief-loop does.

Drive-by fix: chief-build's "Required sources" step still assumed the
old fixed `_goal/goal.md`/`_contract/contract.md` filenames that PR
#24 removed — updated to read every file in the bucket, matching
chief-review-code's equivalent fix in that PR.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@mildronize @claude
fix(v5): remove remaining fixed goal.md/contract.md assumptions
d4884fb 
Follow-up to this PR's chief-build fix and PR #24: chief-retro's
coverage-check table example, chief-wayfinder's framing text, and
chief-test's Required sources step all still named the old fixed
_goal/goal.md / _contract/contract.md filenames that PR #24 removed.
Updated all three to read/reference every file actually present in
the bucket, same as chief-build and chief-review-code already do.
Confirmed clean with a repo-wide grep afterward.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@mildronize @claude
fix(v5): rename fast/thorough mode pair to standard/strict for consis…
78f495d 
…tency

Caught an inconsistency across this PR's own commits: chief-build used
"fast"/"thorough" internally while chief-loop's argument used
"fast"/"strict" — two different words for the same TDD+review-mandatory
mode. "fast" was also the wrong word regardless: the distinguishing
property between the two modes is whether TDD/code-review is mandatory,
not speed — standard mode still runs typecheck and tests like always,
it just doesn't force red-green-per-seam TDD or a mandatory
/chief-review-code pass.

Renamed uniformly across chief-build, chief-loop, chief-autopilot, and
chief-explain: "fast" -> "standard", "thorough" -> "strict". No
behavior change, wording only. Confirmed clean with a grep afterward
(the one remaining "fast" hit, in chief-explain's smell-baseline
paragraph, is unrelated — describes chief-build's checks being fast/
deterministic vs chief-test's slow ones, not a mode name).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@mildronize
mildronize added this pull request to stack #26 September 15, 2026 07:52
@mildronize @claude
fix(v5): move v4-comparison explanation to chief-explain only
4fb8029 
The v4-comparison clause ("matches v4's process", "matches v4 builder-
agent's process/speed") was repeated next to every "standard mode" /
"strict mode" mention across chief-build, chief-loop, and
chief-autopilot. Trimmed all of them to just name the mode (the
mechanical definition — TDD, review, yes/no — stays where it's
operationally needed, e.g. chief-build's own Mode section and recipe;
only the historical/comparative framing was cut). Added one
consolidated explanation to chief-explain instead, right after the
skill-family table, as the single place this framework-history context
lives.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@mildronize
mildronize removed this pull request from stack #26 September 15, 2026 13:31
mildronize and others added 5 commits September 15, 2026 20:32
@mildronize
fix(v5): split chief-loop into fast (default) / strict modes, fix app…
d7a9379 
…roval-gate stall (#25)
@mildronize @claude
fix(v5): remove dead docs/ references from installed skills
1f982b9 
User-reported: chief-init isn't self-contained — it references
docs/example-chief/ "in the chief repo" as a usable Reference, but
npx skills add only ever copies skills/ into a consuming project, so
that path never exists there. chief-explain's own design note already
states this principle explicitly; these were leftover violations of it.

Scanned all 21 skill files for docs/ references. Found 8 across 4
files, all pointing at docs/design/v5-ai-workflow.md or
docs/example-chief/:

- chief-init: the docs/example-chief/ "Reference" line (the real bug —
  presented as something to go read) now points at /chief-explain
  instead, which IS installed and already carries the full directory
  diagram. Also dropped a dead citation next to the storage-location
  question, whose rationale was already stated in the same sentence.
- chief-explain: its own directory-diagram comment had one leftover
  citation despite the file's stated self-contained design — replaced
  with the one-line reason inline.
- chief-plan (3 spots) and chief-wayfinder (2 spots): dead citations
  next to rationale that was already given inline in the same
  sentence — removed, kept the substance.

Everything removed was supplementary ("why" citations), never
operationally required — no skill's actual behavior depended on
reading the cited file. Confirmed clean with a repo-wide grep
afterward. False positives excluded: chief-rule's own
.chief/_rules/README.md (a file it writes into the user's project,
not a chief-repo path), chief-init's/chief-migrate's mentions of
_template/ and .agents/agents/ (files that may exist in the user's
own project), and loop-readiness's generic "existing docs/" (about
the target project's own docs, not chief's).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@mildronize
fix(v5): remove dead docs/ references from installed skills (#27)
383d124
@mildronize @claude
chore(v5): bump Chief version to v5.canary-2
9bcd0b7 
Covers PR #27 (self-contained doc-reference cleanup) on top of the
v5.canary-1 snapshot.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@mildronize
chore(v5): bump Chief version to v5.canary-2 (#28)
bd82460
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mildronize