Async-dev
Single skill that drives the async development pipeline end to end. Three sub-flows live inside, accessed through one router:
| Sub-flow | When |
|---|---|
| Setup | Repo not yet configured for async dev; user wants to install. |
| Run | An issue is labeled to-implement (or commented @claude /implement); no open PR closes it. |
| Review | A PR is labeled to-review (or commented @claude /review); change requests pending. |
Iron rule
You are the router until you commit to a sub-flow. Once committed, run that sub-flow's actions in order; do not jump back to routing mid-flow.
Routing: hybrid contract
Walk in order. First match wins.
- Argument override. If the arguments contain exactly
setup,run, orreview(case-insensitive, standalone token), route there immediately. This is the explicit override the CI workflow uses. - Trigger env. When invoked from CI (
GITHUB_EVENT_NAMEset):- Label payload
to-implement→run. - Label payload
to-review→review. - Comment body matches
@claude /implement(or/aidd-dev:02-implement) →run. - Comment body matches
@claude /review→review.
- Label payload
- Repo state.
- Missing
.github/workflows/aidd-async.ymlAND missing.claude/aidd-orchestrator.json→setup. - Open PR closes the referenced issue →
review. - Fresh issue with no linked PR + intent to implement →
run.
- Missing
- Natural-language intent. Verbs in the user prompt:
install / configure / set up / bootstrap / rotate config→setup.implement / run / process / handle queue / claude on issue→run.address review / iterate on PR / fix comments / handle review→review.
Tie-break: most-specific signal wins (PR number > label > free-text keyword > config absence).
If none of the above resolves, surface the three sub-flows with one-line triggers and ask the human which to run. Never proceed blindly.
If repo state contradicts intent (e.g. user says "run" but .claude/aidd-orchestrator.json is absent), surface the conflict before delegating; never silently switch.
See references/routing.md for the full decision tree, signal precedence, and edge cases.
Sub-flows
Setup (11 actions)
Sets up async-dev in a repo. Detects context, asks for runtime parameters, generates artefacts, bootstraps labels, installs user-scope plugins (local mode), configures secrets (remote mode), schedules the poll routine (local mode), commits and pushes the generated files, and offers a smoke test on the chosen issue.
| # | Action | Role |
|---|---|---|
| 01 | detect-context | Identify repo, default branch, existing config, CI permissions |
| 02 | ask-config | Collect runtime parameters (mode, auth, labels, schedule, agents) |
| 03 | generate-workflow | Emit .github/workflows/aidd-async.yml from assets/setup/workflow-template.yml |
| 04 | generate-local-script | Emit poll/daemon scripts (local mode only) from assets/setup/local-*-template.sh |
| 05 | write-config | Persist .claude/aidd-orchestrator.json from assets/setup/config-template.json |
| 06 | bootstrap-labels | Create to-implement / to-review / claude/* labels via gh |
| 07 | install-user-scope-plugins | Install aidd-orchestrator + aidd-dev at user scope (local mode) |
| 08 | configure-remote-secrets | Sync CLAUDE_CODE_OAUTH_TOKEN, AIDD_BOT_TOKEN, etc. (remote mode) |
| 09 | bootstrap-scheduling | Schedule the poll routine (local) or rely on workflow webhook (remote) |
| 10 | commit-and-push | Stage generated files, conventional-commit, push |
| 11 | smoke-test | Label a throwaway issue with to-implement; verify the pipeline reacts |
Files: actions/setup/01-detect-context.md ... actions/setup/11-smoke-test.md.
Default flow: 01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 → 09 → 10 → 11. Actions self-skip when their preconditions are not met (e.g. 07 skips in remote mode, 08 skips in local mode).
Run (6 actions)
Executes one orchestration cycle on a fresh issue. Reads ready issues, resolves blockers, acquires the lock label, hands the implementation to the active SDLC orchestration capability, observes the resulting git and VCS state, and emits a run-result.json summary the workflow's post-job consumes.
| # | Action | Role |
|---|---|---|
| 01 | poll-ready | Find the next issue with to-implement, no claude/working, no open closing PR |
| 02 | resolve-deps | Check linked issues / dependencies; abort if blocked |
| 03 | acquire-lock | Apply claude/working label; refuse if already held |
| 04 | check-sdlc | Verify an SDLC orchestration capability is loaded |
| 05 | delegate-sdlc | Hand the issue to the SDLC capability; observe outcome |
| 06 | write-audit | Emit run-result.json for the workflow's post-job |
Files: actions/run/01-poll-ready.md ... actions/run/06-write-audit.md.
Default flow: 01 → 02 → 03 → 04 → 05 → 06. One cycle per ready issue.
Review (4 actions)
Closes the loop after a PR is opened by the run flow. Detects when to keep auto-fixing and when to hand off to a human. Idempotent on re-runs.
| # | Action | Role |
|---|---|---|
| 01 | collect-comments | Read all PR + linked-issue comments newer than the last bot activity |
| 02 | detect-stop | Decide stop vs continue using references/review/stop-conditions.md |
| 03 | fix-iteration | Delegate fixes to the SDLC capability; reply to each addressed comment |
| 04 | finalize | Resolve threads, post the structured summary, set claude/awaiting-review or blocked |
Files: actions/review/01-collect-comments.md ... actions/review/04-finalize.md.
Default flow: 01 → 02 → (03 → 01 loop if continue) → 04. Stop conditions in references/review/stop-conditions.md.
Rules
- Exactly one sub-flow runs per invocation. The router commits, then runs that sub-flow to completion.
- Never inline a sub-flow's logic at the router level. The router decides; the actions execute.
- Each action enforces its own pre-flight checks and exit codes. The router never enforces post-conditions.
- If a sub-flow aborts, surface the exit state; do not retry by switching sub-flows.
- For batch invocations (e.g. multiple ready issues), the workflow re-invokes the skill once per item; the router does not loop.
Say when this orchestration is over
Once the sub-flow you committed to has run its last action, and only then, run:
shellecho "aidd:step-end aidd-orchestrator:00-async-dev"
No host reports when an orchestration finished. A skill call's own result comes back in a tenth of a second, which is the dispatch and not the completion, so a measurement that never hears this ends the run at the next pause — and an orchestration is mostly pauses. Everything it drove afterwards then reads as work that belonged to nothing.
References
references/routing.md- full decision tree, signal precedence, conflict resolution.references/setup/auth-modes.md- local vs remote auth contracts.references/setup/claude-action-auth.md-claude-code-actiontoken setup.references/setup/local-mode-scheduling.md- poll routine options.references/review/stop-conditions.md- when the review loop hands off to a human.
Assets
Setup-only templates copied into the target repo by the setup sub-flow:
assets/setup/workflow-template.yml-.github/workflows/aidd-async.ymlskeleton.assets/setup/local-poll-template.sh- local-mode poll script.assets/setup/local-daemon-template.sh- local-mode daemon script.assets/setup/config-template.json-.claude/aidd-orchestrator.jsonskeleton.
Test
Each sub-flow's final action carries a ## Test block that exercises the full sub-flow with mocked dependencies.
