create-update-agentflow-architecture

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

1. Read repository rules, memories, and .agentflow/references/django-architecture.md.
2. Read the user request and authoritative requirements.
3. Inspect the implemented Django code, active settings, installed local apps, URL declarations, models, migrations, serializers, views, tasks, and existing conventions relevant to the change.
4. 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 except a fire-and-forget job must lead somewhere. A job may be a leaf when the caller does not wait for task execution; do not add a fake terminal or edge. 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.