agent-architecture-decision

Agent Architecture Decision

Use this skill to decide whether a project needs agentic architecture and, if so, design the simplest effective workflow, memory/state model, tool-use model, orchestration approach, evaluation gates, and implementation roadmap.

The goal is not to add agents by default. Prefer deterministic workflows, RAG, API pipelines, and ordinary background jobs when they satisfy the product goal with less risk.

This skill must connect recommendations to the concrete project context: vision, target users, current stack, existing modules, data sources, product workflow, deployment shape, and verification constraints.

Run Modes

Choose one mode before acting:

• discuss-only: analyze and recommend; output a slim AGENTIC_PACKET (at minimum: mode, agentic_value_hypothesis, recommended_shape, why_not_simpler, why_not_more_complex, rejected_options, open_questions); do not edit files.
• architecture-packet: produce a complete AGENTIC_PACKET; do not edit files.
• materialize-docs: produce the complete AGENTIC_PACKET and update architecture or product-control docs only after explicit user approval.
• implement-slice: produce the complete AGENTIC_PACKET including the implementation block, then implement a bounded first slice only after the Implementation Gate passes.

If the user only asks for analysis, default to discuss-only. If the user says "execute" after an architecture packet, first state the file/action plan and only edit after ALL Implementation Gate conditions are true.

Workflow

CREATE A TODO LIST FOR THE TASKS BELOW:

1. Parse the request and choose a run mode. If the requested outcome is ambiguous, ask one focused question and stop.
2. Verify read access to the project root, project docs, source tree, tests, and agent rules. If the project cannot be read but the conversation already provides project context inline → continue in discuss-only mode using the inline context and mark every claim not verified against the repo as unverified. If neither a readable project nor inline context exists → report a blocker and stop.
3. Inspect existing project docs, architecture notes, source tree, AI/provider code, data flow, tests, and agent rules before making claims.
4. Identify current deterministic workflows, RAG paths, tool/API integrations, persistence, memory, and deployment constraints.
5. Decide whether agentic behavior is necessary by comparing against non-agentic baselines. If a non-agentic workflow is sufficient → set recommended_shape to that non-agentic option (Architecture Selection shape 1 or 2), skip step 7, and apply steps 8–12 to the selected workflow; otherwise → continue to step 6.
6. Map the product workflow into deterministic steps, AI-assisted steps, tool calls, state transitions, and human checkpoints.
7. Select the simplest fitting agentic shape.
8. Recommend a technical stack that respects existing project constraints and current official or primary-source docs.
9. Define state, memory, tool, orchestration, safety, and evaluation boundaries.
10. Produce the AGENTIC_PACKET required by the selected mode (slim for discuss-only, complete for all other modes), evaluation gates, and explicit unverified_items.
11. If implementation is explicitly requested, produce an implementation plan and verification matrix before editing.
12. Output the selected mode, recommended shape, rejected alternatives, first safe next step, and any blockers; then stop.