| name | create-update-agentflow-architecture |
| description | Create or revise precise app-owned Django architecture using AgentFlow tables, endpoint and task flows, and minimal platform documentation. |
Create Or Update Django AgentFlow Architecture
Use this skill when work changes Django product behavior, models, APIs, permissions, Celery tasks,
Beat schedules, integrations, settings, or cross-app contracts.
Read Before Drawing
- Read repository rules, memories, and
.agentflow/references/django-architecture.md.
- Read the user request and authoritative requirements.
- Inspect the implemented Django code, active settings, installed local apps, URL declarations,
models, migrations, serializers, views, tasks, and existing conventions relevant to the change.
- Read both architecture states:
python3 .agentflow/scripts/agentflow.py snapshot --state implemented
python3 .agentflow/scripts/agentflow.py snapshot --state approved
Use --page <page-id> when only one page is relevant. Approved architecture is not implemented
until the revision state says so.
Build The Django Hierarchy
Top-level folders must be project-owned Django apps. Add Platform only for genuinely cross-app
deployment, settings, middleware, shared infrastructure, observability, or authentication
architecture. Do not add top-level feature, team, or documentation folders.
Infer app ownership from active Django settings and AppConfig, not directory names alone. Prefer
an explicit local-app list such as MY_APPS when present. Assign API flows to the app that owns the
URL declaration. Exclude Django and third-party apps.
Inside each app, preserve the client's chosen names and order. Typical folders are Models,
Mixins, Enums, APIs, and Tasks; add other folders only when useful and never create empty
ones. Use a common app only for genuinely cross-app primitives.
Choose The Page Type
- Use
table for models, model mixins, enums, permissions, settings matrices, and structured
contracts.
- Use
flow for endpoint data paths, Celery jobs, Beat schedules, signals, integrations, and
system behavior.
- Use
document only for concise platform context that cannot be reviewed clearly as a table or
flow.
Models
Use one table per model. Show exact field name, Django field type, nullability, blank, default,
relation target and on_delete, index or uniqueness, choices, validators, and concise rules.
Put model class, app label, database table, abstract/proxy state, inherited mixins, source module,
and model constraints in page details.
For proposed models, use direct domain names. Name explicit relationship models after both sides,
such as CourseUserMapping. Reject vague ownership, duplicated truth, unjustified JSON storage,
missing integrity constraints, speculative fields, and indexes without a real query path. Reuse an
approved model mixin instead of duplicating shared fields.
Mixins
Use one table per architecture-significant model mixin. Show fields, inherited bases, abstract
state, behavior contract, owner app, and consumers. Keep domain mixins in their domain app; use
common only when unrelated apps share the complete contract.
Enums
List every exact member, stored value, label, meaning, consumer, and compatibility or deprecation
rule. Do not hide meaningful choices in a single pipe-delimited field.
APIs
Use one vertical flow per endpoint data path or tightly coupled operation. Show actor, API entry,
authentication and permission decisions, scope checks, parsing and validation, concrete business
steps, database/cache operations, transaction boundaries, task or event handoffs, response, and
important failures. Put exact method, route, view, serializer, status codes, and contracts in
details. Do not collapse an entire view, serializer, service, or function into one node.
Celery And Beat
Use a job node only for work that is slow, retryable, externally dependent, batch-oriented, or
not needed for the synchronous response. Show enqueue timing, exact task and queue, persisted
identifiers, idempotency, retries, timeout, rate limits, state transitions, and terminal failures
when relevant. Use transaction.on_commit when enqueueing depends on committed data.
For Beat, show the exact schedule and timezone, business justification, overlap protection, batch
limits, catch-up behavior, and failure visibility. Do not use Celery or Beat for every operation.
Draw Simple, Complete Flows
Build every flow from top to bottom. Omit layout or set layout.direction to down; place only
parallel paths side-by-side.
Use only actor, interface, action, api, decision, database, cache, queue, job,
event, external, subprocess, terminal, and error. Keep titles short. Put exact Django
symbols and contracts in subtitles and details. Every node must be reachable, every non-terminal
node must lead somewhere, decision edges must be labeled, and terminal/error nodes cannot have
outgoing edges.
Author And Validate
Read .agentflow/references/proposal-format.md. Create only explicit set-navigation,
upsert-page, and delete-page operations. Omission never deletes architecture. Preserve stable
IDs and submit complete changed pages.
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>
Use proposal revise for an active proposal. Never open the generated page automatically; tell the
user to refresh an existing tab or manually open .agentflow/index.html.
Reconcile Before Review
- Every top-level folder is an owned Django app or justified Platform folder.
- Every requested model, field, relation, constraint, mixin, enum, endpoint path, task, schedule,
failure, and outcome is visible.
- Related model, enum, API, and task pages use identical names and states.
- Existing architecture reflects inspected source; proposed architecture contains no invented
product behavior.
- Django and repository conventions are followed without introducing scope beyond the request.
Stop before planning or implementation. Approval must be explicit.
