Land docs/personas.md — persona/agent model (persona = skill) (tk-oe8o0)

README.md

@@ -37,6 +37,7 @@ opinions rather than cloned directly.
 - `docs/gascity-reference.md` — index of canonical Gas City documentation at `docs.gascityhall.com`, plus the bar for adding new `docs/gascity-*.md`
 - `docs/gascity-local-patching.md` — recommended process for cities that must carry local `gascity` patches
 - `docs/file-structure.md` — conventions for where docs and specs live in this pack
+- `docs/personas.md` — the persona/agent model: a persona is a skill (identity plus process-skills), and when a persona earns a standing addressable agent
 
 ## Usage
 

docs/personas.md

@@ -0,0 +1,78 @@
+---
+name: Personas
+description: How gc-toolkit gives an LLM a role — a persona is a skill (identity plus process-skills), how a persona differs from a standing agent, and the three layers (persona, distribution, Gas City orchestration).
+---
+
+# Personas (gc-toolkit)
+
+> How we give an LLM a role. The core is framework-agnostic; Gas City wraps it
+> (last section). Mechanics — skill paths, subagent wiring, scoping — are a
+> follow-up verified against current Claude Code docs, not assumed.
+
+## A persona is a skill
+Making an LLM *take on a persona* is **loading a skill into its context** —
+the universally-adopted skill mechanism already is the persona-loader. A persona is:
+
+- **Identity** — a tight, always-on stance ("who I am," what I optimize for).
+  Always loaded; if it's too big to always carry, tighten it.
+- **Owns** — advisory: the project-relative artifacts it keeps current
+  (e.g. docs/architecture.md). Nothing enforces it; the persona honors it.
+  Promoted to first-class metadata only when a real need appears.
+- **Processes** — what it can *do*, each a **skill** of its own
+  (architect-review), referenced by name. Each process-skill is
+  self-contained: it bundles its own reference material and declares the files
+  it reads. There is no separate "references" or "knows" facet — those live
+  inside the skills that use them.
+
+No tiering by default — every process is a skill. Add a private/inline process
+only when something genuinely can't stand alone.
+
+The persona-skill *is* the identity plus an index of its method-skills.
+
+## Identity travels; owns/knows resolve per project
+The identity is portable (architect works in any repo). What it owns and
+reads is project-relative — the architect maintains *this* repo's
+docs/architecture.md, whichever repo it's loaded in.
+
+## Persona vs. agent
+An **agent** is a persona *instantiated as a standing, addressable instance.*
+Most persona use is transient — load, work, release. A persona earns a standing
+agent only when it must **gate** work or **patrol continuously**; otherwise load
+transiently. (In Gas City you bring attention to a *bead*, not an agent, so
+"address the architect" mostly dissolves.)
+
+## Keep skills curated, not global
+Every process being a skill does NOT mean every skill loads into every agent —
+that would bloat a plain worker with methods it never uses. So:
+- a persona's process-skills **ride with the persona**, loaded when engaged;
+- only **broadly-shared** methods (red-green) are top-level/always-discoverable;
+- a plain worker carries only its minimal set.
+
+## Three layers
+1. **Persona = the skill.** The content; framework-agnostic.
+2. **Distribution = a generator.** Renders one canonical persona into each
+   framework's skill location (.claude/skills/, OpenHands .agents/skills/, ...)
+   and extracts invokable process-skills. Needed only for >1 target.
+3. **Gas City = orchestration.** Which persona onto which bead, owns/knows
+   resolved per rig, the gc.persona stamp, and the first-pass triage that reads
+   persona descriptions to assign one to a bare bead.
+
+## Example
+    ---
+    name: architect
+    description: Use when a change touches system structure, or a PRD needs an
+      architectural review.
+    ---
+    # Architect
+    ## Who I am
+    I hold the shape of the system — boundaries, coherence, cost of future change.
+    ## What I maintain
+    - docs/architecture.md   (advisory)
+    ## What I do
+    - review -> the architect-review skill
+    - design -> the architect-design skill
+
+## Mechanics (deferred — verify against current docs)
+To fill next, against the latest Claude Code / skills docs rather than memory:
+where skills load from (flat vs. nested), how subagents consume skills, the
+persona-process scoping mechanism, and the assume-persona entry point.

specs/tk-oe8o0/README.md

@@ -0,0 +1,67 @@
+---
+name: Personas model — landing record (tk-oe8o0)
+description: Work record for adopting docs/personas.md — the design-session rationale behind the persona/agent model, what landed where, and what was deferred. The lean published doc lives in docs/personas.md; this preserves the fuller reasoning.
+---
+
+# Personas model — landing record
+
+This directory is the historical record for **tk-oe8o0**, which adopted the
+persona/agent model as a central doc. The authoritative, lean statement is
+[`docs/personas.md`](../../docs/personas.md); this record preserves the fuller
+design-session rationale and the prior-art that the model draws on.
+
+## Provenance
+
+- **Design session:** mechanik-thread, 2026-06-13. The full doc draft and the
+  architect example were converged there.
+- **Status:** operator-blessed 2026-06-13; the prior HELD was lifted. The doc
+  was landed verbatim as `docs/personas.md`.
+- **Builds on:** the shipped bead-universe layer (bead-host / proactive agents,
+  `mol-first-reaction`, `gc-attention.sh`).
+- **Prior art:** five surveys, persisted in full (primary-source write-ups +
+  provenance) under [`research/`](research/) and indexed by
+  [`research/prior-art.md`](research/prior-art.md), so adopted patterns stay
+  auditable from the repo alone.
+
+## The model (lean) — design rationale
+
+The published doc is the lean form. The reasoning that produced it:
+
+- **A persona IS a skill.** "Take on a persona" = load the skill.
+  Framework-agnostic.
+- **A persona = tight always-on IDENTITY + advisory OWNS + PROCESSES**, each a
+  skill. References/knows fold INTO the process-skills (self-contained). No
+  tiering by default; private/inline process only when required.
+- **Identity is portable**; owns/knows resolve per deployment rig.
+- **An AGENT = a persona instantiated as a standing/addressable instance** —
+  earned only to GATE work or PATROL continuously; else transient load.
+- **Curate skills per consumer (NOT global):** a persona's process-skills ride
+  with the persona; only broadly-shared methods go top-level; a plain polecat
+  stays minimal. (Avoids skill-bloat on simple workers.)
+- **Three layers:** (1) persona = the skill; (2) distribution = a generator
+  renders the canonical persona into each framework's skill location + extracts
+  process-skills (only for >1 target); (3) Gas City orchestration =
+  persona↔bead binding, rig-relative owns/knows, the `gc.persona` stamp, and the
+  first-pass triage.
+
+## Landing decisions
+
+- **Adopted verbatim** as `docs/personas.md` (with the conventional
+  `name`/`description` frontmatter the file-structure spec asks of central
+  docs).
+- **Discoverability:** the root `README.md` "Docs" list now points at
+  `docs/personas.md`, per the file-structure adoption guidance (update the
+  discoverability surface in the same PR).
+- **Mechanics deferred.** The doc keeps a `## Mechanics (deferred)` stub. Filling
+  it is a separate follow-up that must run a latest-knowledge verification pass
+  (claude-code-guide / current Claude Code docs) covering skill load paths (flat
+  vs. nested), subagent skill consumption, persona-process scoping, and the
+  assume-persona entry point. It was deliberately NOT filled here.
+
+## Cross-cutting takeaway from the prior art
+
+The identity/owns split is validated prior art (CrewAI, MetaGPT). Treating
+"owns" as a maintained-artifact contract is novel — no surveyed system has it.
+The knows-inclusion idea is borrowable from Kiro/Cursor. And persona-adoption ==
+skill-loading is the load-bearing observation: it is *why* a persona is a skill.
+See [`research/prior-art.md`](research/prior-art.md) for the sourced surveys.

specs/tk-oe8o0/research/prior-art.md

@@ -0,0 +1,78 @@
+---
+name: Personas prior-art surveys (provenance)
+description: Provenance-stamped index of the five prior-art surveys behind the persona/agent model — the systems surveyed, what each contributed, and sources — so the patterns adopted into docs/personas.md stay auditable.
+---
+
+# Prior-art surveys — provenance
+
+Five prior-art surveys informed the persona/agent model adopted in
+[`docs/personas.md`](../../../docs/personas.md). This file is the
+**provenance-stamped index**: the systems surveyed, the pattern each
+contributed, and the sources. The full survey write-ups — produced in the
+mechanik-thread design session (2026-06-13) from primary sources — are
+persisted alongside this index as `survey-N-*.md` and linked under each
+heading below, so the adopted patterns stay auditable from the repo alone.
+
+## 1. OpenHands / OpenClaw
+
+**Full survey:** [`survey-1-openhands-openclaw.md`](survey-1-openhands-openclaw.md)
+
+OpenHands microagents and OpenClaw's `IDENTITY.md` + `SOUL.md` split, plus a
+heartbeat daemon for a standing agent.
+
+- [OpenHands docs](https://docs.openhands.dev)
+- [OpenClaw docs](https://docs.openclaw.ai)
+- [openclaw/openclaw](https://github.com/openclaw/openclaw)
+
+## 2. MetaGPT / ChatDev
+
+**Full survey:** [`survey-2-metagpt-chatdev.md`](survey-2-metagpt-chatdev.md)
+
+MetaGPT's `Role` class (SOP-as-actions, path-constants × `ProjectRepo`) and
+ChatDev's `RoleConfig` / `PhaseConfig` / `ChatChain`.
+
+- [FoundationAgents/MetaGPT](https://github.com/FoundationAgents/MetaGPT)
+- [OpenBMB/ChatDev](https://github.com/OpenBMB/ChatDev)
+
+## 3. CrewAI / AutoGen / LangGraph
+
+**Full survey:** [`survey-3-crewai-autogen-langgraph.md`](survey-3-crewai-autogen-langgraph.md)
+
+CrewAI's `Agent` (role / goal / backstory, output declared on the `Task`),
+AutoGen's `system_message` vs `description` split, and LangGraph's nodes +
+reducers.
+
+- [CrewAI docs](https://docs.crewai.com)
+- [AutoGen docs](https://microsoft.github.io/autogen)
+- [LangGraph docs](https://docs.langchain.com/langgraph)
+
+## 4. Roo Code / Cline / Cursor / Aider
+
+**Full survey:** [`survey-4-roo-cline-cursor-aider.md`](survey-4-roo-cline-cursor-aider.md)
+
+Roo Code custom modes (`fileRegex` edit-fence), Cline, Cursor inclusion modes,
+and Aider's read-only vs. editable file distinction.
+
+- [Roo Code docs](https://docs.roocode.com)
+- [Cline docs](https://docs.cline.bot)
+- [Cursor docs](https://docs.cursor.com)
+- [Aider](https://aider.chat)
+
+## 5. Claude Code / Kiro / Amazon Q
+
+**Full survey:** [`survey-5-claude-kiro-amazonq.md`](survey-5-claude-kiro-amazonq.md)
+
+Claude Code subagents + skills, Kiro steering (inclusion: always / fileMatch /
+manual), and Amazon Q resources globs.
+
+- [Claude Code docs](https://code.claude.com/docs)
+- [Kiro docs](https://kiro.dev/docs)
+- [Amazon Q docs](https://docs.aws.amazon.com)
+
+## Key cross-cutting findings
+
+- The **identity / owns split** is validated prior art (CrewAI, MetaGPT).
+- Treating **"owns" as a maintained-artifact contract** is novel — no surveyed
+  system has it.
+- **Knows-inclusion** is borrowable from Kiro / Cursor.
+- **Persona-adoption == skill-loading** — this is *why* a persona is a skill.