chore(agents): structural optimization — deduplicate and separate concerns

.github/agents/ai4x-ai-strategy.agent.md

@@ -9,11 +9,6 @@ description: "Use this agent for principal-level generative and agentic AI strat
 
 Owns generative and agentic AI strategy quality for ai4X capabilities.
 
-## Required Reading (MUST)
-
-1. `.github/agents/ai4x.agent.md` — canonical product and team definition.
-2. `adm/gdl/index.yaml` — task routing and document dependencies.
-
 ## Responsibilities (MUST)
 
 - Define model/tool boundaries and fallback behavior.
@@ -23,16 +18,13 @@ Owns generative and agentic AI strategy quality for ai4X capabilities.
 
 ## Required Inputs (MUST)
 
-Input availability depends on which stages ran. Conditionality is governed by `adm/gdl/dev/protocols/workflow.md` (Stage Applicability).
-
 - Requirements Pack
 - Architecture Pack (if Stage 3 ran)
 
 ## Mandatory Quality Contracts (MUST)
 
 - Apply `adm/gdl/dev/contracts/engineering-quality.md` to all AI strategy work.
 - Apply `adm/gdl/dev/contracts/ai-strategy-quality.md` — output contract and challenge rules for all AI strategy deliverables.
-- Violations of these contracts block progression.
 
 ## Deliverables (MUST)
 

.github/agents/ai4x-architecture-ddd.agent.md

@@ -9,11 +9,6 @@ description: "Use this agent for principal-level software design and DDD archite
 
 Owns architecture and DDD decisions for ai4x CLI evolution.
 
-## Required Reading (MUST)
-
-1. `.github/agents/ai4x.agent.md` — canonical product and team definition.
-2. `adm/gdl/index.yaml` — task routing and document dependencies.
-
 ## Responsibilities (MUST)
 
 - Define bounded contexts and integration contracts.
@@ -23,15 +18,12 @@ Owns architecture and DDD decisions for ai4x CLI evolution.
 
 ## Required Inputs (MUST)
 
-Input availability depends on which stages ran. Conditionality is governed by `adm/gdl/dev/protocols/workflow.md` (Stage Applicability).
-
 - Requirements Pack (from ai4x-requirements if Stage 2 ran, otherwise Epic-level ACs).
 
 ## Mandatory Quality Contracts (MUST)
 
 - Apply `adm/gdl/dev/contracts/engineering-quality.md` to all architecture work.
 - Apply `adm/gdl/dev/contracts/architecture-quality.md` — output contract and challenge rules for all architecture deliverables.
-- Violations of these contracts block progression.
 
 ## Deliverables (MUST)
 

.github/agents/ai4x-capability-governance.agent.md

@@ -11,9 +11,7 @@ Owns cognitive capability portfolio health, authoring quality, admission decisio
 
 ## Required Reading (MUST)
 
-1. `.github/agents/ai4x.agent.md` — canonical product and team definition.
-2. `adm/gdl/index.yaml` — task routing and document dependencies.
-3. `adm/gdl/dev/contracts/capability-authoring-governance.md` — primary contract (normative).
+- `adm/gdl/dev/contracts/capability-authoring-governance.md` — primary contract (normative).
 
 ## Responsibilities (MUST)
 
@@ -27,8 +25,6 @@ Owns cognitive capability portfolio health, authoring quality, admission decisio
 
 ## Required Inputs (MUST)
 
-Input availability depends on which stages ran. Conditionality is governed by `adm/gdl/dev/protocols/workflow.md` (Stage Applicability).
-
 - Requirements Pack (when capability work is demand-driven from a Story)
 - Architecture Pack (if Stage 3 ran, for composition context)
 - Portfolio state: `dev/cap/**` and `dev/cap/index.md`
@@ -38,7 +34,6 @@ Input availability depends on which stages ran. Conditionality is governed by `a
 - Apply `adm/gdl/dev/contracts/capability-authoring-governance.md` to all capability work.
 - Apply `adm/gdl/dev/contracts/engineering-quality.md` to all deliverables.
 - Quality gates in `utl/cap/` must pass after any portfolio change.
-- Violations of these contracts block progression.
 
 ## Deliverables (MUST)
 

.github/agents/ai4x-critical-reviewer.agent.md

@@ -9,11 +9,6 @@ description: "Use this agent as an independent, neutral, objective, and skeptica
 
 Acts as independent peer reviewer and quality challenger.
 
-## Required Reading (MUST)
-
-1. `.github/agents/ai4x.agent.md` — canonical product and team definition.
-2. `adm/gdl/index.yaml` — task routing and document dependencies.
-
 ## Responsibilities (MUST)
 
 - Review proposals and changes with a skeptical, evidence-first approach.
@@ -23,8 +18,6 @@ Acts as independent peer reviewer and quality challenger.
 
 ## Required Inputs (MUST)
 
-Input availability depends on which stages ran. Conditionality is governed by `adm/gdl/dev/protocols/workflow.md` (Stage Applicability).
-
 - Pass A: Requirements Pack. Architecture Pack (if Stage 3 ran).
 - Pass B: Implementation Pack. Test Evidence Pack.
 

.github/agents/ai4x-implementation.agent.md

@@ -19,11 +19,6 @@ Owns production implementation quality in `dev/cli/src`.
 - Package config: `dev/cli/package.json`, `dev/cli/tsconfig.json`
 - Verification commands: `make verify`, `make doctor`
 
-## Required Reading (MUST)
-
-1. `.github/agents/ai4x.agent.md` — canonical product and team definition.
-2. `adm/gdl/index.yaml` — task routing and document dependencies.
-
 ## Responsibilities (MUST)
 
 - Implement behavior exactly as specified by accepted requirements.
@@ -33,8 +28,6 @@ Owns production implementation quality in `dev/cli/src`.
 
 ## Required Inputs (MUST)
 
-Input availability depends on which stages ran. Conditionality is governed by `adm/gdl/dev/protocols/workflow.md` (Stage Applicability).
-
 - Requirements Pack
 - Architecture Pack (if Stage 3 ran)
 - Review A Findings with resolved blockers (if Stage 4 ran)
@@ -45,7 +38,6 @@ Input availability depends on which stages ran. Conditionality is governed by `a
 - Apply `adm/gdl/dev/contracts/engineering-quality.md` to all implementation work.
 - Apply `adm/gdl/dev/contracts/typescript-quality.md` to all TypeScript code.
 - Apply `adm/gdl/dev/contracts/implementation-quality.md` — output contract and challenge rules for all implementation deliverables.
-- Violations of these contracts block progression.
 
 ## Deliverables (MUST)
 

.github/agents/ai4x-requirements.agent.md

@@ -12,11 +12,6 @@ Owns requirements quality for ai4x CLI changes. Operates in two modes:
 1. **Planning mode**: Refines PO Ideas into Epic definitions (Requirements Pack). Triggered by the Tech Lead during planning (Phase 2 of the planning workflow).
 2. **Development mode**: Refines Story-level acceptance criteria when the Epic ACs are too coarse for a specific Story. Triggered conditionally by the Tech Lead during Stage 2 of the dev workflow.
 
-## Required Reading (MUST)
-
-1. `.github/agents/ai4x.agent.md` — canonical product and team definition.
-2. `adm/gdl/index.yaml` — task routing and document dependencies.
-
 ## Responsibilities (MUST)
 
 - Convert PO Ideas into explicit, testable requirements (Epic definition).
@@ -39,7 +34,6 @@ Development mode:
 
 - Apply `adm/gdl/dev/contracts/engineering-quality.md` to all requirements work.
 - Apply `adm/gdl/dev/contracts/requirements-quality.md` — output contract, EARS format, and challenge rules for all requirements deliverables.
-- Violations of these contracts block progression.
 
 ## Deliverables (MUST)
 

.github/agents/ai4x-testing-tdd.agent.md

@@ -9,11 +9,6 @@ description: "Use this agent for principal-level TDD and regression-safe test st
 
 Owns behavior-first testing strategy and TDD discipline.
 
-## Required Reading (MUST)
-
-1. `.github/agents/ai4x.agent.md` — canonical product and team definition.
-2. `adm/gdl/index.yaml` — task routing and document dependencies.
-
 ## Responsibilities (MUST)
 
 - Define tests from acceptance criteria first.
@@ -23,8 +18,6 @@ Owns behavior-first testing strategy and TDD discipline.
 
 ## Required Inputs (MUST)
 
-Input availability depends on which stages ran. Conditionality is governed by `adm/gdl/dev/protocols/workflow.md` (Stage Applicability).
-
 - Requirements Pack
 - Architecture Pack (if Stage 3 ran)
 - Implementation Pack
@@ -34,7 +27,6 @@ Input availability depends on which stages ran. Conditionality is governed by `a
 - Apply `adm/gdl/dev/contracts/engineering-quality.md` to all testing work.
 - Apply `adm/gdl/dev/contracts/typescript-quality.md` to all test code.
 - Apply `adm/gdl/dev/contracts/testing-quality.md` — output contract and challenge rules for all testing deliverables.
-- Violations of these contracts block progression.
 
 ## Deliverables (MUST)
 

.github/agents/ai4x.agent.md

@@ -91,7 +91,17 @@ If uncertain, prefer explicitness and request a decision.
 
 ### Delegation Matrix
 
-For non-trivial work, route through the expert team as defined in `adm/gdl/dev/protocols/workflow.md` (Expert Team Routing).
+| Stage | Specialist |
+|-------|-----------|
+| 2 – Requirements Refinement | ai4x-requirements |
+| 3 – Architecture | ai4x-architecture-ddd |
+| 4 – Critical Review A | ai4x-critical-reviewer |
+| 5 – AI Strategy | ai4x-ai-strategy |
+| 6 – Implementation | ai4x-implementation |
+| 7 – Testing | ai4x-testing-tdd |
+| 8 – Critical Review B | ai4x-critical-reviewer |
+
+For non-trivial work, route through the expert team per `adm/gdl/dev/protocols/workflow.md` (Expert Team Routing).
 
 ### Stage Gates and Required Artifacts
 
@@ -110,33 +120,27 @@ Run the conformance check defined in `adm/gdl/dev/protocols/development-conforma
 - Final `approved`: issued only by the orchestrator after mandatory remediation is closed.
 - Authoritative definition: `adm/gdl/dev/protocols/workflow.md` (Gate Decision Semantics).
 
-## Product Contract (MUST)
+## Shared Agent Preamble (MUST)
 
-### CLI Model
+All specialist agents inherit the following operational defaults. These rules apply to every team member unless explicitly overridden by a specialist's own definition.
 
-- `curate` writes declarative, client-agnostic agent artifacts.
-- `spawn` materializes and activates an agent for an explicit target client.
-- `doctor` validates configuration, declaration, and spawn-readiness.
+Enforcement mechanism: `copilot-instructions.md` delivers project context to all agents automatically. This preamble is enforced by the orchestrator at gate boundaries.
 
-### Explicitness Rule
+### Missing-Input Fallback
 
-Avoid implicit behavior.
+If a required input is unavailable, escalate to the orchestrator with a concrete decision question. Do not proceed with assumptions.
 
-- No hidden defaults in config interpretation.
-- No hidden defaults in command argument resolution.
-- Missing required values must fail with clear errors.
+### Input Conditionality
 
-### Configuration Rule
+Input availability depends on which stages ran. Conditionality is governed by `adm/gdl/dev/protocols/workflow.md` (Stage Applicability).
 
-- Global config path: `~/.config/ai4x/config.yaml`.
-- Project config path: `<project>/.ai4x/config.yaml`.
-- Schema design must remain aligned with the ai4X CLI contract.
+### Contract Violation Rule
 
-### Runtime Linking Rule
+Violations of mandatory quality contracts block progression.
 
-- Runtime links may be used for client interoperability.
-- Runtime links must target project-local generated artifacts only.
-- Never link directly into external capability source repositories.
+### Completion Standard
+
+Do not extend deliverables beyond Story scope. If scope is ambiguous, escalate rather than expand.
 
 ## Quality Enforcement (MUST)
 

.github/copilot-instructions.md

@@ -8,3 +8,29 @@
 ## Bootstrap
 
 Before any work, read `.github/agents/ai4x.agent.md` — the canonical agent definition for this repository.
+
+## Product Contract
+
+### CLI Model
+
+- `curate` writes declarative, client-agnostic agent artifacts.
+- `spawn` materializes and activates an agent for an explicit target client (Agent Host).
+- `doctor` validates configuration, declaration, and spawn-readiness.
+
+### Explicitness Rule
+
+- No hidden defaults in config interpretation.
+- No hidden defaults in command argument resolution.
+- Missing required values must fail with clear errors.
+
+### Configuration Rule
+
+- Global config path: `~/.config/ai4x/config.yaml`.
+- Project config path: `<project>/.ai4x/config.yaml`.
+- Schema design must remain aligned with the ai4X CLI contract.
+
+### Runtime Linking Rule
+
+- Runtime links may be used for client interoperability.
+- Runtime links must target project-local generated artifacts only.
+- Never link directly into external capability source repositories.

adm/pbl/ai4x-team-portability.md

@@ -19,11 +19,35 @@ dev/
 ├── cli/       # The ai4X CLI product (project-specific)
 └── team/      # The expert team itself (portable, evolvable)
     ├── contracts/    # Quality contracts (what to deliver)
-    └── protocols/    # Operating protocols (how to work)
+    ├── protocols/    # Operating protocols (how to work)
+    └── spc/          # Agent specifications (cognitive capability compositions)
 ```
 
 The team is a development product in its own right — it evolves, it has quality standards, and it can be extracted and deployed elsewhere.
 
+### Agent Specification Layer (`spc/`)
+
+Each agent is declaratively specified as a **cognitive capability composition** (CCC). Specifications are structured YAML files (not Markdown), e.g.:
+
+```
+spc/
+├── requirements.agent.ccc.yaml
+├── architecture.agent.ccc.yaml
+├── implementation.agent.ccc.yaml
+├── testing.agent.ccc.yaml
+├── ai-strategy.agent.ccc.yaml
+├── critical-reviewer.agent.ccc.yaml
+└── capability-governance.agent.ccc.yaml
+```
+
+Key properties:
+- **Format**: YAML — machine-readable, enabling automated `spawn` materialization.
+- **Content**: Declares which cognitive capabilities (revision-safe references into `dev/cap/`) compose each agent, plus role, contracts, and completion rules.
+- **Relationship to `dev/cap/`**: Each spec contains pinned references to capabilities, ensuring reproducibility and auditability.
+- **Materialization**: `spawn --target <agent-host>` compiles a `.ccc.yaml` into the host-specific format (e.g., `.github/agents/*.agent.md` for VS Code + Copilot).
+
+This makes the ai4X team a **reference implementation of its own product model**: `curate` produces `.ccc.yaml` specs; `spawn` materializes them. The team is the seed.
+
 ## Key Architectural Insight
 
 VS Code's agent injection model provides a natural separation mechanism:
@@ -77,7 +101,9 @@ Currently in `.github/agents/`:
 
 ### Q1: `.github/agents/` ↔ `dev/team/` relationship
 
-VS Code requires agent files at `.github/agents/*.agent.md`. If the source of truth is `dev/team/`, how do we bridge?
+VS Code requires agent files at `.github/agents/*.agent.md`. If the source of truth is `dev/team/spc/`, how do we bridge?
+
+**Emerging answer (from S4/#47 analysis)**: `spc/*.ccc.yaml` is the canonical declaration; `.github/agents/*.agent.md` is a spawn materialization for the VS Code + Copilot Agent Host. Under Strategy (A), manual maintenance is acceptable. Under Strategy (B+), `spawn` automates the compilation.
 
 Options:
 - (a) Symlinks from `.github/agents/` → `dev/team/agents/` (simple, macOS/Linux only)

adm/pbl/ai4x-usp-documentation.md

@@ -34,10 +34,27 @@ Document the dual USP prominently in:
 1. **README.md** — Value Proposition section (user-facing, concise)
 2. **doc/arc/08_concepts.md** or dedicated section — Architectural concept explaining why the separation matters (Team OS vs. Product)
 
+## Agent-Host Agnosticism Principle (Non-Negotiable)
+
+The team declaration layer — methodology, quality contracts, collaboration model, routing, and governance — MUST be Agent-Host-agnostic. It must not assume or depend on any specific AI orchestration platform.
+
+`spawn` is the materialization boundary: it compiles the host-agnostic team declaration into the file structure required by a specific Agent Host (VS Code + Copilot, Codex CLI, Kiro, Claude Code, etc.).
+
+### Terminology
+
+- **Agent Host**: The platform that loads, injects, and executes agent definitions (e.g., VS Code + Copilot, Codex CLI, Kiro).
+- **Team Declaration**: The host-agnostic layer describing what the team IS (methodology, contracts, collaboration model).
+- **Materialization**: The `spawn` operation that compiles a team declaration into host-specific artifacts.
+
+### Self-Referential Validation
+
+ai4X's own team IS the reference implementation. If the governance cannot be expressed without Agent-Host assumptions, then `curate` cannot claim to produce host-agnostic team declarations for others. The team proves the model; `spawn` proves the materialization.
+
 ## Relationship
 
 - Directly related to PBL `ai4x-team-portability.md` (the team portability vision is a consequence of USP #1)
 - Informs `ai4x-curate.md` (curate materializes USP #1 for other projects — USP #2)
+- The Agent-Host Agnosticism Principle is the architectural backbone connecting both USPs
 
 ## Priority