Personas: settle the mechanics (skill load paths, subagent loading, scoping) (tk-ohrlc)#130
Closed
zook-bot wants to merge 2 commits into
Closed
Personas: settle the mechanics (skill load paths, subagent loading, scoping) (tk-ohrlc)#130zook-bot wants to merge 2 commits into
zook-bot wants to merge 2 commits into
Conversation
…ding, scoping, assume-persona Investigation deliverable for tk-ohrlc (child of epic tk-ae96t): answer the four deferred "Mechanics" questions left as a TBD stub in docs/personas.md, grounded in CURRENT Claude Code docs (fetched + cross-checked 2026-06-14; load-bearing claims re-verified against the primary skills/sub-agents pages, not training memory). This is a FINDINGS write-up, not a doc edit. docs/personas.md lives only on the held PR #123 (branch polecat/tk-oe8o0), not on main, so the stub cannot be filled here. Per the dispatch note, findings are persisted standalone under specs/tk-ohrlc/research/ (mirroring how tk-oe8o0 persisted its prior-art surveys) and return to the epic host for operator discussion; settled mechanics fold into docs/personas.md later. Key findings: - Q1 load paths: a skill is a <name>/SKILL.md directory; discovery is FLAT within one .claude/skills/ (no nested-dir grouping) but spans many .claude/skills/ dirs (parents to repo root + on-demand monorepo dirs). Precedence managed>personal>project; plugins namespaced. Persona grouping = naming convention or plugin boundary, not a dir tree. - Q2 subagent loading: the subagent `skills:` frontmatter PRELOADS full skill bodies into the subagent's isolated context at startup — the primitive that lets process- skills "ride with the persona." Skill tool also available unless gated via tools/ disallowedTools. - Q3 scoping: no native per-agent visibility scoping of project skills. Levers: subagent `skills:` preload, disabled-by-default plugin, disable-model-invocation (hides the description AND blocks preload — a real exclusivity constraint), skillOverrides. allowed-tools scopes capability, not visibility. Path A/B/C trade-off surfaced for the operator. - Q4 assume-persona: in-session, /invoke the persona identity skill (persists). At boot, `--agent`/`agent` setting runs an agent as the main session with `skills:` preloads + an initialPrompt (processes commands/skills) — the cleanest documented "boot as the persona." No bare `claude --skill` flag. Adds: - specs/tk-ohrlc/README.md — investigation record + one-line answers + status - specs/tk-ohrlc/research/mechanics.md — full findings, per-answer provenance, synthesis into the persona model, open questions for operator discussion, uncertain/not-documented Part of epic tk-ae96t.
zook-bot
commented
Jun 14, 2026
zook-bot
left a comment
zook-bot
left a comment
Contributor
Author
There was a problem hiding this comment.
Blocking finding, posted as COMMENT because GitHub does not allow zook-bot to request changes on a PR authored by zook-bot.
specs/tk-ohrlc/README.md:51,specs/tk-ohrlc/research/mechanics.md:243,specs/tk-ohrlc/research/mechanics.md:257,specs/tk-ohrlc/research/mechanics.md:277: the write-up names/invokeas the in-session andinitialPromptentry point for loading a persona skill. I could not verify/invokein the current Claude Code docs: the skills page documents direct invocation as/<skill-name>, and the commands reference does not list an/invokecommand. This is load-bearing for Q4, so the artifact would send the operator toward a non-existent command. Please replace these with the concrete skill command form, e.g./persona-xor/<skill-directory-name>, and adjust the startup/initialPrompt wording accordingly.
Validation performed: reviewed the full PR diff, checked git diff --check, and re-checked the relevant Claude Code skills/subagent/commands docs.
…e> (tk-pmavm) Codex review on PR#130 flagged that `/invoke` is not a documented Claude Code command. Skills are invoked directly as `/<skill-name>` (the skill directory name is the command); there is no `/invoke` command. Replace every `/invoke` command reference in the persona mechanics findings with the documented `/persona-x` / `/<skill-name>` form, and reword the in-session and initialPrompt entry points accordingly. Plain-English "invoke" verbs and the Skill-tool references are left intact. Addresses PR#130 review 4492498506.
zook-bot
commented
Jun 14, 2026
zook-bot
left a comment
zook-bot
left a comment
Contributor
Author
There was a problem hiding this comment.
No blocking findings.
Re-reviewed PR head 8e40bdc after the follow-up commit. The merged files no longer reference /invoke; Q4 now uses the documented direct skill command form (/persona-x / /<skill-name>), which matches the current Claude Code skills docs. I also checked the docs-only diff with git diff --check.
Non-blocking note: the PR description still has one stale /invoke mention in its implementation notes, but the merged artifact is corrected.
zook-bot
marked this pull request as ready for review
June 14, 2026 06:32
Contributor
Author
|
Superseded by PR #132 (the consolidated architect-persona PR, now in operator-reviewed rework as bead tk-ae96t.2). Closing as superseded. |
zook-bot
added a commit
that referenced
this pull request
Jun 23, 2026
…ttle mechanics (tk-ae96t.1) Build the FIRST gc-toolkit persona — the architect — on the persona-as-skill model, setting the convention every later persona follows. Supersedes the held #123 (docs/personas.md) and #130 (mechanics findings); re-includes both since neither is on main. - Prior-art survey (specs/tk-ae96t.1/research/): BMAD-METHOD "Winston", Roo Code Architect mode, wshobson/agents, Martin Fowler — distilled into the architect. - Persona: skills/architect (city-wide identity), agents/architect/skills/ {architect-design,architect-review} (agent-local process-skills), and the agents/architect standing form (on_demand, dormant). pack.toml registers it. - Path A realized natively: agent-local skills keep the methods out of plain workers by construction — the deprecated `skills:` preload + the un-authored `skillOverrides` trim are replaced. docs/personas.md "Mechanics" filled; "Three layers" reframed concept-first (operator inline comment on #123). Held for operator review — sets the convention before later personas follow it. Re-includes #123 (tk-oe8o0): docs/personas.md, README line, specs/tk-oe8o0/*. Re-includes #130 (tk-ohrlc): specs/tk-ohrlc/*.
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
1 participant
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.
Summary
Fills the "Mechanics (deferred)" section of docs/personas.md. Do AFTER tk-oe8o0
lands (this fills its stub). Work out, against CURRENT Claude Code / skills docs
(NOT training memory — that part changes fast; use claude-code-guide / live docs):
not global — avoid bloating plain workers);
Origin: mechanik-thread design session 2026-06-13. Parent: tk-ae96t.
Implementation notes
Findings write-up complete (tk-ohrlc) — docs-only, 2 files under specs/tk-ohrlc/:
Answers the 4 deferred "Mechanics" questions behind docs/personas.md, verified against
CURRENT Claude Code docs (fetched + re-checked 2026-06-14, not training memory):
Q1 skill load paths (flat-within-dir, spans many .claude/skills/; precedence; plugin namespacing)
Q2 subagent skill loading (the
skills:preload primitive = process-skills ride with the persona)Q3 scoping (no native per-agent visibility scoping; Path A/B/C trade-off; disable-model-invocation
hides description BUT blocks preload — a real exclusivity constraint; allowed-tools != visibility)
Q4 assume-persona entry point (/invoke in-session; --agent + skills: + initialPrompt at boot)
Findings-only: docs/personas.md is held on PR #123 (not main), so the stub is NOT edited here.
Results return to epic host (tk-ae96t) for operator discussion before folding into the doc.
Refinery: please merge to main — normal docs landing (mirrors tk-oe8o0's persisted surveys).
Refinery handoff
tk-ohrlc(task, P2)polecat/tk-ohrlcmainmainvia Gastown Refinery.