--- name: AI-DLC Portfolio slug: ai-dlc-portfolio category: AI Engineering description: AI-DLC Portfolio coordinates multiple AI-DLC workflows across repositories and worktrees with a catalog of evidence-backed projects, dependencies, intents, and dispatch state. Use it to initialize a portfolio workspace, register work, create worktrees, validate readiness, and monitor parallel sessions. github: "https://github.com/awslabs/cli-agent-orchestrator/tree/main/examples/aidlc-portfolio/skills/aidlc-portfolio" language: Python stars: 1087 forks: 226 install: "npx degit https://github.com/awslabs/cli-agent-orchestrator/tree/main/examples/aidlc-portfolio/skills/aidlc-portfolio ~/.claude/skills/aidlc-portfolio" installs_to: ~/.claude/skills/aidlc-portfolio source_path: examples/aidlc-portfolio/skills/aidlc-portfolio/SKILL.md collection_size: 18 category_size: 2451 collection_url: "https://dirskills.com/collections/awslabs/cli-agent-orchestrator" added: 2026-08-21T05:13:19.056Z last_synced: 2026-08-21T05:13:19.056Z canonical_url: "https://dirskills.com/skills/ai-dlc-portfolio" --- # AI-DLC Portfolio AI-DLC Portfolio coordinates multiple AI-DLC workflows across repositories and worktrees with a catalog of evidence-backed projects, dependencies, intents, and dispatch state. Use it to initialize a portfolio workspace, register work, create worktrees, validate readiness, and monitor parallel sessions. **Install:** ```bash npx degit https://github.com/awslabs/cli-agent-orchestrator/tree/main/examples/aidlc-portfolio/skills/aidlc-portfolio ~/.claude/skills/aidlc-portfolio ``` ## README # AI-DLC Portfolio Maintain a thin control plane around existing AI-DLC workflows. Never replace or modify the child workflow engine. Resolve every relative resource path against the directory containing this `SKILL.md`. In the commands below, set `SKILL_DIR` to that absolute directory: ```bash SKILL_DIR=/absolute/path/to/skills/aidlc-portfolio ``` ## Operating Rules 1. Run `"$SKILL_DIR/scripts/portfolio.ts"` for every portfolio mutation. 2. Keep portfolio state at `/portfolio` and project checkouts at `/repositories`. 3. Give each active child intent its own path under `/worktrees`. 4. Dispatch one `aidlc_runner` per child intent with CAO `assign`. 5. Treat child AI-DLC state as opaque. Never edit `aidlc-state.md` or derive its next stage. 6. Require evidence and confidence for discovered catalog relationships. 7. Ask the human about missing or uncertain business facts before verification. 8. Run dispatch validation before starting or resuming a child runner. 9. Treat the portfolio supervisor as the sole shared-memory approval authority. 10. Never merge worktree-local `project.md` or `team.md` changes. 11. The supervisor owns bootstrap; the operator should not have to prepare the workspace, repository checkout, intent files, worktrees, or child harness. 12. Never dispatch until portfolio discovery has explicit human confirmation. 13. Never answer a child AI-DLC question without human input. 14. Stage, project, and verify child harnesses only through `harness` commands. 15. Advance parent work only through the persisted portfolio lifecycle. 16. Require one structured result per child and pass convergence before Learn. ## Bootstrap From Work Items The normal entry point is an operator naming a repository and one or more work items. Perform setup on their behalf: 1. Derive a stable portfolio ID from the repository and sorted work-item IDs. 2. Use the terminal's launch directory as the portfolio root unless the operator explicitly supplies another root. Never create a nested root. 3. Run `init` against that exact root; never hand-create portfolio state. 4. Create a fresh canonical checkout under `/repositories`. Do not reuse, clean, reset, or remove an existing user checkout or worktree. 5. Inspect the work items and register the project, dependencies, and one portfolio intent per independent work item using templates and utility commands. 6. Create each worktree through `worktree create`. 7. Locate the Claude AI-DLC distribution at `$HOME/Project/aidlc-workflows/dist/claude`. Run `harness stage`, `harness sync`, and `harness verify` to project one manifest-pinned Opus 5 runtime into every worktree. 8. Run `doctor` and `dispatch check`, then assign all dependency-ready `aidlc_runner` sessions concurrently with CAO `working_directory` set to each absolute worktree. 9. Report the generated root, intent IDs, worktree paths, and terminal IDs. The operator owns creation of the empty parent/root directory and launches the supervisor from it. Ask them only when a required repository, work item, credential, or AI-DLC distribution cannot be discovered. Do not turn routine bootstrap inside the root into operator instructions. ## Initialize ```bash bun "$SKILL_DIR/scripts/portfolio.ts" init \ --root /absolute/workspace \ --id portfolio-id \ --name "Portfolio Name" ``` Then run: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" doctor --root /absolute/workspace ``` Initialization is explicit and idempotent. Never use a hook to create a workspace. For a workspace created before lifecycle state schemaVersion 2, migrate once: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" lifecycle migrate --root ``` Read [portfolio-lifecycle.md](references/portfolio-lifecycle.md). After every startup or callback, inspect the durable phase and exact next action: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" lifecycle status --root ``` ## Discover And Register Read [catalog-model.md](references/catalog-model.md) before discovering or changing projects, components, capabilities, or dependencies. Read [coordination-rules.md](references/coordination-rules.md) before creating child intents, worktrees, or dispatches. Inspect technical evidence before asking questions. Use the templates under `assets/templates`, then register validated files: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" project register --root --file bun "$SKILL_DIR/scripts/portfolio.ts" dependency add --root --file bun "$SKILL_DIR/scripts/portfolio.ts" intent create --root --file ``` Record unresolved questions under `/portfolio/questions`. Support `Unknown`, `Defer`, and referral to another stakeholder. Do not upgrade a fact from `discovered` or `proposed` to `verified` without human approval. After catalog registration, render `assets/templates/discovery-decision.yaml`. Record the human's decision for organization, business outcomes, business capabilities, and the complete dependency list: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" discovery confirm \ --root --file ``` For every `unknown` or `deferred` disposition, the corresponding fact name must appear in `acceptance.unknowns` or `acceptance.deferrals`. The utility stores a catalog revision; any later catalog change makes confirmation stale and blocks dispatch until the human reviews it again. Project registration records a canonical checkout; it does not clone one. Before worktree creation, ensure the registered path exists under `/repositories` and is a Git repository. ## Harness Lifecycle Read [harness-lifecycle.md](references/harness-lifecycle.md) before staging or updating child runtimes. Stage the source distribution after registering intents and creating their worktrees: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" harness stage \ --root \ --source "$HOME/Project/aidlc-workflows/dist/claude" bun "$SKILL_DIR/scripts/portfolio.ts" harness sync --root bun "$SKILL_DIR/scripts/portfolio.ts" harness verify --root ``` The staged manifest records source revision, source and staged hashes, overlay revision, and staging time. The default overlay pins the Claude `opus[1m]` alias to `global.anthropic.claude-opus-5[1m]`. Use `--project` and `--intent` to sync or verify a subset. Never bypass a tracked-path refusal. Reconcile project-owned `.claude/` or `aidlc/` content explicitly before retrying. ## Dispatch Create or validate a worktree: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" worktree create \ --root --project --intent \ --branch --base bun "$SKILL_DIR/scripts/portfolio.ts" harness verify \ --root --project --intent bun "$SKILL_DIR/scripts/portfolio.ts" dispatch check \ --root --project --intent ``` The worktree must pass harness verification and dispatch validation. Render `assets/templates/runner-message.md`, then use CAO `assign` with `agent_profile: aidlc_runner` and `working_directory` set to the validated absolute worktree. The supervisor profile enables this CAO parameter through `CAO_ENABLE_WORKING_DIRECTORY=true`. After assignment returns a terminal ID, record it: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" session update \ --root --project --intent \ --status active --terminal ``` If assignment fails, leave the session pending. Never mark a session active before CAO returns a terminal ID. ## Parent Lifecycle Advance only one phase at a time: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" lifecycle advance \ --root --to discover ``` Repeat for `confirm` and `plan`. Entering Dispatch requires explicit human plan acceptance: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" lifecycle advance \ --root --to dispatch --accepted-by "" ``` After all child sessions complete, advance to `integrate`, resolve every reported blocker, then advance to `learn`. Finish only after learnings and integration state are clean: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" lifecycle complete \ --root --actor "" ``` ## Cross-Project Convergence Read [convergence.md](references/convergence.md). Before a child reports completion, it renders `assets/templates/child-result.yaml` and submits it: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" result submit \ --root --file ``` After all expected results arrive, compute graph impact and integration status: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" convergence check \ --root [--intent ] ``` Missing results and dependency-order risks require remediation. For an eligible breaking, deferred, or unknown risk, obtain an explicit human decision and bind it to the current risk revision: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" convergence decide \ --root --id --decision accepted \ --accepted-by "" --note "" ``` Use `resolved` only when the human confirms the reported risk is resolved. Re-run `convergence check`; changed evidence invalidates stale decisions. ## Human Question Relay When a child AI-DLC stage asks for human judgment, the runner writes the generated questions to Markdown using `[Answer]:` markers and submits the unanswered file: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" question submit \ --root --id --project --intent \ --stage --file ``` Submission rejects any pre-filled answer and moves the session to `waiting`. The runner reports the packet and stops. It must never invoke `question answer`. The supervisor offers the user Guide, Edit Markdown, or Chat. Write each human answer verbatim on its `[Answer]:` line without changing generated question text, then resolve the packet: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" question answer \ --root --id --file \ --mode guided --answered-by "" ``` The command rejects changed question text, missing answers, invalid modes, and repeat answers. It preserves the answered Markdown byte-for-byte, records the human provenance, and returns the session to `active`. Use `question list` to verify status before asking the runner to resume. ## Shared Memory Read [shared-memory.md](references/shared-memory.md) before processing child AI-DLC learnings. `dispatch check` returns canonical baseline revisions for `project.md` and `team.md`; include them in the runner assignment. Child runners submit structured proposals from `assets/templates/learning-proposal.yaml`: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" learning propose \ --root --file ``` The supervisor lists and reviews proposals. Approval performs the canonical write under the portfolio lock: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" learning list \ --root --project --status pending bun "$SKILL_DIR/scripts/portfolio.ts" learning approve \ --root --id ``` If approval reports a stale base, inspect the latest canonical rule set and resolve duplicates or contradictions. Record that human judgment before retrying: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" learning reconcile \ --root --id --note "" ``` Use `memory refresh` at safe stage boundaries when the child needs current canonical context. Before completing a child session, inspect and clean both memory destinations. Both mutations require the exact worktree revision returned by inspect: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" memory inspect \ --root --project --intent --destination project bun "$SKILL_DIR/scripts/portfolio.ts" memory clean \ --root --project --intent --destination project \ --expected-worktree-revision ``` Repeat for `team`. `session update --status completed` refuses shared-memory changes remaining in the feature worktree. ## Recover And Report Run `status` after startup or callback delivery: ```bash bun "$SKILL_DIR/scripts/portfolio.ts" status --root ``` Reconcile terminal loss against durable child AI-DLC state. Relaunch a runner against the same registered worktree and child intent; never create replacement workflow state.