diff --git a/.github/agents/ai4x-ai-strategy.agent.md b/.github/agents/ai4x-ai-strategy.agent.md index 1f2b490..c933490 100644 --- a/.github/agents/ai4x-ai-strategy.agent.md +++ b/.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,8 +18,6 @@ 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) @@ -32,7 +25,6 @@ Input availability depends on which stages ran. Conditionality is governed by `a - 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) diff --git a/.github/agents/ai4x-architecture-ddd.agent.md b/.github/agents/ai4x-architecture-ddd.agent.md index cbc13dc..1145fb5 100644 --- a/.github/agents/ai4x-architecture-ddd.agent.md +++ b/.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) diff --git a/.github/agents/ai4x-capability-governance.agent.md b/.github/agents/ai4x-capability-governance.agent.md index d75b7b6..4da127f 100644 --- a/.github/agents/ai4x-capability-governance.agent.md +++ b/.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) diff --git a/.github/agents/ai4x-critical-reviewer.agent.md b/.github/agents/ai4x-critical-reviewer.agent.md index 94c48f4..f5d18e9 100644 --- a/.github/agents/ai4x-critical-reviewer.agent.md +++ b/.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. diff --git a/.github/agents/ai4x-implementation.agent.md b/.github/agents/ai4x-implementation.agent.md index ae7ac00..83f309b 100644 --- a/.github/agents/ai4x-implementation.agent.md +++ b/.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) diff --git a/.github/agents/ai4x-requirements.agent.md b/.github/agents/ai4x-requirements.agent.md index 32aed5f..04df052 100644 --- a/.github/agents/ai4x-requirements.agent.md +++ b/.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) diff --git a/.github/agents/ai4x-testing-tdd.agent.md b/.github/agents/ai4x-testing-tdd.agent.md index e153363..2e9d961 100644 --- a/.github/agents/ai4x-testing-tdd.agent.md +++ b/.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) diff --git a/.github/agents/ai4x.agent.md b/.github/agents/ai4x.agent.md index b09ea9c..699dc9a 100644 --- a/.github/agents/ai4x.agent.md +++ b/.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: `/.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) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 909877a..de42383 100644 --- a/.github/copilot-instructions.md +++ b/.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: `/.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. diff --git a/adm/pbl/ai4x-team-portability.md b/adm/pbl/ai4x-team-portability.md index 9a93ca7..4793af0 100644 --- a/adm/pbl/ai4x-team-portability.md +++ b/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 ` 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) diff --git a/adm/pbl/ai4x-usp-documentation.md b/adm/pbl/ai4x-usp-documentation.md index a1e6e93..a0161ab 100644 --- a/adm/pbl/ai4x-usp-documentation.md +++ b/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