Aep Map

Map

Decompose the Context Document into a system map (modules + interfaces), a layered story graph (work items + dependencies + execution slices), and an agent topology (roles + handoff contracts). This is the hardest phase — a wrong module boundary means dozens of agents produce incompatible code.

Where this fits:

/aep-envision → /aep-map → /aep-scaffold → [ /aep-design → /aep-launch → /aep-build → /aep-wrap ] → /aep-reflect
             ▲ you are here

Session: Main, interactive with user (System Map requires human review) Input: Product definition from product/index.yaml (split mode) or product-context.yaml (v1 mode) Output: product-context.yaml updated with architecture, stories, waves, topology, layer_gates, cost, and changelog sections

YAML Schema: See templates/product-context-schema.yaml for the full structure and field definitions.

---

Before Starting

File Resolution:

ls product/index.yaml 2>/dev/null && echo "SPLIT MODE" || echo "V1 MODE"
cat product-context.yaml

• Split mode (product/index.yaml exists): Read product definition (opportunity, personas, product.\*) from product/index.yaml. Read operational state from product-context.yaml.
• V1 mode: Read everything from product-context.yaml.

If product definition is missing (no product section in either file), run /aep-envision first.

---

Step 1: System Map (Single Agent + Human Review)

Produce a System Map (see templates/system-map.md) from the Context Document:

• Modules: Major components with clear responsibility boundaries. Each module's "does not" definition is as important as its "does" definition. Set each module's kind (ui | backend | shared) — ui modules render user-facing surfaces, which drives the UI-facing story trigger used by /aep-model, dispatch, and launch.
• Interface contracts: For every module-to-module connection, define the exact API surface — endpoints, data shapes, error contracts. These are not documentation; they are executable specifications enforced by contract tests.
• Data flow: How information moves through the system for each user journey in the MVP contract.
• Third-party boundaries: External service integration points with failure modes.

Write the system map to the architecture section of product-context.yaml.

When to Produce a Technical Specification

If the System Map reveals any of these conditions, suggest producing a Technical Specification (see templates/technical-spec.md) before proceeding to story decomposition:

• 3+ interface contracts require multi-step protocol sequences
• The system has 2+ distinct state machines
• There are explicit failure classes with different recovery behaviors
• Trust boundaries cross module lines

The System Map defines WHAT the modules are and HOW they connect. The Technical Spec defines HOW those connections behave under all conditions (success, failure, timeout, recovery). Write the Technical Spec as a standalone document and reference it from the architecture section:

architecture:
  technical_spec: "docs/technical-spec.md"

See templates/references/symphony-spec-reference.md for the exemplar standard.

Human Review Gate

The user must review and approve the System Map. Architecture decisions have the highest error cost in the entire pipeline. Present the map and explicitly ask for approval before proceeding to story decomposition.

If the user wants changes, revise and re-present. Do not proceed until approved.

---

Step 2: Story Decomposition (Parallel Agents)

Once the System Map is confirmed, decompose into stories:

• One Decomposition Agent per module: Receives Context Document + System Map + its module definition. Produces stories tagged with layer (0 = walking skeleton, 1+ = enrichment layers).
• One Integration Story Agent: Looks at module connections in the System Map. Produces stories that glue modules together — the end-to-end flows crossing module boundaries. These are especially critical at Layer 0.

Each story follows the Story Spec format (see templates/story-spec.md) and must include:

• What changes when complete (observable behavior)
• Acceptance criteria automatable as tests
• Layer assignment (0 = walking skeleton, 1+ = enrichment)
• Module assignment
• Dependency declarations
• Interface obligations (if touching module boundaries)
• Files likely affected (for conflict detection)
• business_value (1-10, or null to derive from priority)
• compile_mode (default single_change; use grouped_change for tightly coupled stories, shared_enabler for infrastructure)

All stories start with `status: pending`. Stories follow a state machine: pending → ready → in_progress → in_review → completed (or blocked / failed as error states). The /aep-dispatch skill manages state transitions during execution.

Activity Mapping

After decomposition agents produce their stories, map each story to a user activity from product.activities (and, in split mode, set story.capability to the owning capabilities[] id — this is how dispatch/launch later locate the story's Object Map; leave null in v1/single-journey, where the default capability is the project slug):

• Stories that directly enable a user-facing capability get the activity they serve (e.g., "Create presigned upload URL" → create-profile because it enables the user to upload a selfie).
• Infrastructure/foundation stories that don't map to any specific user activity leave `activity` as null. These are implementation enablers — they appear in the architecture view but NOT in the user journey story map. This is correct and expected.
• Integration stories use the primary user activity they validate end-to-end.

Not every story needs an activity. The story map shows the user's perspective — technical plumbing is visible in the architecture view.

Walking Skeleton (Layer 0)

Layer 0 is the most important layer. It is a horizontal slice across the activity backbone — the thinnest story from each user activity, strung together so a user can complete the crudest possible end-to-end journey from the Context Document's Layer 0 MVP Contract.

"Build a skeleton that can walk before building a perfect leg."

Every activity in product.activities with layer_introduced: 0 should have at least one Layer 0 story. Do not go deep into any module before proving the end-to-end path works. This is the most expensive mistake in this workflow.

---

Step 3: Dependency Resolution & Waves (Single Agent)

A dedicated agent receives all stories and produces:

• Story Graph: A directed acyclic graph organized by layer, showing dependencies and parallelism opportunities.
• Waves (Execution Slices): Within each layer, group stories into waves that can be dispatched as a batch. A wave is a set of stories with no mutual dependencies that can run fully in parallel. (The YAML field is stories[].slice; the user-facing term is "wave.")
• Critical path per layer: The longest dependency chain, determining minimum time to complete that layer.
• Layer gates: The integration test definition that must pass before advancing to the next layer.

Write all stories to the stories section of product-context.yaml. Also populate the waves section grouping stories by layer + wave.

Outcome Contracts

For each layer that has an outcome_contract defined (see product.layers[].outcome_contract), ensure the layer gate test definition aligns with the success metric. If no outcome contract exists for a layer, consider adding one — Jeff Patton emphasizes that layers should be anchored in outcomes, not just feature completeness.

The outcome contract is evaluated by /aep-reflect after layer completion. It answers: "did this layer achieve what we hypothesized?"

Telemetry Binding (observability)

This is where the project decides its telemetry sources — metric-driven, then inventory (see the coverage rule in references/telemetry-ingestion.md §1.5).

1. Collect the needed signals: every quantitative success_metric (type ∈ task_completion_rate | time_to_complete | error_rate | satisfaction_score) across the layers, plus any topology.routing.post_merge_guard.health_signals you intend to monitor. That set is the demand for telemetry. 2. Bind each to a source: start from the candidate `telemetry_sources` detected by /aep-scaffold's audit (or ask the user which tool provides each — Sentry / Datadog / PostHog / analytics / health endpoint). For each needed signal add a metric_map: { <metric-or-signal>: "<query>" } entry on the matching source, and fill its endpoint + token_env (name only — never the secret). 3. Flag the unmeasurable: a quantitative success_metric with no source either becomes qualitative (it will pause for human judgment in /aep-reflect) or is recorded unmeasured — never leave a quantitative metric silently un-sourced.

Write the result to topology.routing.telemetry_sources (+ health_signals). /aep-reflect, /aep-watch, and /aep-autopilot run coverage_check() against this before trusting any auto path; an incomplete binding blocks auto, it does not silently no-op.

Capability Maps (multi-journey products)

If product/index.yaml exists (created by /aep-envision for multi-journey products), also write per-capability map.yaml files:

• product/maps/<capability>/map.yaml — backbone activities, layers, story stubs for this capability
• Story stubs in map.yaml are sketches; the full stories in product-context.yaml are the operational versions

Split mode note: In split mode, the capability map's map.yaml story stubs are narrative sketches. The full stories are written to product-context.yaml, and product/index.yaml is NOT modified by /aep-map (it only reads from it).

• This is additive — if no capability maps exist, skip this step

Alignment Layers (.5 Layers)

After defining each implementation layer, review calibration.plan from product-context.yaml (operational file, both modes) (if populated by /aep-envision) or consider which quality dimensions may need human calibration:

• UI-facing stories → consider visual-design and/or copy-tone calibration
• New API endpoints → consider api-surface calibration
• New domain entities → consider data-model calibration
• First user-testable layer → consider scope-direction calibration

For heavy dimensions (visual-design, ux-flow, copy-tone): plan a .5 alignment layer with stories tagged calibration_type: <dimension>. Run /aep-calibrate <dimension> before dispatching to generate a brief and capture decisions into calibration/<type>.yaml.

For light dimensions (api-surface, data-model, scope-direction, performance-quality): plan a /aep-calibrate <dimension> checkpoint BEFORE dispatching the relevant stories in the next integer layer. No .5 layer needed — decisions update product-context.yaml directly.

• Layer 0.5 (first .5 layer): Typically establishes the visual design system. Run /aep-calibrate visual-design to create calibration/visual-design.yaml.
• Layer 1.5, 2.5 (subsequent .5 layers): Extend calibration to new patterns. /aep-calibrate detects existing calibration artifacts and generates focused briefs covering only the delta.
• Opt-in, not automatic. The /aep-reflect step after each layer classifies calibration needs by dimension. The human decides which dimensions need attention. But the workflow makes the question unavoidable.

Object Map feeds the heavy UI dimensions. Once /aep-model has approved an

Object Map for a capability, the visual-design and ux-flow .5-layer briefs

derive their "pages/screens to design" from the Object Map's screen plan

(product/maps/<cap>/object-map.yaml → screens) instead of an ad-hoc routes/

scan. Structure first (object-model), then taste (visual-design) and journey

(ux-flow).

Object Map Drafts (UI-facing capabilities)

After stories are decomposed, produce a draft noun-first Object Map for each UI-facing capability (a capability that declared the object-model quality dimension, or visual-design/ux-flow, or has user-facing stories). This is the bridge from the verb-first story map to the UI — it stops build agents from inventing one-step-one-screen task-wizard UIs.

Mine the draft with the ORCA rounds (Objects → Relationships → CTAs → Attributes → screens) from product.activities, stories[].description, and architecture.domain_model. See the /aep-model skill and its references/orca-process.md for the derivation, and templates/object-model-schema.yaml + templates/object-map-schema.yaml for the structure. Write:

• product/object-model.yaml — cross-capability object ontology (provenance.reviewed: false)
• product/maps/<capability>/object-map.yaml — per UI-facing capability, `status: draft`

Use the capabilities[] ids for the <capability> path segment. In v1 / single-journey products (no capabilities[]), use a single default capability = the project slug (product: / project: in the YAML) and set every UI story's coverage entry under that one map.

These are drafts only — do not mark them approved. Object boundaries and IA are high-impact design decisions; /aep-model presents the draft for a short human review gate and flips status: approved. Dispatch/launch refuse UI-facing stories without an approved Object Map.

Re-runs invalidate approval. If a later /aep-map run re-decomposes stories or activities under a capability whose object-map is already approved, flip that map's status: stale (and provenance.reviewed: false on the shared object-model.yaml if its objects changed). The dispatch/launch gates treat stale like draft — they abort until /aep-model re-approves the delta.

If a project is pure-backend/CLI (no UI-facing capability), skip this step.

Feedback Loop

Decomposition agents may discover module boundaries are wrong. They submit amendment proposals to the System Map. When amendments accumulate to 3+ items or any single amendment affects an interface contract, trigger an Architecture Review with the user before continuing.

---

Step 4: Agent Topology Design

Why this lives here: Per Anthropic's research, "each subagent needs an objective, an output format, guidance on tools and sources, and clear task boundaries — defined before execution." Topology is a decomposition decision — it determines how /aep-launch configures workspaces and what context /aep-build agents receive.

Define the agent roles, handoff contracts, and routing rules using the Agent Topology template (see templates/agent-topology.md):

Agent Role Definition

For each role in the execution pipeline, define:

• Role name: What this agent type is called (e.g., implementer, contract-verifier, integration-tester)
• Responsibility boundary: What this agent does and does not do. Single-responsibility is the rule.
• Input contract: The exact structure of the work object this agent receives. Schema-defined, not free text.
• Output contract: The exact structure of the artifact this agent produces. Schema-defined.
• Context window composition: What goes into this agent's context — which sections of the Context Document, which parts of the System Map, what dependency artifacts. Irrelevant context degrades performance.
• Cost budget: Expected token usage and time per invocation.

Handoff Contracts

For every agent-to-agent transition:

• Trigger: What event causes the handoff
• Payload: What artifact is passed, in what schema
• Validation: What checks run on the payload before the receiving agent starts

Routing Rules

• Dispatch policy: How stories are assigned from the ready queue
• Concurrency limit: Maximum parallel agents (start conservative: 5-10)
• Conflict detection: Stories modifying the same files must not run in parallel
• Retry routing: Same agent retry (2x) → fresh agent with failure log (1x) → human escalation

Write the topology to the topology section of product-context.yaml. Also initialize the layer_gates and cost sections.

---

Output

Before Committing: Validate YAML

See references/yaml-guardrails.md for the full checklist. Run:

npx js-yaml product-context.yaml > /dev/null && echo "YAML OK"

If this fails, fix the YAML before committing. Common fixes: quote list items containing colons, flatten nested sub-lists, escape embedded double quotes.

Commit

# Resolve $BASE (integration branch) — see git-ref "Integration Branch" (override → develop → main)
BASE=$(git config --get aep.integration-branch 2>/dev/null || true)
[ -z "$BASE" ] && { git show-ref --verify --quiet refs/heads/develop \
  || git show-ref --verify --quiet refs/remotes/origin/develop; } && BASE=develop
BASE=${BASE:-main}

git pull --ff-only origin "$BASE"
git add product-context.yaml product/
git commit -m "feat: add system map, story graph, and agent topology"
git push origin "$BASE"

Sections written:

• architecture — system map (modules, interfaces, data flow)
• stories — layered story graph with waves (all stories start status: pending)
• waves — stories grouped by layer + wave for batch dispatch
• topology — agent roles, handoff contracts, routing rules
• layer_gates — integration test definitions per layer (aligned with outcome contracts if defined)
• cost — initial cost budgets and tracking structure
• changelog — append an entry recording what was added

Always append to the changelog section.

---

For Iteration

When updating the map (triggered by /aep-reflect or new requirements):

1. Read the existing product definition (product/index.yaml in split mode, product-context.yaml in v1 mode) and operational state from product-context.yaml 2. Identify what's changed — new modules, revised interfaces, new stories 3. Update affected sections (architecture, stories, topology) 4. If interface contracts changed → re-verify dependent stories 5. Append to the changelog section 6. Commit updated version

---

Anti-Patterns

• Do not use more agents to mask unclear decomposition. If stories are vague or overlapping, adding agents amplifies confusion. Fix the decomposition first.
• Do not skip the walking skeleton. Going deep into one module before proving the end-to-end path works is the most expensive mistake in this workflow.
• Do not allow free-text handoffs. Every agent-to-agent communication must be schema-defined. Ambiguity compounds exponentially across parallel agents.

---

Next Step

Decomposition is complete. If no project exists yet:

/aep-scaffold

If the project has UI-facing capabilities, approve the Object Map drafts before dispatching UI stories:

/aep-model

/aep-model presents the draft Object Map for a short human review gate and flips it to approved. Then start executing stories:

/aep-dispatch

/aep-dispatch reads the story graph from product-context.yaml and begins moving stories through the state machine (pending → ready → in_progress → ...), routing each through /aep-design → /aep-launch → /aep-build → /aep-wrap. For UI-facing stories it injects the approved Object Map slice and refuses to dispatch if no approved Object Map exists.

Orchestration Patterns

Detailed patterns for the control plane's orchestrator — state management, context assembly, layer gating, and failure handling. Read this when setting up or debugging the execution pipeline.

---

Work Graph as State Machine

The work graph is a live state machine. Every story node holds a status and transitions based on events.

State Transitions

pending     → ready        (all dependency stories reach 'completed')
ready       → in_progress  (orchestrator dispatches to agent)
in_progress → in_review    (agent submits PR)
in_review   → completed    (verification passes)
in_review   → in_progress  (verification fails, retry initiated)
in_progress → failed       (retry limit exceeded, escalated)
pending     → blocked      (a dependency story enters 'failed')
any         → deferred     (user explicitly postpones)

Orchestrator Loop

The orchestrator is event-driven, not polling-based:

1. Event received (story completed, PR submitted, verification result, failure). 2. Update state of the affected story in the work graph. 3. Cascade check: Does this transition unlock new stories? (completed → check dependents). Does it block stories? (failed → mark dependents as blocked). 4. Dispatch: For each newly ready story, run conflict detection, assemble context, dispatch to agent per routing rules. 5. Layer check: Are all stories in the current layer completed? If yes, trigger Integration Gate. 6. Alert check: Any cost anomalies? Any critical path blockages? Notify user if needed.

Concurrency Control

• Maximum parallel agents is configurable. Start with 5–10.
• Two stories with overlapping "Files Likely Affected" must not run in parallel — serialize them.
• If two parallel stories produce merge conflicts, the later PR rebases on the merged one and re-verifies.

---

Context Assembly

The Problem Context Assembly Solves

An agent's output quality is directly proportional to the relevance and precision of its input context. Too little context → the agent guesses. Too much context → the agent gets confused or hits token limits. Context assembly is the art of giving each agent exactly what it needs and nothing more.

Assembly Rules

For each agent role, the Agent Topology document defines a context window composition — the ordered list of what goes in. The orchestrator follows this list mechanically:

1. Read the composition spec for the target agent role. 2. Prune the Context Document to the sections listed in the spec. 3. Extract the relevant System Map slice — the story's module and its adjacent interfaces only. Do not include unrelated modules. 4. Collect dependency artifacts — for each completed dependency, extract the public interface (types, exports, API surface). Do not include internal implementation unless the composition spec explicitly requires it. 5. Validate the package — all required fields present, no references to missing artifacts. 6. Measure the package — if it exceeds the target token budget for the role, escalate for manual pruning or split the story.

Common Assembly Failures

• Missing dependency artifact: A dependency is marked completed but its output artifact is not found. This usually means the previous agent's output contract was not enforced. Fix: add post-completion validation in the handoff contract.
• Stale interface contract: The System Map was amended but the context package still references the old version. Fix: always read interface contracts from the latest System Map, not from cached copies.
• Context overflow: The assembled package exceeds the agent's token budget. Fix: either prune more aggressively (summarize dependency artifacts instead of including full source) or split the story into smaller units.

---

Layer Gating

Gate Design

Each layer has an Integration Gate — tests that verify stories work together. The gate is NOT the sum of individual story tests. It tests emergent behavior at integration boundaries.

Layer 0 gate is the most important test in the pipeline. It executes the exact user journey from the Context Document's Layer 0 MVP Contract. If the walking skeleton doesn't work end-to-end, something is architecturally wrong.

Subsequent layer gates test:

1. All previous layer journeys still work (regression). 2. New capabilities added in this layer work end-to-end. 3. Interface contracts honored under realistic conditions (not just mocks).

Gate Failure Protocol

Gate fails
  → Identify failure boundary (which module interface)
  → Check: implementation vs contract mismatch?
     → Implementation wrong: create fix story → Phase 4
     → Contract wrong: trigger Architecture Review → Phase 2
        → Assess impact on completed stories
        → May require re-execution of affected stories

Gate failure on a contract issue is the most expensive failure in the pipeline because it can invalidate already-completed work. This is why Phase 2 (System Map approval) is a human-reviewed gate — catching contract errors early prevents cascading rework.

---

Failure Handling

Why Fresh-Agent Retry Works

When an agent fails and retries, it carries the full reasoning trajectory from its first attempt. If that trajectory led to a dead end, the retry often follows the same path — the agent is stuck in its own logic. A fresh agent receives only the structured failure log, not the reasoning. It approaches the problem without the stuck trajectory.

The failure log's "what was NOT tried" field is the highest-value signal for the fresh agent. It provides starting points the previous agent considered but did not explore.

Failure Log Schema

{
  story_id: string,
  attempt_number: number,
  agent_role: string,

  approach_summary: string,     // What the agent tried to do
  failure_point: string,        // Which verification step failed
  error_output: string,         // Exact error messages or test failures
  hypothesis: string,           // Agent's best guess about root cause
  not_tried: string[],          // Alternative approaches considered but not attempted

  context_issues?: string,      // Any problems with the context package
  time_spent_seconds: number,
  tokens_used: number
}

Cascade Prevention

When a story fails:

1. Mark direct dependents as blocked. 2. Continue executing non-blocked stories in the same layer. 3. If the failed story is on the critical path → alert user immediately (entire layer is blocked). 4. If NOT on critical path → other work continues. User addresses failure asynchronously. 5. When the failed story is eventually resolved (fixed or deferred), unblock dependents and resume normal dispatch.

Escalation Format

When a story reaches human escalation, present:

1. The story spec (what was being attempted). 2. All failure logs from all attempts (what happened). 3. The fresh agent's failure log specifically (the most informed analysis). 4. Current impact: which stories are blocked, is this on the critical path? 5. Suggested options: fix the story, simplify the story, defer it, or modify the architecture.

---

State Persistence

The orchestrator's state must survive crashes.

Storage Options

• File-based (JSON in repo): Simple, version-controlled. Sufficient for most MVP projects. Limitation: does not support concurrent orchestrators.
• SQLite: Supports querying ("show all failed stories") and concurrent access. Better for larger projects.
• External store (Redis, Postgres): For production-grade orchestration with multiple concurrent sessions.

For MVP-stage projects, start with JSON in the repo. Upgrade when the limitation matters.

State Snapshot Schema

{
  project_id: string,
  current_layer: number,
  stories: {
    [story_id]: {
      status: "pending" | "ready" | "in_progress" | "in_review" | "completed" | "failed" | "blocked" | "deferred",
      assigned_agent?: string,
      attempt_count: number,
      last_updated: ISO8601,
      failure_logs?: FailureLog[],
      pr_url?: string,
      completed_at?: ISO8601
    }
  },
  layer_gates: {
    [layer_number]: {
      status: "not_started" | "running" | "passed" | "failed",
      test_results?: TestResult[],
      completed_at?: ISO8601
    }
  },
  cost_summary: {
    total_cost_usd: number,
    cost_by_layer: { [layer]: number },
    cost_by_role: { [role]: number },
    cost_by_story: { [story_id]: number }
  },
  last_updated: ISO8601
}

State Inspection

The user should be able to query the current state at any time:

• Progress per layer: completed / in_progress / pending / failed / blocked
• Critical path status: what is the next bottleneck?
• Cost breakdown: where is the money going?
• Blocked stories: what is waiting on what?

Provide a simple CLI command or dashboard that reads the state file and renders this overview.

Telemetry Ingestion & Outcome Auto-Evaluation

How /aep-reflect (and /aep-watch) pull real-world signals automatically, and how a layer's quantitative outcome contract is evaluated without a human. This augments the interactive reflect flow — it never replaces human review by default. (Gap G5.)

Authoring note: this file is canonical in

skills/product-context/_shared/references/; scripts/build-skills.sh

materializes it into each consuming skill's references/.

---

1. Automated source ingestion

Pull from read-only sources with bash/curl/jq and reduce each to the normalized observation record the reflect Step 2 classifier consumes:

{
  "source": "error_stream | analytics | monitoring | bug_tracker | dogfood",
  "signal": "one-line description of what was observed",
  "evidence": "url | query | sample (no secrets)",
  "story_ref": "<story-id if attributable, else null>",
  "suggested_class": "bug | refinement | discovery | opportunity_shift | process | null"
}

suggested_class is a hint only — the reflect Step 2 classifier (and the human, unless full_auto) makes the final call. Ingested records are merged with interactive input before classification; automation augments, never replaces.

Source config

Endpoints live under topology.routing.telemetry_sources (a list). Each entry:

telemetry_sources:
  - kind: error_stream # error_stream | analytics | monitoring | bug_tracker
    endpoint: "https://…/api/…?since={since}" # {since} = last-ingest high-water mark
    token_env: SENTRY_TOKEN # NAME of an env var / secret — never the secret itself
    metric_map: # for analytics/monitoring: outcome-metric name → query
      activation_rate: "SELECT … "

Safety: access is read-only; reference credentials by env-var / secret-store name only — never embed secrets in the repo or in `product-context.yaml`.

Dogfood-report adapter (dogfood_report source)

Dogfood runs — local (/aep-build Phase 6), post-deploy (autopilot post-merge guard), or a standalone / ad-hoc live exercise — emit the unified markdown report (## <title> / **Severity:** / **Category:** / **Repro:** / **Observed:** / **Expected:** / **Evidence:**) to .dev-workflow/dogfood-*.md (see patterns/executor/references/dogfood-validation.md → Unified report format). This adapter parses each ## finding into the `/aep-watch` Step 1 finding record (the operative shape Step 3 dedupes and Step 4 turns into a story — _not_ the 5-field telemetry record above, which is the classifier's conceptual input) so the same Step 2 classifier consumes it — closing the G6 self-feeding loop for every dogfood trigger, not just the guard path. It is a file glob, not a network source: self-describing, so coverage_check (§1.5) does not gate it.

Source config (the discriminator key matches the container: type: under watch.sources[], kind: under telemetry_sources[]):

watch:
  sources:
    - type: dogfood_report
      glob: ".dev-workflow/dogfood-*.md" # default; add post-deploy report paths as needed

Per-finding mapping (markdown field → finding field):

suggested_class is a hint only — the Step 2 classifier (and the human, unless full_auto) makes the final call, exactly as for every other source. In particular a finding that reads as calibration / discovery / opportunity-shift / process is not auto-filed; it surfaces to a human (see /aep-watch Step 2).

No high-water mark — dedupe-only. The unified report has no per-finding timestamp, so a dogfood_report source does not advance watch.since (that cursor applies only to time-ordered sources); re-scanning the glob each tick is harmless because idempotency rests entirely on the stable dedupe key. Each finding gets a deterministic external_id = "dogfood:" + slug(report-basename) + ":" + shorthash(slug(title) + "|" + category), so /aep-watch Step 3 dedupes on watch_origin.{source,external_id}: already-filed findings no-op, and a genuinely new finding (new title/category) yields a new id and a new story. The autopilot post-merge guard Path 1 stamps the same external_id on the story it files, so whichever path ingests a given report first wins and the other no-ops — no double-filing.

---

1.5 Deciding which sources to wire (the coverage rule)

You don't list telemetry for its own sake — a source is needed _iff_ some declared signal requires it. The decision is hybrid:

1. Metric-driven (what signals do we need?) — enumerate every quantitative success_metric across product.layers[].outcome_contract plus every topology.routing.post_merge_guard.health_signals entry. That set _is_ the demand for telemetry. 2. Inventory (which tool provides each?) — /aep-scaffold's audit detects the project's observability stack (Sentry, Datadog, PostHog, OpenTelemetry, log drains, /healthz-style endpoints) and records candidate telemetry_sources (kind + endpoint + token_env, no metric_map yet); you can also add candidates by hand. 3. Bind (`/aep-map`) — for each needed signal, attach it to a candidate source by adding a metric_map: { <metric-or-signal>: "<query>" } entry. A needed signal with no measurable source is flagged, not ignored: make the metric qualitative, or record it unmeasured — never leave a quantitative metric silently un-sourced.

coverage_check(needed) — the guard helper

Consumers that rely on telemetry (/aep-watch, /aep-reflect Step 2.75, /aep-autopilot) call this before trusting auto behavior. It is pure config inspection — no network:

coverage_check(needed_signals):
  missing = []
  for sig in needed_signals:           # quantitative success_metric names + health_signals
    if no telemetry_sources[*].metric_map has key == sig
       (and, for a health_signal, no source/endpoint provides it):
      missing.append(sig)
  return { covered: missing == [], missing }

On `covered == false`: surface "telemetry binding incomplete for <missing> — run /aep-map (observability step)" and block the auto path (watch refuses to claim auto-coverage; reflect falls back to the human pause; autopilot pauses). Missing wiring must block auto, never silently no-op — that's the v2 human-in-the-loop default.

---

2. Outcome-contract auto-evaluation

A layer's outcome_contract carries a success_metric (type + target) and a decision_rule (keep_if / otherwise). Precondition: run coverage_check([success_metric]) (§1.5) first — if the metric isn't bound to a source, take the human-pause path (the binding is incomplete; do not auto-eval). When covered, evaluate per topology.routing.auto_outcome_eval:

On a fetch failure or ambiguity, fall back to the human pause (fail safe, not fail open). Record every auto-evaluation in the changelog:

- date: YYYY-MM-DD
  type: outcome_evaluation
  summary: "Layer N: <metric> = <actual> vs target <target> → passed|failed (auto)"

---

3. full_auto interaction (A1)

topology.routing.full_auto (default false) is the master switch. It only changes the qualitative path:

Default keeps humans in the loop; only an explicit full_auto: true removes the qualitative pause.

---

Cross-references

• /aep-reflect Step 1 (Gather Feedback) and Step 2.75 (Evaluate Outcome Contracts)
• /aep-watch (reuses the normalized observation record for its ingest step)
• aep-autopilot references/tick-protocol.md — Step ⑥ Layer Completion (what the

auto-eval lets advance without a pause)

YAML Guardrails for product-context.yaml

Every skill that writes to product-context.yaml must validate the file before committing. Invalid YAML silently breaks the dashboard and blocks all downstream consumers.

Validation Command

Run this after every edit to product-context.yaml:

npx js-yaml product-context.yaml > /dev/null && echo "YAML OK"

If the project has the @agentic-engineering-patterns/api package, use the actual loader for deeper validation (Zod schema + preprocessing):

npx tsx -e "
  const { loadProductContext } = require('@agentic-engineering-patterns/api/lib/product-context-loader');
  loadProductContext(process.env.PRODUCT_CONTEXT_PATH || './product-context.yaml');
  console.log('YAML + schema OK');
"

If validation fails, fix the YAML before committing. Do not commit broken YAML under any circumstances.

Common YAML Pitfalls in product-context.yaml

These are the patterns that most frequently break the parser when agents write to the file.

1. List items ending with a colon

A trailing colon makes YAML interpret the item as a mapping key. If the next lines are indented, YAML expects a value — and fails.

# BROKEN — YAML treats this as a mapping key
acceptance_criteria:
  - Generate page redesigned for multi-step video workflow:
    - Intent prompt input
    - Multi-step progress display

# FIXED — quote the entire item, flatten sub-items
acceptance_criteria:
  - "Generate page redesigned for multi-step video workflow: intent prompt input, multi-step progress display"

Rule: Never end a list item with : followed by indented sub-items. Either quote the item or flatten the sub-list.

2. Embedded double quotes inside list items

YAML interprets "text" as a quoted string boundary. Content after the closing quote is invalid.

# BROKEN — YAML sees "Complete Your Profile" as the full string, then chokes on the rest
- "Complete Your Profile" guard includes link to /profile

# FIXED — wrap in double quotes, use single quotes inside
- "'Complete Your Profile' guard includes link to /profile"

# ALSO FIXED — escape inner quotes
- "\"Complete Your Profile\" guard includes link to /profile"

Rule: If a list item contains embedded double quotes, wrap the entire value in double quotes and use single quotes (or escaped quotes) inside.

3. Colons in the middle of list items

A colon followed by a space (: ) triggers YAML key-value parsing.

# BROKEN — YAML tries to parse "Dashboard" as a key
- Dashboard: creator dashboard showing recent generations

# WORKS (preprocessor handles this) — but quoting is safer
- "Dashboard: creator dashboard showing recent generations"

Rule: The preprocessYaml function in the loader auto-quotes most of these, but when writing new content, prefer explicit quoting for items containing : .

4. Special characters: @, {, }

# BROKEN — @ is a YAML tag indicator, { starts a flow mapping
- @mention the user
- Use {variable} interpolation

# FIXED
- "@mention the user"
- "Use {variable} interpolation"

Rule: Quote list items containing @, {, or }.

5. Nested sub-lists under string items

YAML list items are scalar values — they cannot have children unless the item is a mapping key.

# BROKEN — a string item cannot have sub-items
- Main feature description
  - Sub-feature A
  - Sub-feature B

# FIXED — flatten into one item or use a mapping structure
- "Main feature description: Sub-feature A, Sub-feature B"

Pre-commit Checklist

Before committing any change to product-context.yaml:

1. Run the validation command above 2. If adding acceptance_criteria, description, or any free-text list: scan for colons, quotes, and special characters 3. If the validation command is not available (e.g., no Node.js), at minimum review list items for the patterns above

Agent Topology Template

Defines every agent role in the execution pipeline, how they communicate, and how the orchestrator routes work to them. This is an architectural document — changes here affect the behavior of the entire execution plane.

The core rule: agents communicate through structured artifacts, not free text. Every input and output is schema-defined. Every handoff has validation. No exceptions.

---

Agent Roles

Role: [Role Name]

Purpose: [One sentence — what this agent does in the pipeline.]

Responsibility boundary:

• Does: [Specific responsibilities]
• Does not: [Explicit exclusions — prevents role creep]

Input contract:

[Schema definition of the work object this agent receives. Use TypeScript types, JSON Schema, or equivalent. Be explicit about required fields.]

Example:
{
  story_spec: StorySpec,           // The full story specification
  context_slice: {
    context_document: string,       // Relevant sections only
    system_map_module: ModuleDef,   // This story's module definition
    adjacent_interfaces: InterfaceContract[],
    dependency_artifacts: Artifact[] // Public interfaces from completed dependencies
  }
}

Output contract:

[Schema definition of what this agent produces.]

Example:
{
  implementation: {
    branch_name: string,
    files_changed: FileDiff[],
    pr_url: string
  },
  verification: {
    unit_tests: TestResult[],
    contract_tests: TestResult[],
    all_passing: boolean
  },
  status_report: {
    story_id: string,
    outcome: "success" | "failure",
    error_summary?: string,
    what_was_not_tried?: string[]   // Critical for fresh-agent retries
  }
}

Context window composition: [Exactly what goes into this agent's context and in what order. Less is more — irrelevant context degrades performance.]

1. Story Spec (full) 2. Context Document (pruned to: Purpose, Technical Constraints, relevant Layer in MVP Contract) 3. System Map (this module + adjacent interface contracts only) 4. Dependency artifacts (public API surface only, not internals)

Cost budget:

• Expected tokens: [range, e.g., 10k–50k input, 5k–20k output]
• Expected duration: [range, e.g., 2–10 minutes]
• Alert threshold: [e.g., > 100k total tokens or > 20 minutes]

[Repeat for each agent role]

---

Standard Roles

Most projects will need at least these roles. Add or remove based on project complexity.

implementer

Takes a story spec and produces code + tests + PR. The workhorse of the execution plane.

contract-verifier

Takes a PR and runs interface contract tests against the System Map. Catches integration incompatibilities before merge.

integration-tester

Runs end-to-end tests for layer gates. Operates on the combined codebase, not individual stories.

failure-analyst

Takes a failed story's trace and produces a structured failure log with root cause hypothesis and unexplored alternatives. Feeds into fresh-agent retries.

---

Handoff Contracts

[Source Role] → [Target Role]

Trigger event: [What causes this handoff — e.g., "implementer completes PR submission"]

Payload schema:

[Exact structure passed from source to target]

Pre-handoff validation: [Checks that run before the target agent starts. If validation fails, the handoff is rejected and the source agent is notified.]

• [ ] Payload matches schema
• [ ] All required fields present and non-empty
• [ ] Referenced artifacts (files, PRs) actually exist
• [ ] [Domain-specific checks]

Failure handling: [What happens if validation fails — retry source? escalate?]

---

Routing Rules

Dispatch Policy

Queue model: [FIFO within execution slice / priority-based / other]

Assignment: When a story transitions to ready in the work graph, the orchestrator:

1. Checks conflict detection (see below) 2. Checks concurrency limit 3. Assembles context package per the implementer role's context window composition 4. Dispatches to the next available agent instance

Concurrency

• Maximum parallel agents: [Number — start with 5–10, increase as stability is proven]
• Per-module limit: [Optional — prevent one module from consuming all agent capacity]

Conflict Detection

Stories that modify overlapping files must not run in parallel. The orchestrator checks each ready story's "Files Likely Affected" against in-progress stories. Conflicts are serialized — the later story waits until the earlier one completes.

Retry Routing

Attempt 1:   Same agent, error context appended to input
Attempt 2:   Same agent, second retry
Attempt 3:   failure-analyst produces structured log
             → fresh implementer agent receives story spec + failure log
Attempt 4:   Human escalation — story marked 'failed', user notified

Between attempt 2 and 3, the failure-analyst role intervenes to extract useful signal from the failures before handing off to a fresh agent.

---

Cost Tracking Schema

Every agent invocation produces a trace record appended to the project's cost log:

{
  story_id: string,
  agent_role: string,
  attempt_number: number,
  start_time: ISO8601,
  end_time: ISO8601,
  tokens_input: number,
  tokens_output: number,
  cost_usd: number,
  outcome: "success" | "failure" | "escalated",
  error_class?: string    // e.g., "test_failure", "timeout", "context_overflow"
}

Cost Alerts

• Per-story alert: Triggered when total cost across all attempts for a single story exceeds [threshold].
• Per-layer alert: Triggered when cumulative layer cost exceeds [threshold].
• Anomaly alert: Triggered when a story's cost is > 3x the median for its complexity class (S/M/L).

---

Topology Diagram

[Optional but recommended. A simple flow diagram showing agent roles, handoff directions, and the orchestrator's position.]

                    ┌─────────────────┐
                    │   Orchestrator   │
                    │  (Control Plane) │
                    └────────┬────────┘
                             │ dispatches
                    ┌────────▼────────┐
                    │   Implementer    │
                    │ (Execution Plane)│
                    └────────┬────────┘
                             │ PR submitted
                    ┌────────▼────────┐
                    │Contract Verifier │
                    └────────┬────────┘
                             │ pass/fail
                    ┌────────▼────────┐
              ┌─────│   Orchestrator   │─────┐
              │     └─────────────────┘     │
              │ (all layer stories done)     │ (failure)
     ┌────────▼────────┐          ┌─────────▼────────┐
     │Integration Tester│          │ Failure Analyst   │
     └────────┬────────┘          └─────────┬────────┘
              │                             │
         Layer Gate                   Fresh Implementer
         Decision                     or Escalation

Context Document Template

This is the root context document for the project. Every downstream agent inherits this document. Precision here prevents confusion downstream — every vague statement multiplies into ambiguity across parallel agents.

Quality standard: every statement must be convertible into a verification condition. If it cannot be tested, it is not precise enough.

---

Project Identity

• Project name: [Working name]
• Opportunity Brief: [Link to the Phase 0 Opportunity Brief]
• Created: [Date]
• Last updated: [Date]
• Version: [Increment on each meaningful change]

---

Problem Statement

[Who has this problem? What is the problem, specifically? How do they deal with it today? Why is the current approach inadequate? This should be sharp enough that a stranger could read it and understand the pain without further explanation.]

---

Persona / JTBD

Primary Persona

[Describe the primary user concretely. Not "developers" but "solo developers building SaaS products who deploy to edge platforms and want to integrate AI agents without managing infrastructure." Include relevant context: technical skill level, tools they already use, constraints they operate under.]

Job To Be Done

[What job is the user hiring this product to do? Frame it as: "When [situation], I want to [motivation], so I can [expected outcome]."]

---

MVP Boundary

In Scope

[Concrete list of what this system does. Each item should be specific enough to verify.]

Explicitly Out of Scope

[What this system does NOT do, even if users might expect it. This prevents agents from expanding scope.]

Deferred (Possible Future Scope)

[Things that might be added later but are not part of the current effort. Agents should not build toward these unless they come for free.]

Important boundary: "In Scope" defines what the system does. "Goals" (below) defines how you know it's working. A feature can be in scope but not yet a goal for this layer.

---

Goals and Non-Goals

Goals

[Behavior-observable statements. Each must be verifiable by observing the running system. Not aspirations — observable behaviors.

Example: "Poll the issue tracker on a fixed cadence and dispatch work to coding agents" is a goal. "Be a good orchestrator" is not.]

1. [Goal — observable behavior] 2. [Goal — observable behavior]

Non-Goals

[Things a reasonable person might expect this product to do, but it will NOT. Each explains why — preventing scope creep and setting correct expectations for downstream agents.

Example: "Rich web UI — this is a CLI-first tool. A web dashboard is a separate product."]

1. [Non-goal — why excluded] 2. [Non-goal — why excluded]

---

Technical Constraints

Required Stack

[Non-negotiable technology choices and why.]

Preferred Stack

[Preferences that can be overridden with good reason. State the preference and the reasoning.]

Infrastructure

[Where this runs, deployment targets, environment constraints.]

External Dependencies

[Third-party services this project depends on. For each: what it provides, failure behavior, known limitations.]

---

Failure Model

What goes wrong and what the system does about it. Agents building this system need to implement these recovery behaviors. Undocumented failure modes become undocumented bugs.

Failure Classes

Degraded Operation

[What the system can still do when a dependency is down. "Nothing" is a valid answer but must be stated.]

---

Security Model

Trust Boundaries

[What is trusted (e.g., "the operator's machine") and what is not (e.g., "user-submitted content"). Draw the line explicitly.]

Authentication & Authorization

[How users prove identity. How access is controlled. "N/A for MVP" is acceptable but must be stated.]

Secret Handling

[Where secrets come from, how they're stored, how they're passed to components. Never in plaintext config files.]

---

User Activities (Story Map Backbone)

The backbone of the user story map. Each activity is a discrete step in the user's journey, ordered left-to-right as a narrative. These are discovered BEFORE defining layers — the backbone comes first, release boundaries (layers) are drawn across it second.

Read the activities as a sentence to verify narrative coherence: "The user [activity 1], then [activity 2], then [activity 3]..."

Activities from Layer 0 form the core backbone. Later layers may introduce new activities that extend the backbone to the right.

---

Layered MVP Contract

Each layer is a complete, testable, deployable increment. Layer 0 is the walking skeleton — a horizontal slice across ALL activities in the backbone. Each subsequent layer adds capabilities. Most MVPs need 2–4 layers. More than that suggests scope is too large.

Layer 0: Walking Skeleton

User can: [End-to-end journey in concrete steps. "User does X → sees Y → gets Z." Every step observable and verifiable.]

Verification: [The test scenario that proves Layer 0 works.]

Layer 1: [Name]

User can: [Everything from Layer 0, plus new capabilities.]

Verification: [Test scenario for new capabilities.]

Layer 2: [Name]

User can: [Everything from Layer 1, plus new capabilities.]

Verification: [Test scenario.]

---

Success Criteria

Functional

[What must work for this to be a successful MVP? Specific, testable conditions.]

Non-Functional

[Performance, reliability, security. Each with a measurable threshold.]

---

Open Questions

Decisions explicitly deferred. Downstream agents will see these and know not to assume answers.

---

Key Decisions Log

Significant decisions made during Product Framing. Helps downstream agents understand not just what was decided, but why — enabling consistent decisions in ambiguous situations.

---

Stress Test Record

Challenges raised during Phase 1 Stage 3, and how they were resolved.

Opportunity Brief Template

This document captures the core bet behind a product idea. It is deliberately short — one page maximum. Its purpose is to force clarity before committing resources to product design. If the opportunity cannot be stated clearly in this format, it is not ready for Phase 1.

---

The Bet

I believe [target user — be specific] has [problem — describe the pain, not the solution] and currently [how they deal with it today — workarounds, alternatives, suffering] I can build [solution — one sentence] because [unfair advantage — why you specifically can do this]

---

Why Now

What has changed — in technology, market, regulation, or culture — that makes this opportunity viable today when it was not viable before? If nothing has changed, the opportunity may not be real.

---

Strongest Counter-Arguments

List the 2–3 most compelling reasons this might fail or not matter. Be honest. If you cannot articulate the risks, you have not thought deeply enough.

1. [Counter-argument 1] 2. [Counter-argument 2] 3. [Counter-argument 3]

---

Scale of Impact

If this works, what is the magnitude of change? "Saves 10 minutes per week" is different from "enables a workflow that was previously impossible." Neither is inherently better, but the answer shapes every downstream decision.

---

Kill Criteria

Under what conditions should this idea be abandoned? Define this now, before sunk-cost bias sets in.

• [Condition that would invalidate the opportunity]
• [Condition that would invalidate the opportunity]

---

Decision

• [ ] Proceed to Phase 1: Product Framing
• [ ] Kill — opportunity does not justify further investment
• [ ] Defer — revisit when [condition]

Symphony SPEC.md — Specification Writing Reference

This document extracts reusable documentation patterns from OpenAI's Symphony SPEC.md, a ~15,000-word language-agnostic specification for a coding agent orchestration service. Symphony's spec is notable because it is precise enough that any coding agent can implement it in any programming language without clarifying questions.

Use this reference when writing specifications for systems with protocol-level complexity. The patterns here are the standard to aim for.

---

Source Structure

Symphony's SPEC.md has 15 sections. Each maps to an AEP template:

---

Extracted Patterns

Pattern 1: Problem-First Framing

Symphony opens with a single sentence saying what the service IS, then lists exactly 4 operational problems it solves, then states what it is NOT.

How Symphony does it:

"Symphony is a long-running automation service that continuously reads work from an issue tracker, creates an isolated workspace for each issue, and runs a coding agent session for that issue inside the workspace."

>

The service solves four operational problems: [enumerated list]

>

Important boundary: Symphony is a scheduler/runner and tracker reader. Ticket writes are performed by the coding agent.

Why it works: An agent reading this spec knows in 3 paragraphs exactly what to build and — critically — what NOT to build. The "important boundary" prevents the most common scope creep.

Use in AEP: context-document.md Problem Statement section. Ensure every problem statement includes a "what it is NOT" boundary.

---

Pattern 2: Behavior-Observable Goals with Explicit Non-Goals

Goals are statements that can be verified by observing the running system. Non-goals are things a reasonable person might expect but the system deliberately excludes.

How Symphony does it:

Goals:

• "Poll the issue tracker on a fixed cadence and dispatch work with bounded concurrency."
• "Create deterministic per-issue workspaces and preserve them across runs."
• "Recover from transient failures with exponential backoff."

Non-Goals:

• "Rich web UI or multi-tenant control plane."
• "General-purpose workflow engine or distributed job scheduler."

Why it works: Each goal is testable — you can observe the system and confirm it does (or doesn't do) the thing. Non-goals prevent agents from gold-plating.

Use in AEP: context-document.md Goals/Non-Goals section. Distinct from "In Scope / Out of Scope" — scope defines what the system does, goals define how you know it's working.

---

Pattern 3: Typed Entity Definitions with Normalization Rules

Every domain entity has typed fields with defaults, and normalization rules that prevent ambiguity.

How Symphony does it:

Issue:
  id (string) — Stable tracker-internal ID
  identifier (string) — Human-readable ticket key (example: ABC-123)
  priority (integer or null) — Lower numbers are higher priority
  labels (list of strings) — Normalized to lowercase
  blocked_by (list of blocker refs) — Each contains id, identifier, state

Normalization rules:

• "Workspace Key: Derive from issue.identifier by replacing any character not in [A-Za-z0-9._-] with \_"
• "Normalized Issue State: Compare states after lowercase"

Why it works: No ambiguity about what a field contains, what type it is, what the default is, or how to compare values. A coding agent in any language can implement this without guessing.

Use in AEP: system-map.md Domain Model section. Replace unstructured "Key internal concepts" bullet lists with typed field tables.

---

Pattern 4: State Machine Documentation

Stateful entities get explicit state diagrams with named states, transition triggers, and recovery rules.

How Symphony does it:

Orchestration states (distinct from tracker states):

1. Unclaimed — not running, no retry scheduled 2. Claimed — reserved to prevent duplicate dispatch 3. Running — worker task exists 4. RetryQueued — worker not running, retry timer exists 5. Released — claim removed

Transition triggers: Poll Tick, Worker Exit (normal), Worker Exit (abnormal), Retry Timer Fired, Reconciliation State Refresh, Stall Timeout.

"Important nuance: A successful worker exit does not mean the issue is done forever."

Why it works: Every state is named, every transition has a trigger, and easy-to-miss nuances are called out explicitly.

Use in AEP: technical-spec.md State Machines section. Also useful in system-map.md when a module owns a state machine.

---

Pattern 5: Protocol Specs with Illustrative JSON Transcripts

Multi-step interactions get exact handshake sequences with example payloads.

How Symphony does it:

{"id":1,"method":"initialize","params":{"clientInfo":{"name":"symphony","version":"1.0"},"capabilities":{}}}
{"method":"initialized","params":{}}
{"id":2,"method":"thread/start","params":{"approvalPolicy":"...","sandbox":"...","cwd":"/abs/workspace"}}
{"id":3,"method":"turn/start","params":{"threadId":"<thread-id>","input":[{"type":"text","text":"<rendered prompt>"}]}}

Each step includes: what to send, what to expect back, timeout behavior, error mapping.

Why it works: An implementor can literally trace through the JSON transcript to verify their implementation. No prose interpretation needed.

Use in AEP: system-map.md Protocol Sequences section and technical-spec.md Protocol Specifications section.

---

Pattern 6: "Important Boundary" / "Important Nuance" Callouts

Inline blockquote markers flag precision points that are easy to miss.

How Symphony does it:

Important boundary: Symphony is a scheduler/runner and tracker reader. Ticket writes are typically performed by the coding agent.

Important nuance: A successful worker exit does not mean the issue is done forever. The orchestrator schedules a short continuation retry.

Why it works: Agents scan documents for actionable information. These callouts are semantic anchors that prevent the most common implementation mistakes. They stand out visually and can be grep'd.

Use in AEP: Convention across all templates — system-map.md, technical-spec.md, and anywhere precision matters.

---

Pattern 7: Agent-Friendly Redundancy (Config Cheat Sheet)

Symphony includes a section explicitly labeled "intentionally redundant" that summarizes all configuration in one flat table.

How Symphony does it:

"This section is intentionally redundant so a coding agent can implement the config layer quickly."

>

- tracker.kind: string, required, currently linear

- polling.interval_ms: integer, default 30000

- workspace.root: path, default <system-temp>/symphony_workspaces

[... all fields in one list]

Why it works: Agents pay a cognitive/context tax for cross-referencing. A redundant summary eliminates cross-referencing entirely for the most common implementation task (reading config).

Use in AEP: story-spec.md Implementation Cheat Sheet section. Applied at the story level (not product level) because the relevant subset varies per story.

---

Pattern 8: Enumerated Failure Classes with Per-Class Recovery

Failures are taxonomized into classes, each with detection method and recovery behavior.

How Symphony does it:

5 failure classes:

1. Workflow/Config Failures — missing files, invalid YAML, missing credentials 2. Workspace Failures — directory creation, hook timeout, invalid paths 3. Agent Session Failures — handshake failure, turn timeout, subprocess exit 4. Tracker Failures — API errors, non-200 status, malformed payloads 5. Observability Failures — snapshot timeout, dashboard render errors

Each class has explicit recovery: "Dispatch validation failures: Skip new dispatches. Keep service alive. Continue reconciliation."

Why it works: Undocumented failure modes become undocumented bugs. By enumerating failure classes early, every implementor handles the same set of failure scenarios the same way.

Use in AEP: context-document.md Failure Model section (product-level) and technical-spec.md Failure Model section (implementation-level).

---

Pattern 9: Trust Boundary Documentation

Security is not a checklist — it's a boundary declaration about what is trusted and what is not.

How Symphony does it:

"Each implementation defines its own trust boundary."

>

"Implementations should state clearly whether they are intended for trusted environments, more restrictive environments, or both."

>

"Hooks are fully trusted configuration. Hooks run inside the workspace directory."

Filesystem safety is mandatory:

• Workspace path must remain under configured workspace root
• Coding-agent cwd must be the per-issue workspace path
• Workspace directory names must use sanitized identifiers

Why it works: Rather than prescribing specific security controls, Symphony forces each implementation to explicitly declare its trust posture. This prevents the worst outcome: implicit trust assumptions that no one documented.

Use in AEP: context-document.md Security Model section (trust boundaries and auth) and technical-spec.md Security section (filesystem safety, secret handling).

---

Key Principle

The overarching principle from Symphony's approach:

Define WHAT the system does and HOW it behaves under all conditions. Let implementors decide the programming language, framework, and internal architecture.

This is what separates a specification from documentation. Documentation describes what was built. A specification defines what must be built — precisely enough that the builder needs no clarifying questions.

Story Specification Template

The atomic unit of work for the execution plane. A well-written story spec gives an agent everything it needs to implement, verify, and submit a PR without asking questions.

Quality bar: a single-responsibility agent reading only this spec, the Context Document, and the relevant System Map slice should produce correct, mergeable code.

---

Metadata

• Story ID: [Unique identifier, e.g., SANDBOX-001]
• Title: [Short, descriptive]
• Layer: [0, 1, 2… — which development layer]
• Module: [Primary module, as defined in System Map]
• Activity: [Which user activity this enables, from product.activities. Null for infrastructure stories that don't directly serve a user journey step.]
• Wave: [Which wave (execution slice) within the layer this belongs to]
• Dependencies: [Story IDs that must complete before this starts]
• Estimated complexity: [S / M / L]

---

Description

What changes when this story is complete

[Observable difference in the system. Focus on behavior, not implementation. The agent decides how; this spec defines what.]

Why this story exists

[Connect to the Context Document. Which layer of the MVP contract does this serve? Why this layer and not a later one?]

---

Acceptance Criteria

Each must be automatable as a test. If it cannot be automated, it is too vague or belongs in manual review.

1. [Criterion — specific, observable, testable] 2. [Criterion] 3. [Criterion]

---

Interface Obligations

If this story touches a module boundary:

• Implements: [Endpoints/APIs created or modified, referencing System Map contracts]
• Consumes: [Other module APIs called, referencing System Map contracts]
• Contract tests required: [Yes/No]

---

Technical Notes

[Optional. Only include guidance that prevents known pitfalls. Do not over-specify — let the agent choose its approach.]

---

Implementation Cheat Sheet

[Optional. Intentionally redundant summary of everything an implementer agent needs from the Context Document and System Map, copied here so the agent doesn't need to cross-reference. Include only when the story touches 2+ modules or has complex interface obligations.

This section trades DRY for agent effectiveness — a coding agent implementing this story can work from this section alone without searching other documents.]

• Stack: [relevant subset]
• Module: [name] — [one-line responsibility]
• Key types: [TypeScript/schema definitions the agent will need]
• Adjacent interfaces: [endpoints this story calls or implements, with shapes]
• Conventions: [naming, file structure, error handling patterns in this codebase]

---

Files Likely Affected

[Optional. Helps orchestrator detect conflicts between parallel stories.]

---

Verification Strategy

• Unit tests: [What to unit test]
• Integration tests: [Cross-module interaction tests, if applicable]
• Contract tests: [Interface compliance tests, if applicable]

---

Definition of Done

All of the following must be true:

1. All acceptance criteria pass as automated tests 2. All relevant contract tests pass 3. Code follows project conventions 4. PR submitted with description linking to this Story ID 5. No regressions in existing tests 6. Structured status report produced

System Map Template

Defines the architecture at the module level. Serves two functions: (1) establishes module boundaries so decomposition agents work independently, (2) defines interface contracts so parallel implementation stays compatible.

A module boundary drawn wrong costs more to fix than any implementation bug. Review carefully before proceeding to story decomposition.

Callout Conventions

Use these blockquote markers throughout this document to flag precision points that agents must not miss:

Important boundary: Where a responsibility stops and another begins

Important nuance: Easy-to-miss detail that changes implementation

Important constraint: Hard limit that shapes design choices

---

System Overview

Architecture style: [e.g., microservices, modular monolith, serverless functions]

High-level description: [2–3 sentences on structure and why this architecture was chosen, referencing Context Document constraints.]

---

Modules

[Module Name]

Responsibility: [What this module does and does not do. The "does not" part defines the boundary.]

Owns: [Data, state, or resources this module is the authority on. No other module directly modifies these.]

Depends on: [Other modules this one calls or consumes from.]

Technology: [If different from default stack.]

Key internal concepts: [Domain objects, patterns, or abstractions implementers need to understand.]

[Repeat for each module]

---

Domain Model

Domain entities that span module boundaries or require precise typing. Module-specific concepts remain in the Modules section above. Each entity has typed fields so implementers in any language know exactly what to build. See references/symphony-spec-reference.md Pattern 3 for the standard.

[Entity Name]

Purpose: [One sentence — what this entity represents in the system.]

Fields:

Normalization rules:

• [e.g., "All identifiers are lowercased and slugified"]
• [e.g., "Replace characters not in [A-Za-z0-9._-] with \_"]

Invariants:

• [Conditions that must always hold, e.g., "A completed entity always has a non-null completed_at timestamp"]

[Repeat for each domain entity]

---

Interface Contracts

For every module-to-module connection. These will be enforced by automated contract tests in Phase 4. An undefined interface is a guaranteed integration failure.

[Module A] → [Module B]

Protocol: [HTTP REST, gRPC, message queue, function call, etc.]

Endpoint / Channel: [Specific API path, queue name, or function signature.]

Request shape:

[Exact data structure — TypeScript types, JSON Schema, or equivalent. Specify required vs optional, types, constraints.]

Response shape:

[Same specificity as request.]

Error contract:

[What errors can be returned, their shape, what the caller should do for each.]

SLA: [Expected latency, throughput, availability. "TBD" is acceptable if noted as open question.]

---

Protocol Sequences

For interface contracts that involve multi-step interactions (handshakes, streaming, request-response chains), document the sequence here. Simple request-response contracts don't need this — use it when the interaction has ordering, state, or timing constraints. See references/symphony-spec-reference.md Pattern 5 for the standard.

[Protocol Name]: [Module A] <> [Module B]

Trigger: [What initiates this protocol]

Sequence:

1. [Module A] sends [message type]:

   { "type": "init", "payload": { "..." } }

2. [Module B] responds with [message type]:

   { "type": "ack", "session_id": "..." }

3. [Steady-state interaction description]

Timeout behavior: [What happens if step N takes too long] Error behavior: [What happens if step N fails]

Important nuance: [Easy-to-miss detail about this protocol]

---

Data Flow

For each primary user journey in the Layered MVP Contract, trace the data path:

[Journey Name]

User → [Module] → action → [Module] → action → response

Show which module handles each step, what data passes between them, where state is persisted.

---

Third-Party Boundaries

[Service Name]

Provides: [Specific capability used.] Integration point: [Which module, how.] Failure mode: [Behavior when service is down — graceful degradation or hard fail?] Limitations: [Rate limits, quotas, latency.]

---

Deployment Topology

Environments: [Local dev, staging, production.] Module → Runtime mapping: [Which modules run where.] Persistence: [Databases/storage, which modules own them.]

---

Architecture Decision Records

ADR-001: [Title]

Context: [What prompted this decision.] Decision: [What was decided.] Reasoning: [Why, over alternatives.] Consequences: [What this enables and constrains.]

---

Amendment Log

During story decomposition, agents may discover boundary or contract issues. Collected here, reviewed in batch.

Trigger Architecture Review when: 3+ pending amendments, or any single amendment affects an interface contract.

Technical Specification Template: [System Name]

A production-grade system specification for protocol-heavy systems. Use this template when the Context Document and System Map don't capture enough behavioral detail for agents to implement without ambiguity — typically when the system has multi-step protocols, multiple state machines, or complex failure/recovery semantics.

Important boundary: This template is opt-in. Most projects go directly from context-document to system-map. Use this only when the system has protocol-level complexity that those templates don't capture.

When to use this template: During /aep-map, if the System Map reveals 3+ interface contracts requiring protocol sequences, 2+ distinct state machines, explicit failure classes with different recovery behaviors, or trust boundaries crossing module lines.

Reference exemplar: See references/symphony-spec-reference.md for an annotated analysis of OpenAI's Symphony SPEC.md — the standard this template is modeled after.

Quality standard: every statement must be convertible into a verification condition. If it cannot be tested, it is not precise enough.

---

1. Service Identity

[System name] is [one sentence defining what this service IS — what it does, for whom, in what context].

The service solves [N] operational problems:

• [Problem 1 — concrete operational pain point this service eliminates]
• [Problem 2]
• [Problem 3]

Important boundary: [What this service is NOT. State the most likely misunderstanding about scope. Example: "Symphony is a scheduler/runner and tracker reader. Ticket writes are performed by the coding agent."]

Trust Posture

[State explicitly whether this service is intended for trusted environments, restricted environments, or both. This shapes every downstream security and approval decision.]

---

2. Goals and Non-Goals

2.1 Goals

[Behavior-observable statements. Each must be verifiable by observing the running system. Not aspirations — observable behaviors.]

• [Goal — e.g., "Poll the issue tracker on a fixed cadence and dispatch work with bounded concurrency."]
• [Goal — e.g., "Recover from transient failures with exponential backoff."]
• [Goal — e.g., "Support restart recovery without requiring a persistent database."]

2.2 Non-Goals

[Things a reasonable person might expect this system to do, but it deliberately will NOT. Each explains why.]

• [Non-goal — e.g., "Rich web UI or multi-tenant control plane."]
• [Non-goal — e.g., "General-purpose workflow engine or distributed job scheduler."]

---

3. System Overview

3.1 Components

[Named components, each with a one-line responsibility. Number them for cross-referencing.]

1. [Component Name]

• [One-line responsibility. What it does and — if ambiguous — what it does NOT do.]

2. [Component Name]

• [One-line responsibility.]

3.2 Abstraction Layers

[Group components into named layers. This makes the system easier to port and reason about.]

1. [Layer Name] ([layer purpose])

• [What lives in this layer]

2. [Layer Name] ([layer purpose])

• [What lives in this layer]

3.3 External Dependencies

• [Dependency — what it provides, how failure is handled]
• [Dependency]

---

4. Domain Model

4.1 Entities

[Entity Name]

[One sentence — what this entity represents in the system.]

Fields:

[Entity Name]

[Repeat for each domain entity.]

4.2 Normalization Rules

[How values are compared, derived, and sanitized across the system.]

• [Identifier Type] — [Derivation rule, e.g., "Replace any character not in [A-Za-z0-9._-] with \_"]
• [State comparison] — [e.g., "Compare states after lowercase"]

4.3 Invariants

[Conditions that must always hold across the system, not just within one entity.]

• [Invariant — e.g., "A running entity always has a non-null started_at timestamp"]
• [Invariant — e.g., "At most max_concurrent entities may be in Running state"]

---

5. State Machines

[Stateful Entity] States

[These are the system's internal states, which may differ from external/user-visible states.]

1. [State Name] — [When the entity is in this state, what is true about it] 2. [State Name] — [Description] 3. [State Name] — [Description]

Important nuance: [Easy-to-miss detail about state semantics, e.g., "A successful exit does not mean the entity is done forever."]

Transition Triggers

Idempotency and Recovery Rules

• [Rule — e.g., "Claimed checks are required before launching any worker"]
• [Rule — e.g., "Restart recovery is tracker-driven, no durable DB required"]

---

6. Configuration Specification

6.1 Source Precedence

[Where configuration comes from, in priority order.]

1. [Highest priority — e.g., CLI arguments] 2. [e.g., Configuration file values] 3. [e.g., Environment variable indirection] 4. [Lowest priority — built-in defaults]

6.2 Dynamic Reload Semantics

[Can config change at runtime? What happens when it does?]

• [e.g., "Watch config file for changes. Re-apply without restart."]
• [e.g., "Invalid reloads must not crash the service. Keep last known good config."]

6.3 Validation Rules

[What must be true before the system starts dispatching work?]

• [e.g., "Config file can be loaded and parsed"]
• [e.g., "API key is present after environment variable resolution"]

6.4 Config Cheat Sheet

This section is intentionally redundant so a coding agent can implement the config layer quickly.

---

7. Protocol Specifications

[Protocol Name]: [Participant A] <> [Participant B]

Purpose: [What this protocol accomplishes]

Compatibility note: [What must be preserved for interoperability vs. what can vary]

Launch Contract

• Command: [how the subprocess/service is started]
• Working directory: [where it runs]
• Communication: [stdio, HTTP, gRPC, etc.]

Startup Handshake

[Illustrative transcript showing the exact message sequence. Equivalent payload shapes are acceptable.]

{"id":1,"method":"initialize","params":{...}}
// wait for response
{"method":"initialized","params":{}}
{"id":2,"method":"[next step]","params":{...}}

1. [Step 1 — what is sent, what to expect back, timeout] 2. [Step 2] 3. [Steady-state interaction begins]

Streaming / Turn Processing

[How the steady-state interaction works.]

• [e.g., "Read line-delimited JSON from stdout"]
• [e.g., "Buffer partial lines until newline"]
• [e.g., "Stderr is diagnostics only, not protocol"]

Completion conditions:

• [e.g., "turn/completed → success"]
• [e.g., "subprocess exit → failure"]
• [e.g., "turn timeout → failure"]

Timeout and Error Mapping

---

8. Failure Model

8.1 Failure Classes

8.2 Partial State Recovery (Restart)

[What state survives a restart and what must be reconstructed?]

• [e.g., "No retry timers are restored from prior process memory"]
• [e.g., "Service recovers by fresh polling of active items and re-dispatching eligible work"]

8.3 Operator Intervention Points

[How operators control behavior without code changes.]

• [e.g., "Edit config file — changes detected and re-applied automatically"]
• [e.g., "Change entity states in external system — running sessions stopped when reconciled"]
• [e.g., "Restart service — for process recovery or deployment"]

---

9. Security and Operational Safety

9.1 Trust Boundaries

[What is trusted and what is not. Be explicit.]

• [e.g., "The config file is fully trusted configuration"]
• [e.g., "External tracker data is not assumed trustworthy"]

9.2 Filesystem Safety

[Mandatory filesystem invariants.]

• [e.g., "Working paths must remain under configured root"]
• [e.g., "Directory names must use sanitized identifiers"]

9.3 Secret Handling

• [e.g., "Support $VAR indirection in config"]
• [e.g., "Do not log API tokens or secret values"]
• [e.g., "Validate secret presence without printing them"]

9.4 Script/Hook Safety

[If the system executes user-provided scripts or hooks:]

• [e.g., "Hooks are fully trusted configuration"]
• [e.g., "Hook output should be truncated in logs"]
• [e.g., "Hook timeouts are required to avoid hanging the system"]

---

10. Observability

10.1 Logging Conventions

Required context fields:

• [e.g., entity_id, session_id]

Message format:

• [e.g., "Stable key=value phrasing"]
• [e.g., "Include action outcome: completed, failed, retrying"]
• [e.g., "Avoid logging large raw payloads"]

10.2 Runtime Snapshot

[If the system exposes a monitoring interface, define the snapshot shape.]

{
  "running": [],
  "retrying": [],
  "totals": { "input_tokens": 0, "output_tokens": 0, "seconds_running": 0 }
}

10.3 Optional HTTP API

[If applicable — endpoints, response shapes, error envelopes.]

---

11. Operational Boundaries

Important boundary: [System-level boundary that shapes all design decisions]

Important constraint: [Hard limit — resource, scaling, or architectural]

Resource Limits and Backpressure

• [e.g., "Maximum N concurrent workers"]
• [e.g., "Backoff formula: min(10000 * 2^(attempt-1), max_backoff_ms)"]

Scaling Constraints

• [e.g., "Single-process, in-memory state — no distributed coordination"]
• [e.g., "Horizontal scaling requires partitioning by project"]