aod-stack

# Stack Pack Management Skill

Activate, list, and manage stack packs that encode technology-specific conventions,
security patterns, and agent persona supplements into AOD.

## Subcommands

| Command | Purpose |
|---------|---------|
| `/aod.stack use {pack-name}` | Activate a stack pack |
| `/aod.stack list` | Show available packs and active status |
| `/aod.stack remove` | Deactivate the active pack |
| `/aod.stack scaffold` | Scaffold project structure from the active pack |

---

## `/aod.stack use {pack-name}`

Activate a stack pack by copying its rules, generating a persona loader, and
persisting activation state.

### Step 1: Validate the pack exists

1. Check that `stacks/{pack-name}/` exists as a directory.
2. Check that `stacks/{pack-name}/STACK.md` exists and is non-empty.
3. If the directory or STACK.md does not exist, display the error:
   ```
   Pack not found: {pack-name}

   Available packs:
     - {list each directory under stacks/ that contains a STACK.md}

   Use: /aod.stack use {pack-name}
   ```
   Then stop.

### Step 2: Handle already-active pack

1. Read `.aod/stack-active.json` if it exists.
2. If another pack is active (the `pack` field differs from `{pack-name}`):
   - Prompt the user: "Pack `{current-pack}` is currently active. Switch to
     `{pack-name}`? This will deactivate `{current-pack}` first. (y/n)"
   - If the user declines, stop.
   - If the user confirms, execute full deactivation:
     a. Delete all files in `.claude/rules/stack/`.
     b. Delete `.aod/stack-active.json`.
3. If the same pack is already active (`pack` field equals `{pack-name}`):
   - Prompt: "Pack `{pack-name}` is already active. Re-activate to update
     rules and persona loader? (y/n)"
   - If the user declines, stop.
   - If the user confirms, proceed (this refreshes rules from the pack source).

### Step 3: Detect and resolve inconsistent state

Before proceeding, check for inconsistencies:

- If `.aod/stack-active.json` exists but is not valid JSON:
  - Warn: "Inconsistent state: `.aod/stack-active.json` is corrupted.
    Cleaning up stale state."
  - Delete all files in `.claude/rules/stack/`.
  - Delete `.aod/stack-active.json`.
  - Then continue with activation.

- If `.aod/stack-active.json` exists but references a pack directory that does
  not exist under `stacks/`:
  - Warn: "Inconsistent state: `.aod/stack-active.json` references pack
    `{missing-pack}` which no longer exists. Cleaning up stale state."
  - Delete all files in `.claude/rules/stack/`.
  - Delete `.aod/stack-active.json`.
  - Then continue with activation.

- If `.claude/rules/stack/` contains files but `.aod/stack-active.json` does
  not exist:
  - Warn: "Inconsistent state: `.claude/rules/stack/` has files but no
    activation state. Cleaning up orphaned rules."
  - Delete all files in `.claude/rules/stack/`.
  - Then continue with activation.

### Step 4: Copy stack rules and agent supplements

1. Ensure the directory `.claude/rules/stack/` exists (create it if missing).
2. Copy every `.md` file from `stacks/{pack-name}/rules/` to
   `.claude/rules/stack/`.
3. Copy every `.md` file from `stacks/{pack-name}/agents/` to
   `.claude/rules/stack/`, prefixing each filename with `agent-` to avoid
   collisions (e.g., `tester.md` → `agent-tester.md`).
4. If either directory is empty or does not contain `.md` files,
   note this in the activation summary but do not treat it as an error.

### Step 5: Generate persona-loader.md

Create the file `.claude/rules/stack/persona-loader.md` with the following
content (substitute `{pack-name}` with the actual pack name):

```markdown
# Stack Pack Persona Loader

When you are a **specialized** or **hybrid** agent, read your persona supplement
from the active stack pack before executing any task.

## Active Pack: {pack-name}

## Agent Tier Classification

**Core agents** (product-manager, architect, team-lead, orchestrator,
web-researcher): You are stack-agnostic. Do NOT read persona supplements.
Ignore this file entirely.

**Specialized agents** (frontend-developer, senior-backend-engineer,
security-analyst, tester, code-reviewer, devops): Read your persona
supplement from `stacks/{pack-name}/agents/{your-agent-name}.md` as
supplementary context before executing any task.

**Hybrid agents** (ux-ui-designer, debugger): Read your persona supplement
from `stacks/{pack-name}/agents/{your-agent-name}.md` for stack-specific
tooling context before executing any task.

## Instructions

1. Determine your agent name (e.g., `frontend-developer`).
2. Check if `stacks/{pack-name}/agents/{your-agent-name}.md` exists.
3. If it exists, read it and apply its conventions, anti-patterns, and
   guardrails to all outputs in this session.
4. If it does not exist, proceed with your core expertise only.
5. Do NOT modify your core behavior — persona supplements are additive context.
```

### Step 6: Write activation state

Write the file `.aod/stack-active.json` with this exact structure:

```json
{
  "pack": "{pack-name}",
  "activated_at": "{current ISO 8601 timestamp}",
  "version": "1.0"
}
```

Use the current UTC time for `activated_at` (e.g., `2026-02-27T14:30:00Z`).

### Step 7: Validate context budget

After writing all files, check the context budget:

1. Count the number of lines in `stacks/{pack-name}/STACK.md`.
2. Count the number of persona supplement files in `stacks/{pack-name}/agents/`
   and the line count of each.
3. Count the total lines across all files copied to `.claude/rules/stack/`
   (including the generated `persona-loader.md`).
4. Compute total pack overhead = STACK.md lines + max persona supplement lines
   + total rules lines.
5. Warn if any threshold is exceeded:
   - STACK.md > 500 lines: "WARNING: STACK.md is {N} lines (limit: 500).
     Consider splitting into STACK.md and STACK-EXTENDED.md."
   - Any persona file > 100 lines: "WARNING: {filename} is {N} lines
     (limit: 100). Brevity forces precision."
   - Total pack overhead > 800 lines: "WARNING: Total pack context is {N}
     lines (limit: 800). Agent performance may degrade."

### Step 8: Display activation summary

Display the following output, filling in actual values:

```
Stack pack activated: {pack-name}

Rules loaded:
  - .claude/rules/stack/{rule1}.md
  - .claude/rules/stack/{rule2}.md
  - .claude/rules/stack/persona-loader.md

Agent supplements available for:
  - {comma-separated list of .md filenames in stacks/{pack-name}/agents/,
    without the .md extension}

Context budget:
  - STACK.md: {N} lines (limit: 500)
  - Persona supplements: {count} files (<=100 lines each)
  - Stack rules: {N} lines (limit: 200)
  - Total pack overhead: {N} lines (limit: 800)

Run /aod.stack scaffold to create the project structure.
```

---

## `/aod.stack remove`

Deactivate the currently active pack, removing all stack-specific rules and state.

### Step 1: Detect and resolve inconsistent state

Before proceeding, check for inconsistencies:

- If `.aod/stack-active.json` is not valid JSON:
  - Warn: "Inconsistent state: `.aod/stack-active.json` is corrupted. Cleaning
    up all stack state."
  - Delete all files in `.claude/rules/stack/`.
  - Delete `.aod/stack-active.json`.
  - Display: "Stack state cleaned. No pack is active."
  - Then stop.

- If `.aod/stack-active.json` exists but references a pack directory that does
  not exist under `stacks/`:
  - Warn: "Inconsistent state: `.aod/stack-active.json` references pack
    `{missing-pack}` which no longer exists. Cleaning up stale state."
  - Delete all files in `.claude/rules/stack/`.
  - Delete `.aod/stack-active.json`.
  - Display: "Stale state cleaned. No pack is active."
  - Then stop.

- If `.claude/rules/stack/` contains files but `.aod/stack-active.json` does
  not exist:
  - Warn: "Inconsistent state: `.claude/rules/stack/` has files but no
    activation state. Cleaning up orphaned rules."
  - Delete all files in `.claude/rules/stack/`.
  - Display: "Orphaned rules cleaned. No pack is active."
  - Then stop.

### Step 2: Check for active pack

1. If `.aod/stack-active.json` does not exist AND `.claude/rules/stack/` is
   empty (or does not exist):
   - Display: "No stack pack is currently active."
   - Then stop.
2. Read `.aod/stack-active.json` to get the active pack name.

### Step 3: Remove stack rules

1. Delete all files in `.claude/rules/stack/` (including `persona-loader.md`).
2. If the directory `.claude/rules/stack/` is now empty, leave it (do not
   delete the directory itself).

### Step 4: Delete activation state

Delete the file `.aod/stack-active.json`.

### Step 5: Display deactivation summary

```
Stack pack removed: {pack-name}

Cleaned:
  - .claude/rules/stack/ (emptied)
  - .aod/stack-active.json (deleted)

Implementation agents reverted to generic behavior.
Previously scaffolded project files remain untouched.
```

---

## `/aod.stack scaffold`

Create the project structure from the active pack's scaffold templates.

### Step 1: Check for active pack

1. Read `.aod/stack-active.json`. If it does not exist, display:
   ```
   No stack pack is active.

   Activate a pack first: /aod.stack use {pack-name}
   ```
   Then stop.
2. Read the `pack` field to determine the active pack name.

### Step 2: Scan scaffold templates

1. Check if `stacks/{pack-name}/scaffold/` exists and contains files (not just
   `.gitkeep`).
2. If the scaffold directory does not exist or is empty, display:
   ```
   No scaffold templates found for pack: {pack-name}

   The pack does not include project scaffolding.
   ```
   Then stop.
3. Build a list of all files in `stacks/{pack-name}/scaffold/` (recursively),
   preserving their relative paths from `scaffold/`.

### Step 3: Detect conflicts

For each scaffold file, check if the target path already exists at the project
root:

1. Compute the target path: project root + relative path from scaffold/.
2. If the target file exists, mark it as a conflict.
3. If no conflicts exist, skip to Step 4.
4. If conflicts exist, display the conflict list and prompt per-file:
   ```
   Scaffold conflicts detected:

     - {file1} (exists)
     - {file2} (exists)

   For each conflict:
   ```
   For each conflicting file, prompt: "Overwrite `{file}`? (y/n/abort)"
   - **y**: Overwrite the file with the scaffold version.
   - **n**: Skip the file (keep existing).
   - **abort**: Stop scaffolding entirely. Files already copied remain.

### Step 4: Copy scaffold files

1. For each non-conflicting file (and each conflict the user chose to overwrite):
   a. Ensure the parent directory exists (create if missing).
   b. Copy the file from `stacks/{pack-name}/scaffold/{path}` to the project
      root at `{path}`.
2. Skip `.gitkeep` files — they are directory placeholders, not scaffold content.

### Step 5: Placeholder Resolution

After scaffold files are copied, automatically resolve template placeholders in `docs/` files.

1. **Baseline grep** (per KB #22): Run `grep -r '{{PROJECT_NAME}}\|{{CURRENT_DATE}}' docs/` to map all placeholder occurrences before replacement. Record the count for the summary.
2. **Source project name**:
   a. Read `.aod/memory/constitution.md` and extract the project name from its heading or body
   b. If not found or file does not exist: fallback to git repo basename via `basename $(git rev-parse --show-toplevel)`
3. **Replace placeholders** in `docs/` files only:
   - Replace all `{{PROJECT_NAME}}` occurrences with the resolved project name
   - Replace all `{{CURRENT_DATE}}` occurrences with the current date in `YYYY-MM-DD` format
   - **Scope boundary**: Do NOT modify files outside the `docs/` directory
4. **Idempotent**: If a file contains no placeholders (already resolved), it remains unchanged
5. **Display summary**:
   ```
   Placeholder resolution:
     Files modified: {count}
     Placeholders resolved: {total_count}
       - {{PROJECT_NAME}}: {count} → {resolved_name}
       - {{CURRENT_DATE}}: {count} → {resolved_date}
   ```
   If zero placeholders found, display: "Placeholder resolution: no placeholders found in docs/ files"

### Step 6: Display scaffold summary

```
Project scaffolded from: {pack-name}

Created:
  - {file1}
  - {file2}
  - ...

Skipped (already exists):
  - {conflict1}
  - ...

Next: Install dependencies and start your development server.
```

If no files were skipped, omit the "Skipped" section.

---

## `/aod.stack list`

Display all available stack packs with descriptions and active status.

### Step 1: Scan for available packs

1. Look for directories under `stacks/` that contain a `STACK.md` file.
2. If the `stacks/` directory does not exist, display:
   ```
   No stack packs found.

   Create stacks/{pack-name}/STACK.md to get started.
   See specs/058-prd-058-stack/contracts/stack-md-format.md for the format spec.
   ```
   Then stop.
3. If `stacks/` exists but no subdirectory contains a `STACK.md`, display:
   ```
   No stack packs found.

   Pack directories exist but none contain a STACK.md convention contract:
     - {list directories without STACK.md}

   Create a STACK.md in a pack directory to register it.
   See specs/058-prd-058-stack/contracts/stack-md-format.md for the format spec.
   ```
   Then stop.

### Step 2: Read active pack state

1. If `.aod/stack-active.json` exists, read its `pack` field.
2. If the file references a pack that does not exist under `stacks/`, display
   a warning: "WARNING: Active pack `{pack-name}` no longer exists in
   `stacks/`. Run `/aod.stack remove` to clean up stale state."
3. If `.claude/rules/stack/` has files but `.aod/stack-active.json` does not
   exist, display a warning: "WARNING: Orphaned rules found in
   `.claude/rules/stack/` with no activation state. Run `/aod.stack remove`
   to clean up."

### Step 3: Extract pack descriptions

For each pack directory containing a `STACK.md`:

1. Read the `STACK.md` file.
2. Find the first `#` heading (the pack title line, e.g., `# Next.js Supabase Stack`).
3. Extract the **Stack** field value from the Summary section (the line starting
   with `**Stack**:`) to use as the technology tagline.
4. Extract the **Use Case** field value from the Summary section (the line
   starting with `**Use Case**:`) to use as the description.
5. If these fields cannot be found, use the first non-heading, non-empty
   paragraph after the title as the description.

### Step 4: Display formatted list

Display the list using this format:

```
Available Stack Packs:

  * {active-pack-dir-name} (active)
    {Stack field value — e.g., Next.js . TypeScript . Supabase . Prisma . Vercel}
    {Use Case field value — e.g., Full-stack web applications with auth, database, and deployment}

    {other-pack-dir-name}
    {Stack field value}
    {Use Case field value}

Use: /aod.stack use {pack-name}
```

Rules:
- Prefix the active pack with `*` and append `(active)`.
- Indent non-active packs at the same level but without the `*` prefix.
- Leave one blank line between pack entries.
- Sort packs alphabetically by directory name.
- If no pack is active, omit the `*` prefix and `(active)` suffix from all entries.

---

## Error Handling (all subcommands)

### Inconsistent state detection

Apply these checks at the start of `use`, `list`, `remove`, and `scaffold`:

| Condition | Action |
|-----------|--------|
| `.aod/stack-active.json` exists but its `pack` field references a directory not in `stacks/` | Warn user, suggest `/aod.stack remove` |
| `.claude/rules/stack/` has `.md` files but `.aod/stack-active.json` does not exist | Warn user about orphaned rules, suggest `/aod.stack remove` |
| `.aod/stack-active.json` is not valid JSON | Warn user, suggest deleting the file manually and re-activating |

### Pack validation errors

When `use` encounters a STACK.md that is empty:
```
Invalid pack: stacks/{pack-name}/STACK.md is empty.

A valid STACK.md requires at minimum a Summary section.
See specs/058-prd-058-stack/contracts/stack-md-format.md for the format spec.
```

---

## Agent Tier Reference

Used by the persona-loader.md and context budget calculations.

| Tier | Agents | Pack Behavior |
|------|--------|---------------|
| **Core** | product-manager, architect, team-lead, orchestrator, web-researcher | Never modified by packs |
| **Specialized** | frontend-developer, senior-backend-engineer, security-analyst, tester, code-reviewer, devops | Persona supplements loaded |
| **Hybrid** | ux-ui-designer, debugger | Universal methodology + stack tooling supplement |

---

## File Paths Reference

| File | Purpose | Committed |
|------|---------|-----------|
| `stacks/{pack}/STACK.md` | Convention contract | Yes |
| `stacks/{pack}/agents/*.md` | Persona supplements | Yes |
| `stacks/{pack}/rules/*.md` | Source rules | Yes |
| `stacks/{pack}/scaffold/**` | Project template files | Yes |
| `.claude/rules/stack/*.md` | Runtime rules (copied on activation) | No (gitignored) |
| `.claude/rules/stack/persona-loader.md` | Generated persona loading instructions | No (gitignored) |
| `.aod/stack-active.json` | Activation state | No (gitignored) |

---

## Constraints

- Do NOT modify any files in `.claude/agents/` — persona supplements are additive context, not replacements.
- Do NOT register stack-specific skills (FR-002 skill registration is deferred).
- Core agent files are NEVER modified by pack activation.
- Only ONE pack can be active at a time.
- Pack removal does NOT affect scaffolded project files — removal only cleans agent context, not user code.
- Governance behavior (Triad reviews, lifecycle stages, sign-offs) is identical with or without an active pack.