docs(framework): make intent-based skill workflows discoverable #931

Problem

AIDD documents individual capabilities and exposes a few starting points, but a user who begins with an outcome rather than a skill name still has to infer how capabilities compose.

Today the repository provides:

• a capability inventory in docs/CATALOG.md;
• project-aware next-step guidance in aidd-context:00-onboard;
• project/tooling mapping in aidd-context:11-explore;
• reusable how-to sheets through aidd-context:12-cook;
• end-to-end execution through aidd-orchestrator:01-sdlc.

Those responsibilities are useful but leave a gap between them. For common intents such as joining an existing project, fixing a bug, making a bounded change, investigating uncertainty, reviewing or auditing a codebase, a user cannot readily answer:

Which capabilities should I compose, in what order, which steps are conditional or optional, when can I stop, and when should I use a recipe or the orchestrator instead?

The current README points to onboarding, the full SDLC flow, and a small set of bundled recipes, but does not provide an intent-oriented index across the existing surface. 00-onboard chooses a project-specific next step; 11-explore explicitly maps without prescribing; 12-cook lists or applies a named recipe. None is the human-readable bridge from user intent to a typical composition of capabilities.

Illustrative compositions

The examples below make the composition problem concrete. They are illustrative compositions, not normative pipelines or a second workflow source of truth. The actual path may be shorter, branch, or stop early depending on project state, existing artifacts, risk, and user authority. Where a recipe or orchestrator owns the detailed flow, the table points to that boundary rather than prescribing its internals.

These examples illustrate why capability discovery is different from selecting one entry skill: the user also needs guidance about transitions, optionality, stopping conditions, and the boundary between manual composition, recipes, and orchestration. They do not define another canonical SDLC.

Scope

• Add the smallest architecture-consistent entry point for discovering workflows from user intent, whether that is a compact README/index section, an intent-to-recipe guide, improved recipe discoverability, or another existing documentation location.
• Cover representative intents across project setup, requirements, issue/bug work, bounded changes and features, refactoring, investigation, review/audit, and autonomous delivery.
• Include a small, concrete, non-normative set of intent → multi-capability examples that demonstrates composition while referring to canonical skills, recipes, and orchestrators for actual behavior.
• Describe workflows as typical guidance, marking required, conditional, optional, manual, and orchestrated steps where relevant. Include legitimate shorter paths and meaningful stop conditions.
• Make the choice between individual skills, a bundled/project recipe, aidd-context:00-onboard, aidd-context:11-explore, and aidd-orchestrator:01-sdlc explicit where their responsibilities differ.
• Link to the existing canonical skills, recipes, and orchestrator rather than restating their contracts.
• Prefer reusing or deriving from canonical recipe/skill metadata where practical, so the documentation does not become a second independently maintained workflow definition.

Acceptance criteria

• A user can start from a supported intent and reach a concrete, runnable next choice without already knowing a skill name.
• The guidance distinguishes project-aware onboarding, capability exploration, named recipes, manual skill composition, and autonomous SDLC orchestration.
• Representative intent paths identify sequence, conditional/optional steps, valid shorter paths, and completion or stop conditions without presenting one universal pipeline as mandatory.
• Every referenced skill, recipe, and orchestrator exists on the supported branch and links resolve.
• The change does not duplicate docs/CATALOG.md, the 00-onboard project-state logic, or individual skill contracts.
• The chosen representation has an explicit maintenance/source-of-truth rule, or is generated from canonical data where the repository already supports that pattern.
• Documentation validation passes, including the repository's Markdown link checks and any relevant catalog/generated-file checks.

Prior art in this repo

• README.md quick start and recipe links expose onboarding, the full SDLC flow, and a small set of bundled recipes, but not an intent-oriented composition index.
• plugins/aidd-context/skills/00-onboard/SKILL.md owns project-state scanning, assessment, presentation, and running the selected next step.
• plugins/aidd-context/skills/11-explore/SKILL.md maps installed surfaces and explicitly says to map, not prescribe the next step.
• plugins/aidd-context/skills/12-cook/SKILL.md owns listing, authoring, researching, and applying project or bundled recipes.
• docs/CATALOG.md is the exhaustive capability inventory, not a user-intent workflow guide.
• docs/ARCHITECTURE.md assigns sequencing across concerns to orchestrators, keeps recipe skills self-contained, and requires cross-plugin capability discovery at runtime.
• Existing bundled recipes, including start-a-project.md and ship-a-feature.md, demonstrate the desired multi-capability format for selected flows.
• Discussion #866 maps current capabilities, tracked gaps, and intentional boundaries. This issue is narrower: operational discovery from a user's intent, not another capability map or a request to implement every uncovered row.
• #411 established guided onboarding; #883 is about resolving onboarding providers at runtime, not static intent guidance.
• #416 and PR #521 concern recipe research/application and recipe maintenance, not intent-to-recipe discoverability.
• #146 concerns runtime capability-driven orchestration, not documentation for users choosing between manual composition, recipes, and orchestration.

Out of scope

• Replacing or duplicating docs/CATALOG.md, skill descriptions, recipe contracts, or project-aware onboarding.
• Defining a new universal SDLC pipeline or requiring every intent to run the same sequence.
• Moving orchestration logic into documentation, introducing a new workflow engine, or expanding the boundary discussed in Discussion #779.
• Adding a new baseline-validation phase; pre-change validation remains a separate concern unless existing architecture proves it is required here.
• Creating a large static matrix that independently restates recipe or orchestrator behavior without a source-of-truth strategy.
• Implementing new skills, recipes, or orchestrator behavior as part of this documentation/discoverability issue unless the investigation shows a narrowly missing canonical entry is required.