Decide the overall shape of an agentic LLM application across five axes: interaction transparency, state/history/memory, context & caching economics, capability integration (tools/skills/MCP/secrets), and execution substrate & side effects. Use when architecting a new coding-agent console or a non-coding agent (research, document, image, or data-artifact producer) before implementation begins, or when auditing whether an existing agentic app hides its reasoning, treats the transcript as its only state, has no context/caching strategy, bolts on tools/secrets with no custody model, or ships side effects with no isolation, no human gate, or no receipt. NOT for implementation stacks once the shape is decided (rust-tauri-development), pure model/router selection (llm-router), prompt wording (prompt-engineer), or multi-agent coordination mechanics once the app-level shape exists (multi-agent-coordination, swarm-invocation-designer).
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Decide the overall shape of an agentic LLM application across five axes: interaction transparency, state/history/memory, context & caching economics, capability integration (tools/skills/MCP/secrets), and execution substrate & side effects. Use when architecting a new coding-agent console or a non-coding agent (research, document, image, or data-artifact producer) before implementation begins, or when auditing whether an existing agentic app hides its reasoning, treats the transcript as its only state, has no context/caching strategy, bolts on tools/secrets with no custody model, or ships side effects with no isolation, no human gate, or no receipt. NOT for implementation stacks once the shape is decided (rust-tauri-development), pure model/router selection (llm-router), prompt wording (prompt-engineer), or multi-agent coordination mechanics once the app-level shape exists (multi-agent-coordination, swarm-invocation-designer).
license
Apache-2.0
allowed-tools
Read,Write,Edit,Bash,Grep,Glob
metadata
{"category":"Agent & Orchestration","tags":["agent-architecture","transparency","episodic-memory","capability-integration","execution-substrate"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"agentic-coding-ux-designer","reason":"Turns the transparency axis into a concrete flow (plan/apply/review, checkpoint, receipt UI)."},{"skill":"agent-work-receipt-designer","reason":"Defines the receipt schema this skill requires at the execution-substrate finish line."},{"skill":"human-gate-designer","reason":"Designs the actual approval UX for the side-effect human checkpoint this skill mandates."},{"skill":"episodic-memory-algorithms","reason":"Supplies the TTL/blob-promotion/recall mechanics behind the state/memory axis."}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}
Agentic App Architecture
Decide the shape of an agentic app — what it shows, what it remembers, what it costs, what powers it has, and where its actions land — before writing implementation code.
Use This For
Architecting a new coding-agent console (Claude-Code-like), operator surface, or pd-console-style fleet UI from scratch.
Architecting a non-coding agent that produces documents, images, data artifacts, or self-authored tools at runtime.
Deciding memory model, context/caching strategy, and MCP/tool/secret wiring before implementation locks them in.
Auditing an existing agentic app for a hidden-reasoning, transcript-only-state, unbounded-context, or ungated-side-effect design flaw.
Reconciling a coding agent's git/worktree substrate against a non-coding agent's artifact-and-receipt substrate in the same product.
Do Not Use This For
Picking a UI framework, desktop shell, or deployment stack once the architecture axes are decided (rust-tauri-development).
Choosing which model or router serves a request (llm-router) or wordsmithing the system prompt (prompt-engineer).
Designing the moment-to-moment protocol between cooperating agents once the app-level shape already exists (multi-agent-coordination, swarm-invocation-designer).
Five-Axis Decision Flow
flowchart TD
A[Interaction surface & transparency] --> B[State, history & memory]
B --> C[Context & caching economics]
C --> D[Capability integration: tools/skills/MCP/secrets]
D --> E[Execution substrate & side effects]
E --> F{Coding agent?}
F -->|yes| G[Worktree isolation + PR finish line]
F -->|no| H[Artifact + self-authored-tool substrate]
G --> I[Ship with receipts]
H --> I
Choose the interaction model. Decide what surfaces the agent's thinking and tool calls (inline, streaming, collapsible workbench), whether a plan is shown before acting, and how a human interrupts mid-run. A hidden-hands agent is untrustable by construction — see references/interaction-surface-and-transparency.md.
Choose the state/memory model. Decide whether history is durable, whether threads can fork, and whether salient facts get promoted to episodic memory with TTLs. The transcript is not the whole state — see references/state-memory-and-context.md.
Choose the context/caching strategy. Decide the caching approach (the Anthropic prompt cache has a ~5-minute TTL, so poll/sleep cadence and context stability matter), the eviction/summarization policy, and what gets promoted out of the window into memory.
Wire capabilities with custody. Decide tool schemas (lazy-load if the toolset is large), skill packs, an MCP topology (small always-on global core, per-project specialists — see references/capabilities-and-execution-substrate.md), and how secrets reach tool calls without landing in argv, logs, or the transcript.
Choose the execution substrate and side-effect gates. For coding agents: one worktree per writer, advisory claims, a PR finish line with artifact-backed validation, never force-push or touch main. For non-coding agents: durable artifacts (documents/images/data/rendered web artifacts) or even agent-authored tools, each gated by a human checkpoint for irreversible/outward-facing actions.
Ship with receipts. Every side-effecting run leaves a durable, artifact-backed receipt — not a chat message claiming success.
Audit before you build, and again before you ship. Run scripts/agentic_app_audit.mjs against the spec at design time, and again against the shipped reality.
Output Contract
Produce an architecture decision covering all five axes plus a machine-checkable audit:
Use scripts/agentic_app_audit.mjs to score a spec matching schemas/agentic-app-spec.schema.json and return { pass, coverageByAxis, findings, recommendations }.
Anti-Patterns
Chat Box With Secret Hands
Novice: "Put an AI chat next to the work surface and let it act; the transcript is enough of a UI."
Expert: Hidden thinking and hidden tool calls make an agent both untrustable and un-steerable. Reasoning and tool use must be surfaced inline or in an inspectable pane, with a plan shown before consequential action.
Detection: agentic_app_audit.mjs fires hidden-thinking-or-tool-use (critical) whenever thinkingVisible or toolUseVisible is false.
Transcript Is The Whole State
Novice: "The conversation history is the app's memory; there's nothing else to design."
Expert: Durable history, thread forking to explore alternates, and episodic memory (TTL'd, relevance-recallable, promoted out of the raw transcript) are separate, necessary pieces of state design — not features of a good chat UI.
Detection: agentic_app_audit.mjs fires transcript-only-state (critical) whenever both forking and episodicMemory are false.
Side Effects With No Gate, No Isolation, No Receipt
Novice: "The agent can write files, call APIs, and merge its own work; we'll review if something looks wrong."
Expert: Every side-effecting action needs isolation (a worktree for coding agents, a sandbox for non-coding agents), a human checkpoint before anything irreversible or outward-facing, and a durable artifact-backed receipt afterward — especially for coding agents writing to a shared checkout.
Detection: agentic_app_audit.mjs fires no-execution-isolation, no-human-gate-on-side-effects, or no-artifact-receipt (critical for agentType: coding, high otherwise) whenever isolation, sideEffectHumanGate, or artifactReceipts is false.
examples/expected-output.md — Example Output: Agentic App Architecture — Scenario: "Harbor Scout" — a non-coding Port Daddy fleet agent that researches a competitor's release notes, writes a summary report artifac
references/capabilities-and-execution-substrate.md — Capabilities & Execution Substrate — Use this when wiring an agent's powers (tools, skills, MCP servers, secrets) and when deciding where its actions actually land.
references/interaction-surface-and-transparency.md — Interaction Surface & Transparency — Use this when deciding what an agentic app shows the human — thinking, tool use, plans, and steering — before it renders a single screen.
references/state-memory-and-context.md — State, Memory & Context — Use this when deciding what persists beyond the current turn, what gets promoted to durable memory, and how the context window and prompt ca
templates/output-template.md — Agentic App Architecture Decision — [One-sentence description of the app being architected, and whether it is a coding agent or non-coding agent.] - Transparency: [what the
