aidlc-portfolio

# 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 `<root>/portfolio` and project checkouts at
   `<root>/repositories`.
3. Give each active child intent its own path under `<root>/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 `<root>/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 <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 <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 <root> --file <project.yaml>
bun "$SKILL_DIR/scripts/portfolio.ts" dependency add --root <root> --file <dependency.yaml>
bun "$SKILL_DIR/scripts/portfolio.ts" intent create --root <root> --file <intent.yaml>
```

Record unresolved questions under `<root>/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 <root> --file <discovery-decision.yaml>
```

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
`<root>/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 <root> \
  --source "$HOME/Project/aid