# Alexnodeland Principled Scaffold

> Scaffold — Module Documentation Scaffolding

- Skill: `tomevault-io/alexnodeland-principled-scaffold` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/alexnodeland-principled-scaffold`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/alexnodeland-principled-scaffold/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/alexnodeland-principled-scaffold

---


# Scaffold — Module Documentation Scaffolding

Generate the complete documentation structure for a new module or the repo root.

## Command

```
/scaffold <module-path> --type core|lib|app
/scaffold --root
```

## Arguments

| Argument        | Required              | Description                                                                               |
| --------------- | --------------------- | ----------------------------------------------------------------------------------------- |
| `<module-path>` | Yes (unless `--root`) | Path to the module root (e.g., `packages/payment-gateway`)                                |
| `--type`        | Yes (unless `--root`) | Module type: `core`, `lib`, or `app`. Determines which directories and files are created. |
| `--root`        | No                    | Scaffold the repo-level `docs/` structure instead of a module                             |

## Workflow

### Module Scaffolding (`/scaffold <path> --type <type>`)

1. **Parse arguments.** Extract `<module-path>` and `--type` from `$ARGUMENTS`. Type is required — do not guess or auto-detect.

2. **Create core directories:**

   ```
   <module-path>/docs/proposals/
   <module-path>/docs/plans/
   <module-path>/docs/decisions/
   <module-path>/docs/architecture/
   ```

3. **Create type-specific directories:**
   - **lib:** `<module-path>/docs/examples/`
   - **app:** `<module-path>/docs/runbooks/`, `<module-path>/docs/integration/`, `<module-path>/docs/config/`

4. **Populate core files** from `templates/core/`:
   - Read each template file from this skill's `templates/core/` directory
   - Replace placeholders with actual values:

     | Placeholder       | Value                                                   |
     | ----------------- | ------------------------------------------------------- |
     | `{{MODULE_NAME}}` | Name derived from module path (e.g., `payment-gateway`) |
     | `{{MODULE_TYPE}}` | The `--type` value: `core`, `lib`, or `app`             |
     | `{{DATE}}`        | Today's date in `YYYY-MM-DD` format                     |
     | `{{AUTHOR}}`      | Git user name (`git config user.name`) or "TODO"        |

   - Write populated files:
     - `<module-path>/README.md`
     - `<module-path>/CONTRIBUTING.md`
     - `<module-path>/CLAUDE.md`

5. **Populate type-specific files:**
   - **lib:** Write `INTERFACE.md` from `templates/lib/INTERFACE.md`
   - **app:** (No additional root files — app extensions are directories with template docs)

6. **Run validation** using `scripts/validate-structure.sh`:

   ```bash
   bash scripts/validate-structure.sh --module-path <module-path> --type <type>
   ```

7. **Report results** to the user: list created directories and files, and validation status.

### Root Scaffolding (`/scaffold --root`)

1. Create repo-root directories:

   ```
   docs/proposals/
   docs/plans/
   docs/decisions/
   docs/architecture/
   ```

2. Run root validation:

   ```bash
   bash scripts/validate-structure.sh --root
   ```

3. Report results.

## Templates

All canonical templates live in this skill's `templates/` directory:

- `templates/core/` — proposal.md, plan.md, decision.md, architecture.md, README.md, CONTRIBUTING.md, CLAUDE.md
- `templates/lib/` — INTERFACE.md, example.md
- `templates/app/` — runbook.md, integration.md, config.md

## Scripts

- `scripts/validate-structure.sh` — Structural validation engine (canonical copy)
- `scripts/check-template-drift.sh` — CI script to verify template copies match canonical

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/alexnodeland) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->