Refine agent orchestration and wiki workflows

AGENTS.md

@@ -4,26 +4,32 @@ The active harness session is the orchestrator. It owns the user request,
 context selection, contracts, routing, evidence, repair budget, and completion
 decision. Do not spawn or delegate the session to a child orchestrator.
 
-Use the installed `build`, `design`, `analyze`, `review`, `pr-ready`,
-`threat-model`, and `wiki` skills. Choose the smallest reliable loop:
-
-- `INLINE` for clear, low-risk, tightly bounded work;
-- `STANDARD` for coherent implementation with only the agents that add value;
-- `DEEP` for ambiguous, consequential, cross-boundary, migration, security, or
-  UI work requiring explicit contracts and independent evidence.
+Use the installed `build`, `design`, `architecture`, `grill`, `analyze`,
+`review`, `pr-ready`, `threat-model`, `wiki`, and `experiment` skills. Choose
+the smallest reliable mode:
+
+- `INLINE` only for a minimal task whose implementation context, behavioral
+  contract, and direct proof are already present before routing;
+- `LOOP` when discovery or implementation would consume substantial primary
+  context, the change spans distinct responsibilities or contracts, or fresh
+  judgment should improve correctness: one Coder by default or a few disjoint
+  Coders when safely partitioned, targeted proof, a fresh COMBINED Reviewer,
+  and bounded repair.
 
 These are adaptive playbooks, not mandatory pipelines. Do not spawn agents to
-complete a ceremony. Use `repo-scout` only for targeted unknowns. Use `coder`
-for coherent production work, `reviewer` for independent judgment,
-`test-engineer` for valuable behavioral hardening, `diagnostician` for
-ambiguous or repeated failures, `sage` for difficult decisions, and
-`security-reviewer` for material trust-boundary risk. The full profile also
-provides `browser-qa` and `ui-critic`.
+complete a ceremony. Use `architect` for repository structure and change
+boundaries, `repo-scout` only for targeted unknowns, `coder` for coherent
+production work, `reviewer` for independent judgment, `test-engineer` for
+valuable behavioral hardening, `diagnostician` for ambiguous or repeated
+failures, `sage` for difficult decisions, and `security-reviewer` for material
+trust-boundary risk. The full profile also provides `browser-qa` and
+`ui-critic`.
 
 Every agent returns `Result`, `Evidence`, and optional `Next` sections to the
 main orchestrator. Agents never dispatch their successor. The orchestrator
-checks the evidence against the live workspace and creates a fresh, bounded
-assignment for the next role. Do not forward complete transcripts.
+checks changed paths, scope, and evidence against the live workspace before
+creating a fresh, bounded assignment for the next role. Do not forward complete
+transcripts or reactivate a completed specialist.
 
 Current source, configuration, Git state, and fresh executable evidence are
 authoritative. Read `.wiki/index.md` only when repository knowledge helps, then

CLAUDE.md

@@ -4,9 +4,10 @@ Follow the repository instructions in `AGENTS.md`. The active Claude Code
 session is the main orchestrator; do not delegate the session to an
 orchestrator subagent.
 
-Use `/build`, `/design`, `/analyze`, `/review`, `/pr-ready`, `/threat-model`,
-and `/wiki`. Skills contain the reusable loops, canonical agents provide
-bounded roles, and every agent handoff returns to this main session for routing.
+Use `/build`, `/design`, `/architecture`, `/grill`, `/analyze`, `/review`,
+`/pr-ready`, `/threat-model`, `/wiki`, and `/experiment`. Skills contain the
+reusable INLINE and LOOP playbooks, canonical agents provide bounded roles, and
+every agent handoff returns to this main session for integration and routing.
 
 Edit canonical sources under `core/` and `packs/`, not generated `adapters/`.
 Run the fresh validation commands documented in `AGENTS.md` after relevant

README.md

@@ -1,4 +1,4 @@
-# Agentic Coding Kit v6
+# Agentic Coding Kit v6.3
 
 A native, development-focused workflow kit for long-horizon coding work in
 Codex, Claude Code, OpenCode, and GitHub Copilot CLI. The active harness session
@@ -13,12 +13,16 @@ names into another harness.
 
 - One host-native primary orchestrator owns the outcome; specialists never
   become nested orchestrators or dispatch successors.
-- `INLINE`, `STANDARD`, and `DEEP` are adaptive playbooks selected by risk and
-  uncertainty, not mandatory pipelines or file-count thresholds.
+- The primary chooses a direct `INLINE` route where a skill permits it, or owns
+  a delegated `LOOP`; specialists never choose the route or inherit ownership.
+- Implementation loops share only a compact `GOAL`, numbered `ACCEPTANCE`, and
+  repository-grounded `PLAN`, then use one Coder, fresh primary proof, one
+  combined Reviewer, and at most two unsuccessful repairs for the same failure.
 - Agent returns use only `Result`, `Evidence`, and optional `Next`, keeping
   handoffs compact and leaving validation with the active session.
-- Tests, independent review, browser QA, UI critique, and security review are
-  conditional evidence gates rather than ceremonial stages.
+- Extra test hardening, browser QA, UI critique, and security review are
+  conditional evidence gates rather than ceremonial stages; Build's fresh
+  combined Reviewer remains part of its loop.
 - Agents load only the exact repository wiki sections supplied to them, verify
   those claims against current source, report drift, and never edit `.wiki`.
 - Managed installation preserves explicit configuration where supported,
@@ -79,7 +83,7 @@ bash scripts/install-all.sh \
 For one harness, use `install-codex`, `install-claude`, `install-opencode`, or
 `install-copilot` with the platform's `.ps1` or `.sh` suffix.
 
-`core` installs every coding loop and all seven core agents. Use `full` only
+`core` installs every coding loop and all eight core agents. Use `full` only
 when browser execution and visual UI critique are useful.
 
 For a non-interactive install with Codex explicitly configured for unrestricted
@@ -99,63 +103,71 @@ bash scripts/install-all.sh --scope user --profile full \
   --yes
 ```
 
-`permissive` currently emits a validated Codex configuration with
-`approval_policy = "never"` and `sandbox_mode = "danger-full-access"`. Other
-harnesses retain their native permission semantics; the kit does not invent
-unsupported parity fields.
+`permissive` emits Codex `approval_policy = "never"` and
+`sandbox_mode = "danger-full-access"`, plus managed OpenCode global and
+per-agent `allow` permissions. Other harnesses retain their native permission
+semantics; the kit does not invent unsupported parity fields.
 
 An all-host install performs a complete dry-run preflight before changing any
 host. Files are then installed sequentially. Project-scope installation does
 not clear user-global harness configuration.
 
 ## What gets installed
 
-### Seven core skills
+### Ten core skills
 
 | Skill | Purpose |
 |---|---|
 | `build` | Implement features, fixes, refactors, migrations, UI, API, data, configuration, and code-linked documentation. |
-| `design` | Produce a feature, architecture, or UI design before implementation. |
+| `design` | Produce a feature, product, prototype, or UI design before implementation. |
+| `architecture` | Assess or design repository boundaries, ownership, dependencies, and maintainability. |
+| `grill` | Run an explicitly requested one-question-at-a-time decision interview. |
 | `analyze` | Read-only diagnosis, explanation, comparison, architecture, dependency, and performance analysis. |
 | `review` | Independent review of a diff, branch, contract, design, subsystem, or test delta. |
 | `pr-ready` | Repair and package a diff for efficient human PR review. |
 | `threat-model` | Read-only trust-boundary, attack-path, control, and mitigation analysis. |
 | `wiki` | Initialize, reinitialize, or audit curated repository engineering knowledge. |
+| `experiment` | Compare prompts, agents, models, algorithms, benchmarks, or harness variants under a frozen evaluation. |
 
-These are general development workflows. They are not seven mandatory stages.
+These are general development workflows. They are not ten mandatory stages.
 The orchestrator chooses the smallest useful loop and may work inline for a
 clear, low-risk change.
 
-### Adaptive coding loops
+### Primary-owned routing
 
-- `INLINE`: direct work for a clear, tightly bounded change. No ceremonial
-  agent spawning.
-- `STANDARD`: targeted implementation with proportionate checks and one
-  independent gate type at a time where it adds real value.
-- `DEEP`: explicit contract, focused discovery, independent implementation
-  review normally included, plus conditional test, UI, or security evidence.
+- `INLINE` is direct primary work for a small, clear task when the selected
+  skill supports a direct route.
+- `LOOP` keeps interpretation, exploration, planning, integration, verification,
+  and completion in the primary session. For implementation, the primary
+  prepares the compact shared `GOAL`, numbered `ACCEPTANCE`, and `PLAN`, sends
+  them unchanged to one Coder, verifies the live result, and sends the same
+  assignment to one fresh Reviewer for a combined goal-first review.
 
-Risk, uncertainty, compatibility, security, migration, and proof needs select
-the route; file counts do not. New tests and the
-Test Engineer are conditional: use them when they provide durable, observable
-evidence rather than as mandatory workflow stages.
+File count is only a hint. No agent is spawned for ceremony. A focused Repo
+Scout, Test Engineer, Architect, Diagnostician, Sage, Security Reviewer, Browser
+QA, or UI Critic is added only for a concrete discovery need, risk, or proof
+gap. Specialists receive bounded assignments, return evidence to the primary,
+and never dispatch successors.
 
 The routes and retry policy are prompt policy, not a rigid TypeScript workflow
 engine. Tested structural helpers validate selected packet, freshness, and
 repair-budget shapes, but do not automatically route agents or enforce
 handoffs/retries at model runtime. The main model decides which useful route
 comes next and when the requested outcome is sufficiently proven.
 
-Design uses `INLINE DESIGN`, `REVIEWED DESIGN`, `PROTOTYPE`, or `GRILLING`;
-grilling is explicit-only, and prototype promotion returns through Build. PR preparation uses
-`INLINE`, `STANDARD`, or `DEEP`. Threat modeling uses `FOCUSED`, `FULL`, or
-`INCREMENTAL`. Failed coder/reviewer/test repair cycles stop after two
-unsuccessful rounds and return evidence to the user.
+Design uses `INLINE DESIGN`, `DESIGN LOOP`, or `UI STUDIO`; comparative
+prototypes route through Experiment and production promotion returns through
+Build. Architecture, analysis, and PR preparation likewise choose their
+smallest supported direct or loop route. In Build, supported Reviewer blocks go
+to a repair Coder with the unchanged assignment, followed by fresh proof and a
+new full review. Two unsuccessful repairs for the same material failure stop
+the loop and return the blocker.
 
-### Seven core agents
+### Eight core agents
 
 | Agent | Responsibility | Writes |
 |---|---|---|
+| `architect` | Repository-grounded architecture and change-boundary decisions. | No |
 | `repo-scout` | Bounded repository discovery and evidence mapping. | No |
 | `coder` | Coherent production implementation and useful durable behavior evidence. | Production and tests |
 | `reviewer` | Independent code, design, and test-delta judgment. | No |
@@ -169,33 +181,58 @@ The `full` profile additionally installs:
 - `browser-qa`: browser execution and evidence capture.
 - `ui-critic`: independent visual and UX critique.
 
-All agent returns go to the main orchestrator. Assignments carry only the
-role-relevant goal, constraints, workspace context, starting paths, and proof.
-Every return uses `Result`, `Evidence`, and optional `Next`: the direct outcome,
-its decisive support, and only any remaining blocker or route. The tool call
-already correlates the response, so handoffs have no IDs, role schemas, field
-validator, or evidence-count limit. The orchestrator checks live evidence and
-creates the next assignment. Transcripts are never forwarded.
+All agent returns go to the primary. Build assignments consist only of the same
+unchanged `GOAL`, numbered `ACCEPTANCE`, and `PLAN`; concise supported repair
+evidence may accompany a repair dispatch. Agents inspect the live repository
+within their role and return only `Result`, `Evidence`, and optional `Next`.
+The primary checks the live diff, boundaries, and fresh proof before each new
+dispatch. Completed specialists are not reactivated and transcripts are not
+forwarded.
 
 ## Repository wiki
 
 `wiki init` and `wiki reinit` build an architect-grade map of how the repository
-actually works: entry points, control/data flow, module boundaries, APIs,
-authentication, IPC, integrations, jobs, error/configuration conventions,
-tests, CI, release practice, and workspace-specific differences where present.
+actually works: entry points, vertical control/data flows, module boundaries,
+APIs, integrations, branching and error conventions, code organization,
+canonical examples, tests, CI, and workspace-specific differences.
 
-The required pages are:
+Each generated wiki root has these required pages:
 
 ```text
 .wiki/index.md
 .wiki/repository-map.md
-.wiki/architecture.md
 .wiki/engineering.md
+.wiki/coding.md
+.wiki/reviewing.md
+.wiki/testing.md
+.wiki/security.md
 ```
 
-Initialization uses deterministic inventory, one Orientation Scout, one to
-three targeted evidence scans, orchestrator synthesis, independent review, and
-a parser-backed writer/audit. Normal build sessions never update the wiki.
+Initialization and reinitialization run deterministic inventory, one Orientation
+Scout, focused evidence discovery for every content page, primary synthesis,
+one fresh independent review of every draft, and at most one correction Scout.
+The primary generates the index last, then supplies the reviewed schema-v2
+synthesis to the deterministic CLI writer. Each section has a stable anchor,
+claim type, activation signals, and exact canonical source/symbol evidence;
+conventions need an authoritative source or two independent current-code
+examples.
+
+The CLI validates and hashes that evidence but does not launch agents or run the
+final audit. After every successful `init` or `reinit`, the primary separately
+runs read-only `kit wiki audit` and completes only when it passes. Audit checks
+required pages, citations, links, commands, budgets, managed boundaries, and
+canonical/generated drift. Normal work never edits `.wiki`.
+
+An existing unmarked or legacy wiki is never overwritten implicitly. Preview
+and explicitly adopt it when replacement is intended:
+
+```text
+kit wiki reinit --adopt-existing --dry-run --synthesis <reviewed-json>
+kit wiki reinit --adopt-existing --yes --synthesis <reviewed-json>
+```
+
+Adoption backs up the complete previous `.wiki` under
+`.git/agentic-kit/wiki-backups/` before installing the reviewed map.
 
 Optional PR-history learning is a two-pass operation available only during
 wiki initialization or reinitialization:
@@ -224,9 +261,12 @@ accepted, current-source-backed lessons may enter
 
 Project scope uses `.codex/agents` plus `.agents/skills`, `.claude/agents` plus
 `.claude/skills`, `.opencode/agents` plus `.opencode/skills`, and
-`.github/agents` plus `.github/skills` respectively. Codex/OpenCode/Copilot
-share one managed root `AGENTS.md` block; Claude uses one managed `CLAUDE.md`
-location.
+`.github/agents` plus `.github/skills` respectively. ACK does not write its
+primary policy into `AGENTS.md` for Codex or OpenCode. Codex receives it through
+the root `developer_instructions` setting in `config.toml`; OpenCode receives it
+only in the managed `agentic-kit` primary. Existing repository instructions
+remain host-native repository context, not ACK's orchestration channel. Claude
+and Copilot use their managed native instruction files.
 
 OpenCode additionally installs `agents/agentic-kit.md` as the managed
 `mode: primary` engineering agent. The other named agents are bounded
@@ -244,12 +284,11 @@ scope it fails safely before writing and asks you to remove one or set
 precedence may override user-scope settings; the installer does not control
 every OpenCode configuration layer.
 
-The managed primary's Markdown body is intentionally empty. OpenCode supplies
-its native provider-specific base prompt, while the kit policy is supplied once
-through the managed `AGENTS.md` block. YAML-comment ownership metadata keeps the
-empty primary manageable without duplicating the orchestrator prompt. The
-primary frontmatter grants no permissions, so applicable user/project denials
-remain inherited.
+The managed primary contains the canonical ACK orchestrator plus a very small
+OpenCode runtime note. OpenCode specialists deny skill loading and successor
+dispatch, so they receive only their role prompt and the primary's bounded
+assignment. The primary itself retains native task and skill access. Applicable
+user and project permission layers still apply.
 
 ## Influences
 
@@ -351,7 +390,7 @@ copy.
 
 ## Verification and smoke testing
 
-Repository validation:
+Local repository validation:
 
 ```powershell
 npm run typecheck --prefix cli
@@ -361,10 +400,6 @@ npm run check:drift --prefix cli
 npm run bundle --prefix cli
 ```
 
-Windows and macOS are release-blocking in CI. Both run the complete v6 suite,
-generated drift validation, bundle generation, and an all-host project launcher
-smoke test under a path containing spaces and non-ASCII text.
-
 Create a disposable behavior fixture for a fresh harness session:
 
 ```powershell
@@ -384,8 +419,8 @@ proportionate delegation, fresh tests, and avoidance of legacy memory files.
 | Path | Purpose |
 |---|---|
 | `core/` | Canonical manifest, schemas, orchestrator, agents, and skills. |
-| `packs/` | Optional UI specialists. |
-| `adapters/` | Generated host-native artifacts. |
+| `packs/` | Canonical optional specialist sources. |
+| `adapters/` | Generated host-native artifacts; edit canonical sources instead. |
 | `cli/` | Cross-platform renderer, installer, doctor, migration, wiki, and tests. |
 | `scripts/` | Thin Windows and macOS launchers. |