[DRAFT] feat: add AdaL harness support (native discovery, tool mapping)

[Ricardoran]

This PR MUST target the dev branch, not main. main is the
released branch; active work lands on dev first. PRs opened against
main will be asked to retarget dev before review.

Who is submitting this PR? (required)

Field	Value
Your model + version	anthropic-claude-opus-4-6 (Claude Opus 4.6)
Harness + version	AdaL CLI v1.0.0-dev (@sylphai/adal-cli)
All plugins installed	None (clean environment)
Human partner who reviewed this diff	Haoran Zhang (@Ricardoran)

What problem are you trying to solve?

AdaL (@sylphai/adal-cli) is a multi-model agentic CLI with native skill discovery and a plugin marketplace. Its plugin system already reads .claude-plugin/marketplace.json and discovers skills/ recursively — the same progressive-disclosure architecture Codex uses. This PR adds the minimal tool-mapping and documentation so AdaL users can install and discover Superpowers skills through their existing plugin lifecycle.

⚠️ IMPORTANT — This is a DRAFT for maintainer shape review, not a completed integration.

AdaL currently discovers and surfaces all Superpowers skills in its prompt context every session. However, autonomous skill selection (the model reading using-superpowers → brainstorming without explicit user prompting) does not yet pass the clean-session acceptance test. We are filing this draft to:

1. Get maintainer feedback on whether this native-discovery shape is welcome
2. Share measured evidence of what works and what doesn't
3. Determine whether to proceed with AdaL-side routing improvements before re-submitting

AdaL is NOT listed in the main quickstart harness list. The README install section is marked (proposed — acceptance test in progress).

What does this PR change?

1. skills/using-superpowers/references/adal-tools.md — tool mapping (Superpowers actions → verified AdaL tools)
2. skills/using-superpowers/SKILL.md — one line in Platform Adaptation section
3. docs/README.adal.md — install/usage documentation with honest status (0/8 acceptance)
4. README.md — proposed install section (NOT in quickstart list, marked "acceptance test in progress")
5. tests/adal/test-adal-integration.sh — static file/content verification test

No new manifest, hooks, injector code, or dependencies.

Is this change appropriate for the core library?

Yes — this is a new harness integration (the category explicitly allowed by contributor guidelines). It adds only a tool-mapping reference, documentation, and one SKILL.md pointer. It does not modify skill behavior, add dependencies, or claim capabilities that don't exist.

What alternatives did you consider?

1. Shape B (in-process injector): AdaL has no plugin API for message mutation. Rejected.
2. Shape A (session-start hook): AdaL has no hook system. Not applicable.
3. Full bootstrap injection: Would require AdaL core changes — out of scope for this PR.
4. Waiting until autonomous selection is reliable: Considered, but filing early to get shape feedback from maintainers.

Does this PR contain multiple unrelated changes?

No. All changes serve AdaL harness support.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• No prior AdaL-related PRs or issues found

Search commands run:

gh pr list --repo obra/superpowers --state all --search "AdaL OR adal OR sylph" --json number,title,state
gh issue list --repo obra/superpowers --state all --search "AdaL OR adal OR sylph" --json number,title,state
# Both returned empty results

Environment tested

Harness	Harness version	Model	Model version/ID
AdaL CLI	v1.0.0-dev	Claude	anthropic-claude-sonnet-4-6

Tool-name verification evidence

AdaL tool names were derived from a live headless session. The model was asked to list its tools:

adal-dev -q "List the exact machine names of every tool you can call, one per line." -m anthropic-claude-sonnet-4-6 -o text

Confirmed tool names used in adal-tools.md:

• read_file ✅
• create_file ✅
• replace_by_string ✅
• rewrite_file ✅
• delete_lines ✅
• bash ✅
• grep ✅
• glob ✅
• fetch_url ✅
• web_search ✅

Tools NOT claimed (verified absent or not model-callable):

• Skill — no dedicated skill tool; read_file is the mechanism
• Task / TodoWrite — not available; fallback to plan files documented
• Subagent dispatch tool — no model-callable equivalent; documented as degraded

New harness support — HONEST STATUS

What works ✅

• Install/discovery: marketplace add obra/superpowers → clone → plugin install → all 14 skills appear in AdaL's <SKILLS> prompt block every session. Verified via headless query: model lists all superpowers skill names.
• Tool mapping: All tool names verified from live sessions (see evidence above).
• Skill readability: Model can read_file on any installed SKILL.md path and follows the instructions when prompted.

What does NOT yet work ❌

The clean-session acceptance test fails. In 8 fresh sessions with the exact prompt "Let's make a react todo list", the model proceeded directly to implementation without reading using-superpowers or brainstorming first. 0/8 sessions showed autonomous skill activation.

Root cause identified: AdaL's Tier 1 system prompt contains strong action directives ("ACT, don't narrate", "call the appropriate tool NOW") that override the passive skill listing in Tier 2. When the user explicitly asks to "check skills first" (1/1 session), the model immediately reads brainstorming/SKILL.md and follows the workflow correctly.

Measured results

Condition	Skill reads before implementation	Sessions
Standard prompt, all tools	0%	0/5
Standard prompt, read-only tools	0%	0/3
User-primed prompt ("check skills first")	100%	1/1

Non-goals (explicit)

• ❌ No forced workflow execution
• ❌ No session-start hooks or injectors
• ❌ No bootstrap injection code
• ❌ No AdaL core changes
• ❌ No new plugin manifest
• ❌ No third-party dependencies
• ❌ No skill-body edits (only the one-line Platform Adaptation pointer)
• ❌ No fabricated acceptance transcript
• ❌ No claim of full harness support — marked as proposed/draft throughout

Evaluation

• Initial prompt: "Let's make a react todo list" (canonical acceptance test)
• Sessions run: 8+ clean sessions across multiple preamble variants
• Outcome: Autonomous selection fails; discovery/install/readability works

Rigor

• This is NOT a skills change — adds tool-mapping reference only
• I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language)
• Acceptance test passing — NOT YET (documented above)

Human review

• A human has reviewed the COMPLETE proposed diff before submission

---

Questions for maintainers

1. Is the native-discovery shape (Codex-like) welcome for AdaL, given that AdaL reads .claude-plugin/marketplace.json and surfaces skills natively, but autonomous selection is not yet reliable?

2. Would you accept this integration once autonomous skill routing passes the acceptance test (via an AdaL-side prompt improvement), or does the upstream integration need to carry bootstrap injection code itself?

3. Is there precedent for a "discovery-ready" harness that documents install/mapping/docs ahead of full acceptance-test compliance?

4. Is the tool mapping accurate and complete from your perspective?

We are actively working on AdaL's generic skill-routing to make autonomous selection reliable. Once that lands, we will update this PR with a passing acceptance transcript.

---

🌸 Generated with AdaL