docs: retire the customization roadmap, and say what a new session activates - #23
Merged
Merged
Conversation
…tivates Two changes, both about not promising more than the product delivers. Local profile overrides were the top unbuilt item through v2. They are now retired rather than deferred. A per-user override layer creates a second source of persona truth competing with the repo, and the confusion between core version and local customization costs more than the convenience buys. Team-scoped profiles, which put the same layer at project scope via claude-team init and .claude-team/, are retired for the same reason. Session handoff briefing stays: it is coordinator behavior, not a second source of truth. Customizing a persona now has two documented paths, both of which keep one source of truth: open a pull request, or fork. A new CONTRIBUTING.md covers the contribution path and persona authoring, including the requirement most likely to bite a first contributor, which is that generate-agents.sh aborts on a profile with no ## Greeting section. README gains a Customizing the Team section stating the two paths and why there is no third. The dated ROADMAP row that promoted overrides to top priority stays verbatim; a new row records the retirement. The installer overstated what it had activated. The earlier claim that it names subagents as ready to delegate to was wrong: that message was deleted by cbbb7a4 when install.sh began delegating to claude-team sync. The real defect was silence. Claude Code registers subagents and hooks when a session starts and reads slash commands on demand, so a sync activates one of the three immediately. Nothing said so, and three green checkmarks in a row read as three live capabilities. install.sh then closed with "Your Claude dev team is ready." A SessionStart hook had the starkest version of it, since it cannot by definition fire in the session that registers it. A say_session_scope helper keeps the wording in one place, called from cmd_sync. cmd_install_hook and the installer's closing block get their own line. install.sh needs no sync message of its own because it already delegates to the CLI. Every message that was already accurate is untouched. Seven tests added, five of which fail on the previous code. The other two are regression guards on messages that were already correct: install-commands still promising immediacy, and use still asking for a restart. Nothing asserted any user-facing messaging before, so a checkmark could claim a capability that was not live and CI stayed green. Also corrected: the add-a-persona steps never mentioned ## Greeting, so following them literally hit a hard generator abort with no forewarning from the section being read. Stale test counts in README and ROADMAP said 135 and 136. 170 tests. shellcheck clean. Verified by running the installer end to end and reading the full transcript. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019j5DHEZsoeCGRueTbNLuTb
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two changes, both about not promising more than the product delivers.
170 tests (was 163). shellcheck clean.
1. Local profile overrides are retired, not deferred
They were the top unbuilt item through v2. Building them would create a second source of persona truth competing with the repo, with no reliable way to tell whether Akira is behaving like upstream Akira or like a local edit. The confusion between core version and customization costs more than the convenience buys.
Team-scoped profiles (
claude-team initwriting.claude-team/) are retired for the same reason at project scope. Session handoff briefing stays — it's coordinator behavior, not a second source of truth.Customizing a persona now has two documented paths, both keeping one source of truth: open a PR, or fork.
New
CONTRIBUTING.mdcovers the contribution path and persona authoring, including the requirement most likely to bite a first contributor:generate-agents.shaborts on a profile with no## Greeting. README gains a Customizing the Team section stating the two paths and why there is no third.The dated ROADMAP row that promoted overrides to top priority stays verbatim. A new row records the retirement.
2. The installer overstated what it had activated
My original claim was wrong and is worth correcting. I said the installer names subagents as ready to delegate to. That message was deleted by
cbbb7a4wheninstall.shbegan delegating toclaude-team sync.The real defect was silence. Claude Code registers subagents and hooks when a session starts, and reads slash commands on demand — so a sync activates one of the three immediately and leaves two waiting. Nothing said so, and three green checkmarks in a row read as three live capabilities.
install.shthen closed withDone! Your Claude dev team is ready.The SessionStart hook had the starkest version: it cannot by definition fire in the session that registers it, and printed a bare ✓.
A
say_session_scopehelper keeps the wording in one place.cmd_install_hookand the installer's closing block get their own line.install.shneeds no sync message of its own since it already delegates to the CLI. Every message that was already accurate is untouched —use,reset, the coordinator, andinstall-commandswere all correct.Install transcript now reads:
Also corrected
## Greeting. Following them literally hit a hard generator abort with no forewarning from the section being read — the requirement was documented only under Editing an existing persona.Testing
Seven tests added; five fail on the previous code. The other two are deliberate regression guards on messages that were already correct (
install-commandspromising immediacy,useasking for a restart).Nothing asserted any user-facing messaging before this —
grep -nE "immediately|new session|restart" tests/run.shreturned nothing — so a checkmark could claim a capability that wasn't live and CI stayed green.Verified by running the installer end to end into a temp HOME and reading the full transcript, which is what surfaced the problem originally.
Generated by Claude Code