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

[waewoo]

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.

User intent	Example typical composition	Notes
Join an existing project	/aidd-context:00-onboard → /aidd-context:02-project-memory → /aidd-context:11-explore	Onboarding may route to or run project memory first; exploration is an optional map of the project's surfaces, not a mandatory next step.
Implement a small bounded change	/aidd-pm:10-task → /aidd-dev:01-plan → /aidd-dev:02-implement → /aidd-dev:06-test → /aidd-dev:03-assert → /aidd-dev:05-review	A trivial or already well-specified change may skip Task, new test work, or other steps when their preconditions are absent.
Implement a feature	/aidd-pm:04-spec or /aidd-pm:02-user-stories → /aidd-dev:01-plan → /aidd-refine:02-challenge → /aidd-dev:02-implement → /aidd-dev:06-test → /aidd-dev:03-assert → /aidd-dev:05-review → /aidd-vcs:01-commit → /aidd-vcs:02-pull-request	The spec, challenge, test, and other steps are context-dependent. The bundled ship-a-feature recipe and the SDLC orchestrator may provide a shorter or dynamically sequenced path.
Fix a bug	/aidd-pm:09-defect → /aidd-dev:08-debug → /aidd-dev:06-test → /aidd-dev:03-assert → /aidd-dev:05-review	A defect artifact may be unnecessary when an adequate issue already exists. Debug may already include test-driven repair; a separate test step is conditional.
Investigate technical uncertainty	/aidd-pm:05-spike → /aidd-refine:02-challenge → /aidd-pm:10-task or /aidd-pm:04-spec → /aidd-dev:01-plan	Challenge and the follow-up artifact are conditional. The workflow may legitimately stop after the spike when the evidence says not to implement.
Deliver autonomously	/aidd-orchestrator:01-sdlc	The orchestrator owns framing, delivery, checking, delegation, and sequencing; users should not manually replay its internal path.

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.