[AAASM-113] 📝 (docs): SDK adapter authoring guide

[Chisanan232]

Description

Adds the framework adapter authoring guide and a runnable reference template adapter (JIRA AAASM-113).

• docs/guides/authoring-adapters.md — 8-section guide: (1) prerequisites, (2) quickstart from the template, (3) FrameworkAdapter four-method interface reference, (4) the duck-typed GovernanceInterceptor contract + conventional event methods, (5) hook patterns (callback / wrapper / monkey-patch with pros/cons), (6) testing via the in-tree aasm adapter validate contract validator + lifecycle unit tests, (7) entry-point publishing and aa-adapter-<framework> naming, (8) PR checklist. Wired into mkdocs nav and the guides index.
• examples/adapters/template_adapter.py — minimal, runnable FrameworkAdapter implementing all four required methods over a self-contained fictional framework. Runs offline with no third-party deps; passes aasm adapter validate 7/7.

The guide is grounded only in real, importable code: agent_assembly/adapters/base.py, registry.py, and cli/adapter_validator.py.

Scope note for reviewers: the ticket referenced an AdapterTestHarness fixture. No such class exists in the codebase today. Rather than invent it, the testing section documents the two real mechanisms (the aasm adapter validate contract validator and stub-interceptor lifecycle tests) and explicitly flags the gap. Re-scope if a shared harness is desired.

Type of Change

• 📚 Documentation update

Breaking Changes

• No

Related Issues

• Related JIRA ticket: AAASM-113

Testing

• Manual testing performed
• No tests required (explain why)

Validation performed on the changed files:

• examples/adapters/template_adapter.py runs end to end (python examples/adapters/template_adapter.py) and imports cleanly.
• aasm adapter validate examples/adapters/template_adapter.py → 7 passed, 0 failed.
• ruff check + ruff format --check + mypy on the template adapter all clean.
• mkdocs build succeeds with the new page in nav (no link/nav errors).

No tests added: this PR is documentation + an illustrative example; the template adapter's __main__ is itself a self-checking lifecycle demo, and the repo's mypy/ruff hooks cover it.

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• Documentation updated if needed
• All tests passing — full-suite/pre-commit mypy hook is red on pre-existing errors in untouched files (client/gateway.py, core/assembly.py, types.py, etc.); the changed template adapter is mypy-clean in isolation.

🤖 Generated with Claude Code

[Chisanan232]

🤖 Claude Code — PR review

Ticket: AAASM-113 — F69: SDK adapter authoring guide. Epic AAASM-13.

CI — ✅ green

Analyze (python) ✅ · Build documentation (PR, no deploy) ✅; deploy jobs correctly skipped on a PR. No code-level CI failure.

⚠️ The repo's pre-commit mypy hook is red on 34 pre-existing errors on master (client/gateway.py, core/assembly.py, types.py) — confirmed present on pristine base b2ee749, none in this PR's files. That's a broken-master condition, not introduced here; worth its own cleanup ticket. This PR's new file is mypy-clean in isolation.

Scope vs. acceptance criteria

AC	Status	Evidence
Guide covers all 4 FrameworkAdapter abstract methods with examples	✅	grounded in agent_assembly/adapters/base.py (exact signatures)
GovernanceInterceptor event types	✅ (reality-framed)	it's an empty typing.Protocol (no fixed enum) — documented the conventional methods real adapters call, sourced from adapters/crewai/patch.py, framed honestly as conventions
Hook patterns (callback/wrapper/monkey-patch)	✅	included with pros/cons
Reference template adapter, runnable	✅	examples/adapters/template_adapter.py runs full lifecycle; aasm adapter validate → 7 passed / 0 failed
Publishing / entry-points / naming	✅	grounded in adapters/registry.py (group agent_assembly.adapters)
PR checklist	✅	included
AdapterTestHarness documented	⚠️ re-scope	this class does not exist in the tree. The agent did not invent it — documented the real aasm adapter validate path instead and flagged the gap in-guide

2 atomic commits (template adapter + guide). ruff + ruff format + mypy clean on the new file; mkdocs build OK.

Re-scope items for the owner

1. AdapterTestHarness — decide whether a shared test-harness fixture is actually wanted (new ticket), or the documented aasm adapter validate approach is the intended testing story.
2. Minor doc bug in existing CONTRIBUTING: it says aasm adapter-validate (hyphen); the real CLI is aasm adapter validate (subcommand). The guide uses the correct form.
3. The pre-existing master mypy debt (separate cleanup ticket).

Readiness

Ready to merge pending one Pioneer-team approval, with the AdapterTestHarness AC consciously re-scoped (the harness doesn't exist yet). Everything else is complete and grounded in real, importable code.

Recorded as a review note; no formal approval submitted.