create-update-agentflow-architecture

name	create-update-agentflow-architecture
description	Create or revise AgentFlow architecture proposals from PRDs, prompts, code, or user feedback before implementation.

Create Or Update AgentFlow Architecture

Use this repo-local skill when a request changes product behavior, data models, APIs, permissions, events, background jobs, integrations, or cross-module contracts.

Required Inputs

• User request, PRD, issue, design notes, or code context.
• Existing repository rules and relevant .agents/memory/ files.
• Approved architecture from .agentflow/scripts/agentflow.py snapshot.
• Proposal format from .agentflow/references/proposal-format.md when authoring JSON.

Workflow

1. Read relevant code and requirements first. Do not invent architecture from the PRD alone when code exists.
2. Read relevant memories, especially .agents/memory/architecture-feedback.md, so repeated user feedback is built into the first proposal.
3. Model architecture app-first. Each app owns its data models, flows, and custom architecture pages. Use document artifacts for enums, mixins, admin behavior, permissions, signals, and other important context that does not belong in a model or flow. Choose the document path to place custom folders directly beside Models and Flows; do not add a generic Documentation folder.
4. Create or revise a focused proposal JSON. Include only explicit upsert or delete changes.
5. Make flowcharts simple but complete:
   • Include actors, UI actions, forms, APIs, functions, decisions, reads, writes, jobs, events, external services, and terminal outcomes that matter to the architecture.
   • Use exact planned names for tables, fields, routes, functions, tasks, queues, events, and source modules when known.
   • Put important internal work inside node processing steps instead of hiding it in prose.
6. Keep document pages structured and reviewable:
   • use text for concise explanations, lists for named rules or behaviors, tables for comparable definitions, and code only for exact declarations or signatures;
   • give sections, list items, and table rows stable IDs so comments remain anchored;
   • reuse an existing app hierarchy before creating another folder with overlapping meaning.
7. Validate, submit, and render the static reviewer:

python3 .agentflow/scripts/agentflow.py proposal create --input /tmp/proposal.json
python3 .agentflow/scripts/agentflow.py validate --proposal <proposal-id>
python3 .agentflow/scripts/agentflow.py proposal submit <proposal-id>
make agentflow PROPOSAL=<proposal-id>

Tell the user the review was regenerated. They can refresh an existing browser tab or open .agentflow/review.html manually.

For an existing proposal, use proposal revise instead of proposal create.

Handling Comments

Use .agents/skills/apply-agentflow-comments/SKILL.md whenever the user asks to fix, address, resolve, or review AgentFlow comments. That skill owns comment selection, required comment reading, status changes, and resubmission. Record durable feedback in .agents/memory/architecture-feedback.md or .agents/memory/project-context.md after applying it.

Stop Point

Stop before implementation. Ask the user to approve the currently rendered architecture. Approval must be explicit and must refer to the submitted version under review.