@codebehind/agent-workflow 1.1.12 → 1.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codebehind/agent-workflow",
-  "version": "1.1.12",
+  "version": "1.1.14",
   "description": "Scaffold the agent-workflow spec-driven delivery framework into any repo",
   "type": "module",
   "bin": {

package/templates/.claude/skills/bootstrap-meta-repo/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: bootstrap-meta-repo
+description: Scaffold a new meta-repo — gather project info, create README/CLAUDE.md/package.json/docs structure, register git submodules, and commit the initial scaffold.
+---
+
+Use this skill when the user wants to bootstrap a new meta-repository after running `npx @codebehind/agent-workflow init`.
+
+## What is a meta-repo
+
+A meta-repo is a coordination repository that contains no application code. It holds:
+- Shared AI instructions (`CLAUDE.md`, `AGENTS.md`, `.claude/`)
+- Shared documentation (`docs/`)
+- Shared scripts (`scripts/`)
+- Git submodule references to application repositories (`repos/`)
+- npm versioning for the overall platform (`package.json`)
+
+## Objective
+
+Gather project information from the user, scaffold all standard meta-repo files, register git submodules, update `AGENTS.md` to meta-repo mode, and commit the initial scaffold as a clean first commit.
+
+## Phase 1 — Gather inputs
+
+If the user invoked this skill with no arguments or incomplete information, ask for the following before proceeding. Accept everything as a single pasted block if the user provides it upfront.
+
+| Input | Required | Example |
+|-------|----------|---------|
+| Project name | yes | `Aurora` |
+| npm package name | yes | `@aurora/meta` |
+| One-sentence description | yes | `Enterprise DMS for document OCR, signing, and archiving` |
+| Domain description | yes | Key concepts, features, target users — used to populate CLAUDE.md and docs |
+| Submodules list | yes (at least 1) | For each: folder name under `repos/`, git URL, short purpose |
+| Tech stack per submodule | no | Used for the Conventions section of CLAUDE.md |
+
+If submodules are not provided at all, proceed without registering them and note this in the final report.
+
+Ask only for what is missing — do not repeat questions the user already answered.
+
+## Phase 2 — Scaffold files
+
+Create the files listed below. **Skip any file that already exists and has non-placeholder content** — log it as skipped in the final report.
+
+### README.md
+
+```markdown
+# <Project Name> — Meta Repository
+
+<Project description>
+
+## Project Repositories
+
+| Folder | Purpose | URL |
+|--------|---------|-----|
+| `repos/<folder>/` | <purpose> | [GitLab](<url>) |
+
+## Repository Structure
+
+\`\`\`
+<project-slug>-meta/
+├── CLAUDE.md                   # AI agent instructions for this project
+├── README.md                   # This file
+├── package.json                # Versioning and shared npm tooling
+├── docs/
+│   ├── architecture/           # Architecture overviews and diagrams
+│   ├── decisions/              # Architecture Decision Records (ADRs)
+│   └── functional/             # Functional and domain documentation
+├── scripts/                    # Shared orchestration scripts
+├── .claude/                    # Claude Code configuration and skills
+│   ├── settings.json
+│   └── skills/
+└── repos/                      # Git submodules — one per service
+    └── <folder>/
+\`\`\`
+
+## Getting Started
+
+### Clone with submodules
+
+\`\`\`bash
+git clone --recurse-submodules <meta-repo-url>
+\`\`\`
+
+Or, after a plain clone:
+
+\`\`\`bash
+npm run submodules:init
+\`\`\`
+
+### Install shared tooling
+
+\`\`\`bash
+npm install
+\`\`\`
+
+### Update all submodules to latest
+
+\`\`\`bash
+npm run submodules:update
+\`\`\`
+
+## Versioning
+
+This meta repository follows [Semantic Versioning](https://semver.org/). The version in `package.json` represents the overall <Project Name> platform version.
+```
+
+### CLAUDE.md
+
+```markdown
+# <Project Name> — Claude Agent Instructions
+
+This is the meta repository for the <Project Name> platform. Read this file before working on any part of the project.
+
+## Project Overview
+
+<Project description — 2-3 sentences from the domain description provided>
+
+## Repository Map
+
+All service repositories are available as git submodules under `repos/`:
+
+| Submodule path | Service |
+|---|---|
+| `repos/<folder>/` | <purpose> |
+
+## Domain Concepts
+
+<Bullet list of key domain terms derived from the domain description>
+
+## Conventions
+
+- ADRs (Architecture Decision Records) live in `docs/decisions/` using the template at `docs/decisions/ADR-template.md`
+- Shared scripts live in `scripts/` and must be POSIX-compatible shell unless a specific runtime is justified
+- All inter-service API contracts must be documented in `docs/architecture/`
+- When adding a new service repository, register it as a submodule under `repos/` and document it here and in `README.md`
+- Commit style: conventional commits (`feat:`, `fix:`, `chore:`, etc.)
+
+## Working Across Repositories
+
+When a change spans multiple services:
+1. Open the relevant submodule(s) under `repos/`
+2. Work in feature branches within each submodule
+3. Update the submodule pointer in this repo once the downstream branches are merged
+4. Document any cross-cutting API or schema changes in `docs/architecture/`
+
+## AI Agent Notes
+
+- Prefer reading existing docs and ADRs before proposing architectural changes
+- When unsure about a domain term, refer to the Domain Concepts section above
+- Do not modify submodule content directly through this repo — always work inside the submodule directory
+- Shared scripts in `scripts/` should remain idempotent and safe to re-run
+```
+
+### package.json
+
+```json
+{
+  "name": "<npm-package-name>",
+  "version": "0.1.0",
+  "description": "<description>",
+  "private": true,
+  "scripts": {
+    "submodules:init": "git submodule update --init --recursive",
+    "submodules:update": "git submodule update --remote --merge",
+    "submodules:status": "git submodule status"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}
+```
+
+### docs/architecture/overview.md
+
+```markdown
+# Architecture Overview
+
+## System Overview
+
+<Fill in: high-level description of how the system components fit together>
+
+## Services
+
+| Service | Submodule | Responsibility |
+|---------|-----------|----------------|
+| <name> | `repos/<folder>/` | <responsibility> |
+
+## Inter-service Communication
+
+<Fill in: how services communicate — REST, events, shared DB, etc.>
+
+## Key Architectural Decisions
+
+See `docs/decisions/` for Architecture Decision Records.
+```
+
+### docs/decisions/ADR-template.md
+
+```markdown
+# ADR-NNN: <Title>
+
+**Status:** proposed | accepted | deprecated | superseded
+
+**Date:** YYYY-MM-DD
+
+## Context
+
+<What is the issue we are addressing? What are the forces at play?>
+
+## Decision
+
+<What is the change we are making?>
+
+## Consequences
+
+<What are the resulting positive and negative outcomes of this decision?>
+```
+
+### docs/functional/domain-overview.md
+
+```markdown
+# Domain Overview
+
+<Populate with the domain description provided by the user — key concepts, features, and user roles>
+
+## Key Concepts
+
+<Derived from the domain description — define the core entities and terms>
+
+## Features
+
+<List of key product features>
+
+## User Roles
+
+<List of roles/actors if applicable>
+```
+
+### .gitignore
+
+```
+# Dependencies
+node_modules/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Logs
+*.log
+npm-debug.log*
+
+# Build outputs
+dist/
+build/
+```
+
+## Phase 3 — Update AGENTS.md
+
+`AGENTS.md` already exists (created by `npx @codebehind/agent-workflow init`). Update the `## Repo Mode` section:
+
+1. Replace the mode declaration line from `**Mode:** single-repo` to `**Mode:** meta-repo`
+2. Fill in the submodule table (replacing the comment placeholder):
+   ```markdown
+   | Directory | GitLab project URL |
+   |---|---|
+   | repos/<folder>/ | <git-url> |
+   ```
+3. Replace the single-repo description block with the meta-repo description:
+   ```markdown
+   **Meta-repo:** Specs, plans, docs, and artifacts live here. Application code lives in `repos/<module>/` submodules (see table above). Never commit application code directly to this repo. Each affected submodule gets its own MR in its own GitLab project. Reference submodule MR URLs in the meta-repo MR description. When running acceptance proof (UI, API), navigate into the relevant `repos/<module>/` directory to start the app and capture evidence; save artifacts back here under `.agent-workflow/artifacts/`.
+   ```
+4. Remove all HTML comment blocks (`<!-- ... -->`) from the Repo Mode section.
+
+If `AGENTS.md` does not exist, create it from scratch using the meta-repo variant of the standard template.
+
+## Phase 4 — Register git submodules
+
+For each submodule in the provided list, run:
+
+```bash
+git submodule add <git-url> repos/<folder-name>
+```
+
+Run sequentially. If a submodule add fails (inaccessible repo, wrong URL, already registered), log the error and continue with the remaining submodules — do not abort.
+
+If no submodules were provided, create `repos/.gitkeep` so the directory is tracked by git.
+
+## Phase 5 — Commit
+
+Stage all created and modified files:
+
+```bash
+git add README.md CLAUDE.md package.json .gitignore AGENTS.md docs/ repos/
+```
+
+If `.gitmodules` was created (submodules registered):
+```bash
+git add .gitmodules
+```
+
+Commit:
+```bash
+git commit -m "chore: bootstrap meta-repo scaffold"
+```
+
+## Phase 6 — Final report
+
+Output a summary containing:
+
+**Created files:**
+- List each file created with its path
+
+**Skipped files (already existed):**
+- List each file that was skipped
+
+**Submodules registered:**
+- List each successfully registered submodule
+
+**Submodule failures (if any):**
+- List each submodule that failed to register with the error message
+
+**Next steps:**
+1. Review the generated files and fill in any `<placeholder>` values
+2. If any submodules failed, run `git submodule add <url> repos/<folder>` manually
+3. Push as the `main` branch: `git push -u origin main`
+4. Open the GitLab project and configure branch protection
+
+## Edge cases
+
+- **File already exists with real content**: skip it, log as skipped — never overwrite
+- **AGENTS.md missing**: create from scratch in meta-repo mode
+- **No submodules provided**: skip Phase 4, create `repos/.gitkeep`, note in report
+- **Submodule add fails**: log the failure, continue, report at end
+- **Partial user input**: ask only for missing fields, not the full set again
+- **User provides info upfront as a pasted block** (e.g., existing project description prompt): parse it directly without asking questions