AMPR-165 #489: JSON frontmatter for .spark.md + role spark registry

ampere-core/src/commonMain/composeResources/files/sparks/code-agent.spark.md

@@ -1,10 +1,13 @@
----
-id: code-agent
-name: Code Agent
-whenToUse: tasks that write, read, modify, or commit code in a workspace, including code generation, refactoring, file edits, and surrounding git operations (branching, committing, pushing, opening PRs)
-phases: PERCEIVE, PLAN, EXECUTE, LEARN
-tags: code, implementation
-agentRole: Code Writer
+---json
+{
+  "type": "phase",
+  "id": "code-agent",
+  "name": "Code Agent",
+  "whenToUse": "tasks that write, read, modify, or commit code in a workspace, including code generation, refactoring, file edits, and surrounding git operations (branching, committing, pushing, opening PRs)",
+  "phases": ["PERCEIVE", "PLAN", "EXECUTE", "LEARN"],
+  "tags": ["code", "implementation"],
+  "agentRole": "Code Writer"
+}
 ---
 
 You are a Code Agent responsible for:

ampere-core/src/commonMain/composeResources/files/sparks/cooking-domain.spark.md

@@ -1,10 +1,13 @@
----
-id: cooking-domain
-name: Cooking Domain
-whenToUse: tasks that mention recipes, ingredients, meal planning, cooking techniques, or kitchen workflows
-phases: PLAN, EXECUTE
-tags: cooking, recipes, food, kitchen
-modelPreference: gpt-4o-mini
+---json
+{
+  "type": "phase",
+  "id": "cooking-domain",
+  "name": "Cooking Domain",
+  "whenToUse": "tasks that mention recipes, ingredients, meal planning, cooking techniques, or kitchen workflows",
+  "phases": ["PLAN", "EXECUTE"],
+  "tags": ["cooking", "recipes", "food", "kitchen"],
+  "modelPreference": "gpt-4o-mini"
+}
 ---
 
 ## Domain Context: Cooking

ampere-core/src/commonMain/composeResources/files/sparks/minimal-edge.spark.md

@@ -1,7 +1,10 @@
----
-id: minimal-edge
-name: Minimal Edge
-whenToUse: smoke-test fixture exercising the minimum viable declarative spark shape
+---json
+{
+  "type": "phase",
+  "id": "minimal-edge",
+  "name": "Minimal Edge",
+  "whenToUse": "smoke-test fixture exercising the minimum viable declarative spark shape"
+}
 ---
 
 ## Minimal Edge Spark

ampere-core/src/commonMain/composeResources/files/sparks/product-agent.spark.md

@@ -1,10 +1,13 @@
----
-id: product-agent
-name: Product Agent
-whenToUse: tasks that break features into actionable backlog items, triage workloads, prioritise tickets, surface blocked work, and learn from past decomposition outcomes
-phases: PERCEIVE, PLAN, EXECUTE, LEARN
-tags: product, planning, backlog, decomposition
-agentRole: Product Manager
+---json
+{
+  "type": "phase",
+  "id": "product-agent",
+  "name": "Product Agent",
+  "whenToUse": "tasks that break features into actionable backlog items, triage workloads, prioritise tickets, surface blocked work, and learn from past decomposition outcomes",
+  "phases": ["PERCEIVE", "PLAN", "EXECUTE", "LEARN"],
+  "tags": ["product", "planning", "backlog", "decomposition"],
+  "agentRole": "Product Manager"
+}
 ---
 
 You are a Product Manager Agent responsible for:

ampere-core/src/commonMain/composeResources/files/sparks/project-agent.spark.md

@@ -1,10 +1,13 @@
----
-id: project-agent
-name: Project Agent
-whenToUse: tasks that decompose a goal into a structured work breakdown, create or batch-update issues in an external tracker, assign tasks to agents, monitor epic progress, and escalate decisions that exceed an agent's authority
-phases: PERCEIVE, PLAN, EXECUTE, LEARN
-tags: project, coordination, decomposition, escalation
-agentRole: Project Manager
+---json
+{
+  "type": "phase",
+  "id": "project-agent",
+  "name": "Project Agent",
+  "whenToUse": "tasks that decompose a goal into a structured work breakdown, create or batch-update issues in an external tracker, assign tasks to agents, monitor epic progress, and escalate decisions that exceed an agent's authority",
+  "phases": ["PERCEIVE", "PLAN", "EXECUTE", "LEARN"],
+  "tags": ["project", "coordination", "decomposition", "escalation"],
+  "agentRole": "Project Manager"
+}
 ---
 
 You are a Project Manager Agent responsible for:

ampere-core/src/commonMain/composeResources/files/sparks/quality-agent.spark.md

@@ -1,10 +1,13 @@
----
-id: quality-agent
-name: Quality Agent
-whenToUse: tasks that validate code quality, surface bugs, run targeted checks (syntax, style, logic, security, performance, testing), and learn which checks pay off for which kinds of code change
-phases: PERCEIVE, PLAN, EXECUTE, LEARN
-tags: quality, qa, validation, testing, review
-agentRole: Quality Assurance
+---json
+{
+  "type": "phase",
+  "id": "quality-agent",
+  "name": "Quality Agent",
+  "whenToUse": "tasks that validate code quality, surface bugs, run targeted checks (syntax, style, logic, security, performance, testing), and learn which checks pay off for which kinds of code change",
+  "phases": ["PERCEIVE", "PLAN", "EXECUTE", "LEARN"],
+  "tags": ["quality", "qa", "validation", "testing", "review"],
+  "agentRole": "Quality Assurance"
+}
 ---
 
 You are a Quality Assurance Agent responsible for:

ampere-core/src/commonMain/composeResources/files/sparks/recipe-arc-task.spark.md

@@ -1,9 +1,12 @@
----
-id: recipe-arc-task
-name: Recipe Arc Task
-whenToUse: arc-task work that produces a multi-step recipe, meal plan, or cooking procedure as its primary artifact
-phases: PLAN
-tags: arc, recipe, planning, cooking
+---json
+{
+  "type": "phase",
+  "id": "recipe-arc-task",
+  "name": "Recipe Arc Task",
+  "whenToUse": "arc-task work that produces a multi-step recipe, meal plan, or cooking procedure as its primary artifact",
+  "phases": ["PLAN"],
+  "tags": ["arc", "recipe", "planning", "cooking"]
+}
 ---
 
 ## Arc Task: Recipe Production

ampere-core/src/commonMain/composeResources/files/sparks/role-code.spark.md

@@ -0,0 +1,68 @@
+---json
+{
+  "type": "role",
+  "id": "code",
+  "name": "Role:Code",
+  "agentRole": "Code Writer",
+  "requestedToolIds": [
+    "read_code_file",
+    "write_code_file",
+    "run_command",
+    "ask_human",
+    "search_codebase"
+  ],
+  "allowedTools": [
+    "read_code_file",
+    "write_code_file",
+    "run_command",
+    "ask_human",
+    "search_codebase"
+  ],
+  "fileAccessScope": {
+    "read": ["**/*"],
+    "write": [
+      "**/*.kt",
+      "**/*.kts",
+      "**/*.java",
+      "**/*.xml",
+      "**/*.json",
+      "**/*.yaml",
+      "**/*.yml",
+      "**/*.properties",
+      "**/*.md",
+      "**/*.txt"
+    ],
+    "forbidden": [
+      "**/build/**",
+      "**/.gradle/**",
+      "**/node_modules/**",
+      "**/.git/**",
+      "**/.env",
+      "**/.env.*",
+      "**/credentials.json",
+      "**/secrets.json",
+      "**/*.pem",
+      "**/*.key",
+      "**/id_rsa*",
+      "**/.git/config"
+    ]
+  }
+}
+---
+
+## Role: Code
+
+You are operating in a **code-focused** capacity. Your primary responsibilities are:
+
+- Reading and understanding existing code
+- Writing new code and modifying existing implementations
+- Reviewing code for correctness, style, and potential issues
+- Running commands to build, test, and verify changes
+
+### Guidelines
+
+- Follow existing code patterns and conventions in the project
+- Write clear, maintainable code with appropriate comments
+- Consider edge cases and error handling
+- Prefer small, focused changes over large refactors
+- Test changes before considering them complete

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/definition/AgentFactory.kt

@@ -204,6 +204,7 @@ class AgentFactory(
             val eventApi = eventApiFactory?.invoke(agentId)
             val memoryService = memoryServiceFactory?.invoke(agentId)
             SparkBasedAgent.Code(
+                sparkRegistry = phaseSparkLibrary,
                 agentId = agentId,
                 aiConfiguration = effectiveAiConfiguration,
                 eventApi = eventApi,
@@ -254,6 +255,7 @@ class AgentFactory(
             val eventApi = eventApiFactory?.invoke(agentId)
             val memoryService = memoryServiceFactory?.invoke(agentId)
             SparkBasedAgent.Quality(
+                sparkRegistry = phaseSparkLibrary,
                 agentId = agentId,
                 aiConfiguration = effectiveAiConfiguration,
                 eventApi = eventApi,

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/definition/SparkBasedAgent.kt

@@ -14,6 +14,7 @@ import link.socket.ampere.agents.domain.cognition.CognitiveAffinity
 import link.socket.ampere.agents.domain.cognition.sparks.PhaseSparkLibrary
 import link.socket.ampere.agents.domain.cognition.sparks.PhaseSparkManager
 import link.socket.ampere.agents.domain.cognition.sparks.RoleSpark
+import link.socket.ampere.agents.domain.cognition.sparks.SparkRegistry
 import link.socket.ampere.agents.domain.knowledge.Knowledge
 import link.socket.ampere.agents.domain.memory.AgentMemoryService
 import link.socket.ampere.agents.domain.outcome.ExecutionOutcome
@@ -307,6 +308,14 @@ open class SparkBasedAgent<S : AgentState>(
 
     companion object {
 
+        /**
+         * Canonical id of the bundled role spark fixture
+         * (`role-code.spark.md`) that supplies the Code agent's role-level
+         * guidance and capability constraints. Looked up against the
+         * [PhaseSparkLibrary] handed to the `Code` / `Quality` factories.
+         */
+        const val ROLE_CODE_SPARK_ID: String = "code"
+
         /**
          * Resource id of the bundled declarative spark that supplies the
          * Code agent's per-phase guidance. Activated during phase entry
@@ -317,29 +326,35 @@ open class SparkBasedAgent<S : AgentState>(
 
         /**
          * Builds a Code-focused [SparkBasedAgent]: `ANALYTICAL` affinity,
-         * the [RoleSpark.Code] role spark stacked at construction time,
+         * the declarative `role-code` spark stacked at construction time,
          * and the `plan_steps` tool already in its toolset.
          *
          * The factory is the supported entry point for a code agent in
          * the spark world. It mirrors the constructor shape of the
          * legacy `CodeAgent` so call sites can swap implementations
          * without restructuring their dependency graph.
          *
-         * The declarative `code-agent.spark.md` guidance is **not**
-         * applied here. That is the responsibility of the surrounding
-         * `AgentFactory` (or test harness), which wires a loaded
-         * `PhaseSparkLibrary` via the agent's internal setter before the
-         * first cognitive phase entry. Keeping the library hand-off off
-         * the factory keeps the public surface free of the spark
-         * library's internal interface while still giving the factory a
-         * one-line construction story.
+         * Since AMPR-165 the role spark is resolved from
+         * [phaseSparkLibrary] by canonical id ([ROLE_CODE_SPARK_ID])
+         * rather than referenced as a compile-time singleton. Construction
+         * fails fast if the library has no matching fixture — there is no
+         * silent fallback to the old `RoleSpark.Code` object.
+         *
+         * The declarative `code-agent.spark.md` per-phase guidance is
+         * **not** applied here. That is the responsibility of the
+         * surrounding `AgentFactory` (or test harness), which wires the
+         * same `PhaseSparkLibrary` via the agent's internal setter before
+         * the first cognitive phase entry.
          *
          * @param tools additional tools layered on top of the default
          *   `plan_steps` tool (typically a code-writing tool plus the
          *   git tool set). Tool-owned parameter strategies, if any,
          *   travel with the tools themselves.
+         * @param phaseSparkLibrary library that must contain the
+         *   `role-code` fixture; construction fails fast otherwise.
          */
         fun Code(
+            sparkRegistry: SparkRegistry,
             agentId: AgentId = generateUUID("SparkBasedAgent-Code"),
             aiConfiguration: AIConfiguration? = null,
             eventApi: AgentEventApi? = null,
@@ -349,6 +364,7 @@ open class SparkBasedAgent<S : AgentState>(
             tools: Set<Tool<*>> = emptySet(),
             reasoningOverride: AgentReasoning? = null,
         ): SparkBasedAgent<CodeState> {
+            val roleSpark = resolveCodeRoleSpark(sparkRegistry)
             val agent = SparkBasedAgent(
                 agentId = agentId,
                 cognitiveAffinity = CognitiveAffinity.ANALYTICAL,
@@ -361,10 +377,20 @@ open class SparkBasedAgent<S : AgentState>(
                 _observabilityScope = observabilityScope,
                 _reasoningOverride = reasoningOverride,
             )
-            agent.spark<SparkBasedAgent<CodeState>>(RoleSpark.Code)
+            agent.spark<SparkBasedAgent<CodeState>>(roleSpark)
             return agent
         }
 
+        private fun resolveCodeRoleSpark(registry: SparkRegistry) =
+            registry.roleSparkById(ROLE_CODE_SPARK_ID)
+                ?: error(
+                    "SparkBasedAgent factory requires the declarative role spark " +
+                        "'$ROLE_CODE_SPARK_ID' (from files/sparks/role-code.spark.md) " +
+                        "in the provided SparkRegistry, but lookup returned null. " +
+                        "Use DefaultPhaseSparkLibrary.load() so the bundled role-code " +
+                        "fixture is included.",
+                )
+
         /**
          * Resource id of the bundled declarative spark that supplies the
          * Product agent's per-phase guidance.
@@ -456,13 +482,16 @@ open class SparkBasedAgent<S : AgentState>(
 
         /**
          * Builds a Quality-focused [SparkBasedAgent]: `ANALYTICAL`
-         * affinity, [RoleSpark.Code] stacked at construction time
-         * (validation work reads & runs code), and the `plan_steps`
-         * tool already in its toolset.
+         * affinity, the declarative `role-code` spark stacked at
+         * construction time (validation work reads & runs code), and the
+         * `plan_steps` tool already in its toolset.
          *
-         * Mirrors the legacy `QualityAgent` shape.
+         * Mirrors the legacy `QualityAgent` shape. Per AMPR-165, the role
+         * spark is resolved from [phaseSparkLibrary] by canonical id;
+         * construction fails fast if it isn't present.
          */
         fun Quality(
+            sparkRegistry: SparkRegistry,
             agentId: AgentId = generateUUID("SparkBasedAgent-Quality"),
             aiConfiguration: AIConfiguration? = null,
             eventApi: AgentEventApi? = null,
@@ -472,6 +501,7 @@ open class SparkBasedAgent<S : AgentState>(
             tools: Set<Tool<*>> = emptySet(),
             reasoningOverride: AgentReasoning? = null,
         ): SparkBasedAgent<QualityState> {
+            val roleSpark = resolveCodeRoleSpark(sparkRegistry)
             val agent = SparkBasedAgent(
                 agentId = agentId,
                 cognitiveAffinity = CognitiveAffinity.ANALYTICAL,
@@ -484,7 +514,7 @@ open class SparkBasedAgent<S : AgentState>(
                 _observabilityScope = observabilityScope,
                 _reasoningOverride = reasoningOverride,
             )
-            agent.spark<SparkBasedAgent<QualityState>>(RoleSpark.Code)
+            agent.spark<SparkBasedAgent<QualityState>>(roleSpark)
             return agent
         }
     }