AQAF 1.1 — Extensible Architecture Assessment Framework

Local-first and source-backed architecture review for AI-assisted developers.

Catalog: 19 app profiles in four packs. These have mixed detector coverage; not 19 complete architecture analyzers. AQAF reports a provisional, unvalidated heuristic index, not a certification.

Repository Owner Manual and training studio

Start with REPOSITORY_TUTORIAL_START_HERE.md and then DOCS_AGENT_HANDOFF.md. For a genuine file-by-file introduction, start at docs/handbook/README.md and docs/handbook/23-owner-guided-file-walkthrough.md. An automatically generated file inventory describes each repository file, its role and how it should be edited. Six man pages ship under man/. The public website includes /docs/ and /packages/ pages generated by scripts/docs/build_handbook.py. For screencast production, start at tutorials/MASTER_AGENT_HANDOFF.md and tutorials/EP02_FULL_SCRIPT.md.

python3 scripts/docs/build_handbook.py
python3 scripts/docs/verify_handbook.py
bash scripts/docs/rehearse_tutorial.sh
# Windows PowerShell: .\scripts\docs\rehearse_tutorial.ps1

HTML and public pack pages are included but not hosted until you deploy the website. These are documentation additions to AQAF 1.1.0; scanner rules and scoring have not been changed.

Try it

python tools/aqaf.py --version
python tools/aqaf.py profiles list
python tools/aqaf.py packs list
python tools/aqaf.py /path/to/repo --pack web --format md --output ARCHITECTURE_REPORT.md
python tools/aqaf.py /path/to/repo --profile rust_app --format json
python examples/advanced/run_lab.py

The Python package can be installed locally from the included wheel. The npm package wraps the same Python scanner, not a separate JS engine, and requires Python 3.9+.

Four specialist packs

• web — APIs, SaaS, npm libraries, WordPress, browser extensions.
• mobile — Swift and Android.
• systems — Rust, Windows client/server, desktop, IoT, multi-repo.
• automation — Google Apps Script, CLI, scrapers, AI pipelines, MCP servers.

See START_HERE_1_1.md, packs/, docs/PROFILE_AND_PACK_AUTHORING.md, distribution/README.md and HANDOFF_1_1_MASTER.md. Advanced examples live in examples/advanced/. The website source and optional Cloudflare claim/contact backend are under website/.

Strict safeguards

No target-code execution, offline-by-default, read-only scans, justified suppressions, explicit source/uncertainty and manual validation. External profile files are data only and cannot replace built-ins. Source-backed design choices do not make the detection thresholds validated.

Licensed MIT. AQAF is independent and not affiliated with OpenAI, the book authors or example projects.

---

Original 1.0 reference notes

AQAF 1.0 — Architecture Quality Assessment Framework

The quality layer for AI-built software.

AQAF helps builders who use Codex, Cursor, Claude Code, and other coding agents inspect architectural risks, choose a defensible target structure, create test-first refactor handoffs, and prevent known regressions. It is a local-first Python CLI plus reference-backed architecture rules and optional agent workflows.

Important: AQAF 1.0 is an independent, heuristic architecture-review assistant, not a certified software quality, security, or performance assessment. The 0–100 index is provisional, not independently calibrated. Passing a scan does not mean production ready.

5-minute start (no account, no API key, no upload)

Requires Python 3.9+.

# Extract this folder and run directly (no installation necessary):
python3 tools/aqaf.py /path/to/project --format md --output architecture-review.md

# Structured report for agents or automation:
python3 tools/aqaf.py /path/to/project --format json --output aqaf-report.json

# Optional install from local folder (offline after wheel build dependencies are available):
python3 -m pip install .
aqaf --version
aqaf /path/to/project --format md

Use Codex next: copy handoffs/01_assess_repository.md into your agent with the report. Codex should return observed facts, unknowns, an architecture trade-off, top risks, tests, a small safe plan, and ADR candidates. Do not ask it to blindly rewrite your repo.

What the tool actually does

Capability	1.0 status
Heuristic repo scan, no target code execution	Implemented
Product profile inference + explicit override	Implemented; may misclassify
Provisional quality index and confidence notes	Implemented; not calibrated
Structured JSON, Markdown, SARIF	Implemented; SARIF is basic and not a security certification
Baseline new vs existing finding comparison	Implemented
Suppressions with required written reason	Implemented
Opt-in CI failure only for new high/medium findings	Implemented
Architecture bibliography, rule/source mapping	Included; references do not validate detectors
Swift and Rust profiles + Codex review skills	Included; mostly review guidance and heuristics
Real repository benchmarks, third-party accuracy validation	Not done
Hosted UI, GitHub Marketplace listing, payment, licensing server	Not done
Automatic safe fixes, guaranteed scalability	Not offered

Baseline workflow

# Save baseline snapshot in a trusted artifacts directory, NOT auto-edit your code.
python3 tools/aqaf.py ../my-app --format json --output baseline.json

# Compare against the original baseline; only *new* findings can fail CI.
python3 tools/aqaf.py ../my-app --format json --baseline baseline.json --fail-on new-high --output new-report.json

# Generate best-effort SARIF for SARIF-aware consumers:
python3 tools/aqaf.py ../my-app --format sarif --output report.sarif

A finding fingerprint changes if its evidence text changes; baseline comparison is intentionally simple, not semantic tracking. Suppressions live in ../my-app/.aqaf.json (see templates/aqaf-config.example.json) and should be documented/periodically reviewed.

Product profiles

SaaS/web, WordPress plugin, Android, AI pipelines, desktop utility, CLI, scraper/ETL, Swift, and Rust. The target is never “microservices by default.” See product_profiles/, docs/methodology.md, and docs/bibliography.md.

Agent skill/handoff material

• AGENTS.md — concise core quality guardrails (for development of this framework; adapt for target app).
• skills/ — architecture assessment, refactor planning, Swift, Rust, and safe framework improvement.
• handoffs/ — complete product/research/dev/release/sales/support Codex prompts with acceptance criteria.
• governance/CORE_CONTRACT.md — rules that agents may not change casually.
• references/source_registry.json + rules/catalog.json — source-to-rule lineage.

Distribution / business docs

launch/ contains a launch checklist, rollout experiments, privacy/support policy drafts, funnel, and readiness gate. marketing/ contains landing page, pricing hypotheses, content calendar, launch email sequence, demo scripts, objections and customer interview prompts. These are draft assets, not claims backed by customers or conversion data.

Development and validation

python3 -m unittest discover -s tests -v
python3 -m pip install .
python3 -m aqaf --version

Optional build step if build is installed: python3 -m build. See docs/validation_plan.md, launch/RELEASE_GATE.md and tests/ before release.

Privacy and license

The baseline scanner does not make network requests and does not execute scanned repo code. Scan output may contain local paths and summaries; review before sharing. Python source is currently MIT licensed. Commercial documentation, brand/trademark rights, paid service terms and redistribution terms need a deliberate business decision before selling (see launch/IP_AND_LICENSE.md).

Documentation map

• QUICKSTART.md — first repo scan + Codex workflow
• docs/bibliography.md and references/ — books, standards, references and scope
• docs/methodology.md, docs/scoring.md — limits of the assessment
• governance/ — backward compatibility and rule promotion
• marketing/ — ready-to-edit launch materials
• handoffs/ — 15 agent handoffs and expected deliverables
• launch/ — operator checklist and release gate

No publisher, author, vendor, or reference repository has endorsed AQAF.

Version note: 1.0.0 is the first public-facing version number, rebased from internal 2.2.0. The API and rule engine have not undergone independent validation; see PUBLIC_RELEASE_NOTES.md.

First public release website

The full owner release includes website/ (Cloudflare Worker + D1 forms, a founding-review request form, contact form, responsive UI) and offer/ (free review fulfillment template). Website deployment is intentionally operator-configured and cannot accept real submissions without D1 + Turnstile + verified operator contact. See HANDOFF_MASTER.md, PUBLIC_RELEASE_GATE.md and website/ops/DEPLOY.md.