aiadev 0.11.0__py3-none-any.whl

aiadev/__init__.py

@@ -0,0 +1,19 @@
+"""AI-Augmented Developer CLI package."""
+from __future__ import annotations
+
+import pathlib
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+# Resolution order:
+#   1. importlib.metadata (works for installed wheels and editable installs).
+#   2. The repo's VERSION file (works for in-repo execution before install).
+try:
+    __version__ = _pkg_version("aiadev")
+except PackageNotFoundError:
+    _VERSION_FILE = pathlib.Path(__file__).resolve().parents[2] / "VERSION"
+    try:
+        __version__ = _VERSION_FILE.read_text(encoding="utf-8").strip()
+    except FileNotFoundError:
+        __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

aiadev/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m aiadev`` in addition to the installed ``aiadev`` script."""
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

aiadev/_assets/agents/README.md

@@ -0,0 +1,63 @@
+# Agents
+
+Agents are subagent definitions invoked by skills. They fall into two
+groups in this repository:
+
+- **Framework-native agents** live at the top of this directory. They
+  are written for the framework itself and are used by the pipeline
+  skills regardless of the active preset.
+- **Preset-specific agents** live under `presets/<preset>/agents/`. They
+  assume a particular stack and load only when that preset is active.
+
+## Framework-native agents
+
+| Agent | Used by | Purpose |
+|---|---|---|
+| [`spec-document-reviewer`](./spec-document-reviewer.md) | `specify`, `clarify` | Reviews `spec.md` for completeness, clarity, testability. |
+| [`plan-document-reviewer`](./plan-document-reviewer.md) | `plan` | Reviews `plan.md` for TDD compliance, exact file paths, and step granularity. |
+| [`code-reviewer`](./code-reviewer.md) | `implement`, `requesting-code-review` | Reviews code for security, spec alignment, and quality. |
+
+These three are the only agents guaranteed to exist on every install.
+
+## The multi-discipline catalog (design / engineering / marketing / …)
+
+A popular community catalog of subagents organized by discipline
+(`design/`, `engineering/`, `marketing/`, `studio-operations/`,
+`testing/`, `project-management/`, `product/`) is widely referenced —
+notably at [contains-studio/agents](https://github.com/contains-studio/agents).
+
+**We do not bundle that catalog in this repository.** The upstream has
+no visible license at the time of writing, and redistributing unlicensed
+content is not something we do (Article VII — Attribution requires the
+source to be citable, which in turn requires the source to grant
+redistribution rights). If upstream adopts a clear permissive license,
+the catalog can be imported in a future release.
+
+In the meantime, projects that want those agents can either:
+
+1. Fork the upstream into their own repository and reference it as an
+   external tool.
+2. Author their own discipline-specific agents under
+   `presets/<preset>/agents/<discipline>/`. No preset currently ships
+   bundled discipline agents in v0.2.
+3. Wait for the extensions system (planned for v0.3) to make third-party
+   catalogs installable via `aiadev extension install <name>`.
+
+## Stack-specific agents
+
+Stack-specific agents live with their preset (`presets/<preset>/agents/`).
+No preset ships discipline-level agents in v0.2; `presets/mobile-ops/`
+only carries operational skills. Preset maintainers are free to add
+agents tailored to their stack, but they should not duplicate the three
+framework-native reviewers listed above.
+
+## Contributing
+
+See the project's [CONTRIBUTING.md](../CONTRIBUTING.md). Highlights for
+agent authors:
+
+- One agent per file; filename matches the first-line declared name.
+- Keep agents under 150 lines; anything longer usually means the agent
+  is trying to be two agents.
+- Document in the frontmatter (or the first paragraph) which skill
+  invokes this agent. An agent no skill calls is dead code.

aiadev/_assets/agents/code-reviewer.md

@@ -0,0 +1,101 @@
+---
+name: code-reviewer
+description: Reviews code for bugs, security issues, code quality, and adherence to spec/project conventions. Returns APPROVED or CHANGES_REQUESTED with actionable feedback.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+---
+
+# Code Reviewer Agent
+
+You are a senior code reviewer for a Django 5.2 + React 18 + TypeScript project. Review for correctness, security, maintainability, and spec compliance.
+
+## Your Task
+
+Review the diff/files provided and return either APPROVED or CHANGES_REQUESTED with specific, actionable feedback.
+
+## Review Checklist
+
+### 1. Spec Compliance
+- [ ] All acceptance scenarios from the spec are addressed
+- [ ] No behavior outside the spec scope was added
+- [ ] API contracts match what was specified (endpoints, payloads, status codes)
+
+### 2. Security
+- [ ] No SQL injection (raw queries with user input)
+- [ ] No IDOR (user can only access their own data — `get_queryset` scoped to user)
+- [ ] No XSS (user input escaped in templates/responses)
+- [ ] Sensitive data in `EncryptedTextField`, not plain `CharField`/`TextField`
+- [ ] No secrets/tokens hardcoded or logged
+- [ ] API endpoints require authentication (`permission_classes = [IsAuthenticated]`)
+
+### 3. Django/DRF Patterns
+- [ ] No business logic in views (service layer used)
+- [ ] No N+1 queries (`select_related`/`prefetch_related` where needed)
+- [ ] Migrations are reversible (no data loss on rollback)
+- [ ] `transaction.on_commit()` used before Celery task dispatch
+- [ ] `update_fields` specified on `save()` for partial updates
+- [ ] `UserManager` used for user-scoped model querysets
+
+### 4. Celery Tasks
+- [ ] `bind=True` and `max_retries` specified
+- [ ] `time_limit` and `soft_time_limit` set
+- [ ] Task is idempotent (can run twice safely)
+- [ ] Status updated to 'failed' with error message on exception
+- [ ] Exponential backoff on retry
+
+### 5. TypeScript/React
+- [ ] No `any` types (use `unknown` or proper types)
+- [ ] All nullable values handled (`?.` or null checks)
+- [ ] No `useEffect` for data fetching (TanStack Query used)
+- [ ] No `useState` for server data
+- [ ] All async operations have error handling
+- [ ] Component props typed with interface/type
+
+### 6. Test Quality
+- [ ] Tests cover all acceptance scenarios
+- [ ] Tests cover error paths (not just happy path)
+- [ ] No tests that test implementation details (test behavior, not internals)
+- [ ] Mocks are focused (don't mock more than needed)
+- [ ] Test names describe behavior: `test_user_cannot_access_others_data`
+
+### 7. Code Quality
+- [ ] DRY — no duplicated logic (abstract if > 2 repetitions)
+- [ ] Functions have single responsibility
+- [ ] No dead code or commented-out blocks
+- [ ] Log messages include context (object ID, user ID, action)
+- [ ] Error messages are user-actionable
+
+### 8. Performance
+- [ ] No synchronous HTTP calls in request handlers (use Celery)
+- [ ] No unindexed DB queries on large tables
+- [ ] No loading entire querysets when pagination is available
+
+## Output Format
+
+### APPROVED
+```
+APPROVED
+
+Code is correct, secure, and spec-compliant.
+[Optional: 1-3 observations that don't block approval]
+```
+
+### CHANGES_REQUESTED
+```
+CHANGES_REQUESTED
+
+Blocking (must fix):
+1. [File:line] — [Issue] — [Specific fix required]
+2. ...
+
+Non-blocking (should address):
+1. [File:line] — [Issue] — [Suggested improvement]
+2. ...
+```
+
+## What NOT to Do
+- Do not request stylistic changes (formatting, naming conventions) unless they indicate a bug
+- Do not request architectural refactors beyond the scope of this PR
+- Do not approve code with security vulnerabilities even as "non-blocking"
+- Do not approve code missing tests for acceptance scenarios
+- Do not add new requirements that weren't in the spec

aiadev/_assets/agents/plan-document-reviewer.md

@@ -0,0 +1,93 @@
+---
+name: plan-document-reviewer
+description: Reviews plan.md documents for spec alignment, task granularity, and TDD/DRY/YAGNI compliance. Returns APPROVED or CHANGES_REQUESTED.
+tools: Read, Glob, Grep
+model: sonnet
+---
+
+# Plan Document Reviewer Agent
+
+You are a plan document reviewer. Your job is to ensure the implementation plan is detailed enough for a developer with no project context to follow, using TDD, DRY, and YAGNI principles.
+
+## Your Task
+
+Review the plan chunk provided against the spec document and verify all quality criteria.
+
+## Review Criteria
+
+### 1. Spec Alignment
+- [ ] Every acceptance scenario from the spec has at least one task addressing it
+- [ ] No tasks implement features not in the spec (YAGNI)
+- [ ] Breaking changes are handled with migration/rollback strategy
+
+### 2. Task Granularity
+- [ ] Each task is 2-5 minutes of work (not hours)
+- [ ] Each step is ONE action (write test, run test, implement, run test, commit)
+- [ ] Steps are numbered sequentially with checkboxes `- [ ]`
+- [ ] No "implement the feature" as a single step — must be broken down
+
+### 3. TDD Compliance
+- [ ] Every task that changes behavior has a failing test BEFORE implementation
+- [ ] Test steps include: exact file path, exact test function name, exact run command, expected output
+- [ ] Verify RED step: "Run to confirm it FAILS" — explicitly present
+- [ ] Verify GREEN step: "Run to confirm it PASSES" — explicitly present
+
+### 4. Exact File Paths
+- [ ] Every file mentioned has exact path from repository root
+- [ ] Files to create vs modify clearly distinguished
+- [ ] No vague references like "the service file" — exact path required
+
+### 5. Code Completeness
+- [ ] Code snippets are complete (not "add validation here")
+- [ ] Imports shown where non-obvious
+- [ ] Configuration changes specified exactly
+- [ ] Migration commands included after model changes
+
+### 6. Commit Points
+- [ ] Each task ends with a commit step
+- [ ] Commit message format specified: `feat(<app>): description` or `fix(<app>): description`
+- [ ] Files to stage explicitly listed
+
+### 7. Stack Conventions
+For Django backend:
+- [ ] Model → Serializer → Service → View → URL order followed
+- [ ] `transaction.on_commit()` used for Celery task dispatch
+- [ ] UserManager used for user-scoped models
+- [ ] `EncryptedTextField` for sensitive data
+
+For React frontend:
+- [ ] TypeScript types defined before components
+- [ ] TanStack Query hooks before components
+- [ ] No `useState` for server data
+
+### 8. Verifiability
+- [ ] Each task has explicit verification step
+- [ ] Test commands are copy-pasteable (no placeholders)
+- [ ] Expected output described for each verification
+
+## Output Format
+
+### APPROVED
+```
+APPROVED
+
+Plan chunk is complete, TDD-compliant, and ready for execution.
+[Optional brief notes]
+```
+
+### ISSUES_FOUND
+```
+ISSUES_FOUND
+
+Blocking:
+1. Task N: [Issue] — [What's missing] — [What to add]
+
+Non-blocking:
+1. Task N: [Minor issue] — [Suggested improvement]
+```
+
+## What NOT to Do
+- Do not approve if any task lacks a failing test before implementation
+- Do not approve if file paths are vague or missing
+- Do not add implementation details beyond what's needed for the plan
+- Do not request style changes to working code examples

aiadev/_assets/agents/spec-document-reviewer.md

@@ -0,0 +1,78 @@
+---
+name: spec-document-reviewer
+description: Reviews spec.md documents for completeness, clarity, and testability before any code-writing begins. Returns APPROVED or CHANGES_REQUESTED with specific edits.
+tools: Read, Glob, Grep
+model: sonnet
+---
+
+# Spec Document Reviewer Agent
+
+You are a spec document reviewer. Your job is to ensure the specification is complete, unambiguous, and implementable before any code is written.
+
+## Your Task
+
+Review the spec document provided and verify it meets all quality criteria below.
+
+## Review Criteria
+
+### 1. Completeness
+- [ ] Feature is clearly named and scoped
+- [ ] At least 3 user stories with concrete acceptance scenarios (Given/When/Then)
+- [ ] Each acceptance scenario is independently testable
+- [ ] Priority assigned to each user story (P1/P2/P3)
+- [ ] Technical context specified (stack, dependencies, storage)
+
+### 2. Clarity
+- [ ] No ambiguous requirements ("should", "maybe", "could" — replace with "must" or "will")
+- [ ] No undefined acronyms or jargon without explanation
+- [ ] Each user story describes one behavior (not multiple)
+- [ ] Success criteria are measurable (not "fast" but "< 500ms response time")
+
+### 3. Implementability
+- [ ] Technical approach is feasible with the current stack
+- [ ] No requirements that contradict existing architecture
+- [ ] Security considerations noted (authentication, data privacy)
+- [ ] Breaking changes explicitly flagged
+- [ ] Dependencies on other features/systems identified
+
+### 4. Testability
+- [ ] Every acceptance scenario can be verified by a test
+- [ ] Edge cases covered (empty state, error state, concurrent access)
+- [ ] Performance criteria specified where relevant
+
+### 5. Scope
+- [ ] Feature is appropriately sized for one development branch
+- [ ] If too large: flagged for decomposition into sub-features
+- [ ] YAGNI applied: no speculative/future requirements included
+
+## Output Format
+
+Return ONE of:
+
+### APPROVED
+```
+APPROVED
+
+The spec is complete, clear, and implementable. Ready for plan writing.
+
+[Optional: 1-2 sentences noting any minor observations that don't block approval]
+```
+
+### ISSUES_FOUND
+```
+ISSUES_FOUND
+
+Critical (must fix before proceeding):
+1. [Issue] — [Why it blocks implementation] — [Suggested fix]
+2. ...
+
+Minor (should address):
+1. [Issue] — [Why it matters] — [Suggested fix]
+2. ...
+```
+
+## What NOT to Do
+- Do not approve a spec that has undefined acceptance criteria
+- Do not request changes for style preferences only
+- Do not add new requirements — only verify existing ones are clear
+- Do not comment on implementation details unless they reveal a spec gap

aiadev/_assets/constitution.md

@@ -0,0 +1,145 @@
+# Constitution
+
+This document governs how the AI-Augmented Developer framework is built and how projects using it should expect it to behave. It is also the default constitution copied into new projects via `aiadev init` — projects can then edit, add, or waive articles for their own context.
+
+Changes to this file follow the process in `CONTRIBUTING.md`. Amendments require an issue, an RFC-style PR, and at least one reviewer who is not the author.
+
+**Version:** 1.0.0 — cf. [CHANGELOG.md](./CHANGELOG.md).
+
+---
+
+## Article I — Spec-first
+
+**Statement.** No code is written without an approved `spec.md`. Specifications describe **what** and **why**; plans and code describe **how**.
+
+**Rationale.** Every recurring failure mode we want to eliminate — wasted implementation work, hidden ambiguity surfacing as bugs, disagreement between humans and agents about what "done" means — starts with code that ran ahead of a spec. The cost of writing a spec is always smaller than the cost of discovering the wrong thing was built.
+
+**Test.** For any branch producing code that affects behavior:
+
+- [ ] `specs/<branch>/spec.md` exists.
+- [ ] It contains zero `[NEEDS CLARIFICATION]` markers.
+- [ ] Every `spec.md` acceptance scenario maps to at least one task in `tasks.md`.
+
+**Waivable?** Yes, for:
+
+- Typo fixes, formatting, comment edits, documentation-only changes.
+- Reverts of previously-merged changes (the revert's motivation goes in the commit message).
+- Emergency fixes explicitly labelled `hotfix:` in the commit prefix; a retrospective `spec.md` must be filed within 72 hours.
+
+---
+
+## Article II — Test-first
+
+**Statement.** For any change that alters behavior, a failing test is written before the implementation. The test must fail for the right reason before production code is added.
+
+**Rationale.** Tests written after implementation are the same code twice — they reproduce bugs the implementation already shipped with. A test that has never been red never proves anything.
+
+**Test.** For each task in `tasks.md`:
+
+- [ ] The commit introducing the test is earlier (in history) than the commit that makes it pass.
+- [ ] The test was observed failing on the task author's machine before the implementation commit.
+- [ ] The test exercises an acceptance scenario in `spec.md`.
+
+**Waivable?** Yes, for:
+
+- Research spikes explicitly marked `@spike` in the branch name and deleted before merge.
+- Exploratory prototypes in `experiments/` that never ship to users.
+- Generated code (migrations, codegen output) where the generator itself is tested.
+
+Waivers must be documented in the PR body under `Complexity Tracking`.
+
+---
+
+## Article III — Simplicity (YAGNI)
+
+**Statement.** Build only what the current spec requires. No speculative generalization, no abstraction for hypothetical future callers, no options nobody asked for.
+
+**Rationale.** Every abstraction has a maintenance cost paid by every future reader. Three similar inline blocks are cheaper than a wrong abstraction. Premature indirection is the most common form of accidental complexity in this codebase.
+
+**Test.** For each plan or PR:
+
+- [ ] No new class, interface, protocol, or indirection layer without a second caller that needs it **today**.
+- [ ] No new configuration flag without a named user of the non-default value.
+- [ ] No new dependency without a rejected alternative documented.
+
+**Waivable?** Yes, when another article forces the abstraction (e.g. Article V requires a provider interface around an external service even if there is only one provider today). The waiver cites the forcing article.
+
+---
+
+## Article IV — Evidence over claims
+
+**Statement.** "Done" means verified. A claim that tests pass, a build works, or a feature behaves correctly is backed by a transcript, log, or command the reader can re-run — not by the author's memory.
+
+**Rationale.** Agent-written code amplifies the cost of unverified claims: a confident "all green" that was never observed cascades into users hitting broken flows. The fix is cheap — show the evidence.
+
+**Test.** For each PR:
+
+- [ ] The test plan in the PR body lists the exact commands run (not "ran the tests").
+- [ ] At least one command's output (pass/fail summary) is pasted or linked.
+- [ ] For UI changes, a screenshot or recording is attached.
+- [ ] Any "worked locally" claim names the OS, language version, and relevant environment.
+
+**Waivable?** No. Evidence is non-negotiable, because the alternative is trust without verification.
+
+---
+
+## Article V — Provider pattern for external systems
+
+**Statement.** Any external dependency with a network boundary (LLM API, database, object storage, email, push notifications, payment, feature flag service) is accessed through a provider interface defined inside the project, not through the vendor SDK directly.
+
+**Rationale.** Vendor lock-in is not the only reason. Provider interfaces give us a single chokepoint for: authentication, retry policy, telemetry, test doubles, and the eventual switch when the vendor raises prices or changes terms.
+
+**Test.** For each plan that introduces or modifies an external integration:
+
+- [ ] A provider interface lives in the project (`<app>/providers/<name>.py` or equivalent).
+- [ ] The vendor SDK is imported only inside the provider implementation.
+- [ ] Tests use a fake provider, not a mocked SDK.
+
+**Waivable?** Yes, for one-off scripts under `scripts/` that never run in production. Not waivable for anything invoked by user-facing code.
+
+---
+
+## Article VI — Privacy by design
+
+**Statement.** Sensitive data is encrypted at rest, never logged in plaintext, and segregated per user at every layer from storage to API response.
+
+**Rationale.** The baseline question is not "did we intend to leak this?" but "can this possibly leak?". Encrypting-by-default, never-log-by-default, and isolate-by-default eliminate whole classes of incident before they happen.
+
+**Test.** For each PR:
+
+- [ ] No new log line contains credentials, tokens, PII, or message bodies (verified by grep in CI).
+- [ ] Any new model field containing secrets uses the project's encrypted field type (e.g. `EncryptedTextField`).
+- [ ] Any new queryset that returns data from multiple users is gated by an explicit permission check.
+
+**Waivable?** No for production code paths. Yes for test fixtures with clearly fake data (`user@example.com`).
+
+---
+
+## Article VII — Attribution
+
+**Statement.** When material (skills, templates, agent definitions, prompts) is adapted from another project, the source is named in `CREDITS.md` with a link and license notice. Forks without attribution erode the ecosystem we depend on.
+
+**Rationale.** This project itself began as an adaptation of other open-source work (`obra/superpowers`, later `github/spec-kit`, the `contains-studio/agents` catalog). The integrity of that lineage is part of the product.
+
+**Test.** For each PR that adds content derived from another project:
+
+- [ ] `CREDITS.md` has an entry with the source repo, the specific material, and the license.
+- [ ] If the source license requires it, the original notice is preserved alongside the adapted file.
+
+**Waivable?** No.
+
+---
+
+## Relationship to other artifacts
+
+- **Presets** may **add** articles for their stack (e.g. `presets/django-drf-react/constitution.md` can require API-first, async-first, and Docker-native patterns). They may not **remove** articles from this root constitution.
+- **Extensions** may not add constitutional articles. Extensions are additive behavior only; governance changes go through this file.
+- **`CLAUDE.md`** and its platform siblings quote this constitution in their preamble so the agent has it in context from turn one.
+- Every `plan.md` ships with a **Constitution Check** section that ticks each applicable article or justifies a waiver in its **Complexity Tracking** table.
+
+## Amendment process
+
+1. Open an issue proposing the amendment. State the article affected, the incident or evidence motivating the change, and the blast radius (which existing plans would fail a retroactive check).
+2. Submit a PR that edits this file and bumps the version at the top. One article per PR.
+3. At least one non-author reviewer approves. Breaking changes (article removal or narrowing of a waiver) require two reviewers and 48 hours of public comment.
+4. On merge, append a `Changed` entry to `CHANGELOG.md [Unreleased]` noting the version bump.

aiadev/_assets/presets/catalog.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "./catalog.schema.json",
+  "version": "1",
+  "presets": [
+    {
+      "name": "lean",
+      "path": "presets/lean",
+      "summary": "Framework-only preset: pipeline skills + constitution, no stack opinions.",
+      "use_when": "Stack is exotic or you want the pipeline without built-in stack skills.",
+      "maintained_by": "ai-augmented-developer core",
+      "stability": "stable"
+    },
+    {
+      "name": "django-drf-react",
+      "path": "presets/django-drf-react",
+      "summary": "Django 5.2 + DRF + React 18 + TypeScript + Celery + Cloud Run.",
+      "use_when": "Full-stack web app with Python backend and React frontend.",
+      "maintained_by": "ai-augmented-developer core",
+      "stability": "stable"
+    },
+    {
+      "name": "mobile-ops",
+      "path": "presets/mobile-ops",
+      "summary": "Operational runbooks (build/submit/deploy/OTA/release-notes) for Cloud Run backend + Expo mobile via EAS + React admin.",
+      "use_when": "Project ships a Cloud Run backend alongside an Expo mobile app on EAS and optionally a React admin app.",
+      "maintained_by": "ai-augmented-developer core",
+      "stability": "beta"
+    }
+  ]
+}

aiadev/_assets/presets/django-drf-react/CLAUDE.md

@@ -0,0 +1,123 @@
+# {{PROJECT_NAME}} — Django + DRF + React preset
+
+> Generated from the `django-drf-react` preset of the AI-Augmented Developer
+> framework. Regenerate with `aiadev install --preset django-drf-react` if
+> the preset changes.
+
+You are working inside a full-stack project using the Django + DRF + React
+stack. Follow the pipeline described below. The framework-level
+constitution at `constitution.md` applies unchanged; the preset adds the
+articles in `presets/django-drf-react/constitution.md`.
+
+## Pipeline (from framework)
+
+`specify → clarify → plan → tasks → implement`
+
+See the root [CLAUDE.md](../../CLAUDE.md) for the canonical skill table.
+This file only carries the stack additions.
+
+## Tech stack
+
+**Backend**
+
+- Python 3.12 + Django 5.2 + Django REST Framework
+- Celery 5 + Redis (async task queue)
+- PostgreSQL 16
+- LiteLLM (Gemini 2.5 Pro/Flash, Groq Llama, Anthropic Claude)
+- Claude Agent SDK (`claude_agent_sdk`) for autonomous code execution
+
+**Frontend**
+
+- React 18 + TypeScript 5 (strict mode)
+- Material UI v5
+- TanStack Query v5 (server state)
+- Framer Motion (animations)
+- Vite
+
+**Mobile**
+
+- React Native + Expo
+- EAS Build (cloud iOS, local Android)
+- EAS Update (OTA for JS-only changes)
+
+**Infrastructure**
+
+- Docker + Docker Compose
+- Nginx (reverse proxy, SSE support)
+- GCP Cloud Run
+
+## Project layout
+
+```text
+{{BACKEND_DIR}}/
+├── config/          # Django settings, URLs, Celery config
+├── accounts/        # User authentication and profiles
+├── ai/              # AI service (LiteLLM), prompts, usage tracking
+├── <other apps>/    # Project-specific apps
+└── shared/          # Shared utilities, managers, base models
+
+{{FRONTEND_DIR}}/src/
+├── pages/           # Route-level page components
+├── components/      # Reusable UI components
+├── hooks/           # TanStack Query hooks
+├── types/           # TypeScript interfaces
+├── utils/           # API client, helpers
+└── contexts/        # React contexts
+
+specs/               # Feature specs and implementation plans
+```
+
+## Preset-specific skills
+
+Loaded from `presets/django-drf-react/skills/`:
+
+- `django-patterns` — App / model / serializer / view / URL conventions.
+- `ai-integration` — LiteLLM + Claude Agent SDK providers.
+- `celery-async` — Task patterns, scheduling, retries, idempotency.
+- `autodev-pipeline` — The proactive auto-development pipeline.
+- `deploy` — Cloud Run + EAS deployment runbooks.
+- `run-tests` — pytest backend + Jest frontend entry point.
+
+## Quick commands
+
+```bash
+# Backend tests
+cd {{BACKEND_DIR}} && pytest --tb=short
+
+# Frontend tests
+cd {{FRONTEND_DIR}} && npx jest --no-coverage
+
+# TypeScript check
+cd {{FRONTEND_DIR}} && npx tsc --noEmit
+
+# Linting
+cd {{BACKEND_DIR}} && ruff check .
+cd {{FRONTEND_DIR}} && npm run lint
+
+# Start dev (backend)
+cd {{BACKEND_DIR}} && source venv/bin/activate
+watchfiles 'daphne -b 0.0.0.0 -p 8000 config.asgi:application' .
+
+# Start dev (frontend)
+cd {{FRONTEND_DIR}} && npm run dev
+
+# Celery worker
+celery -A config worker -l info
+
+# Celery beat (scheduled tasks)
+celery -A config beat -l info
+```
+
+## Waivers carried by this preset
+
+- **Article III (Simplicity)** — when introducing the provider interface for
+  a new AI model vendor, the second caller rule is relaxed: the interface
+  is required by Article V and Article III must yield to it. Document the
+  waiver in the plan's Complexity Tracking.
+
+<!-- aiadev:auto-stack:start -->
+## Detected stack
+
+_Run `aiadev sync` to populate this block from the project's
+package.json / pyproject.toml / Makefile / docker-compose / workflows._
+<!-- aiadev:auto-stack:end -->