@codewizard-dt/bootstrap 4.0.0 → 5.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +18 -60
- package/lib/prompts/README.md +0 -1
- package/lib/scripts/README.md +1 -2
- package/lib/scripts/migrate-project.sh +1 -1
- package/lib/scripts/setup-project.sh +0 -1
- package/lib/scripts/sync-wiki-scaffold.sh +3 -15
- package/lib/scripts/templates/CLAUDE-wiki.md +4 -4
- package/lib/scripts/templates/bootstrap-prefs-schema.json +1 -1
- package/lib/scripts/templates/wiki/conventions.md +1 -1
- package/lib/scripts/templates/wiki/dashboard.html +2 -2
- package/lib/scripts/templates/wiki/index.md +4 -4
- package/lib/scripts/templates/wiki/work/requirements/index.md +1 -1
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +2 -2
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +1 -1
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +4 -4
- package/lib/scripts/templates/wiki/work/tasks/index.md +1 -1
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +6 -6
- package/lib/scripts/templates/wiki/work/uat/index.md +1 -1
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +4 -4
- package/lib/scripts/wiki-dashboard-server.js +1 -1
- package/lib/skills/README.md +2 -1
- package/lib/skills/architecture-audit/SKILL.md +207 -0
- package/lib/skills/bug-close/SKILL.md +2 -2
- package/lib/skills/bug-file/SKILL.md +9 -5
- package/lib/skills/decision-create/SKILL.md +5 -1
- package/lib/skills/power-mode/SKILL.md +10 -10
- package/lib/skills/primer/SKILL.md +1 -1
- package/lib/skills/req-compile/SKILL.md +2 -2
- package/lib/skills/req-create/SKILL.md +13 -9
- package/lib/skills/req-extract-decisions/SKILL.md +10 -10
- package/lib/skills/req-finalize/SKILL.md +3 -3
- package/lib/skills/req-retire/SKILL.md +10 -10
- package/lib/skills/req-update/SKILL.md +4 -4
- package/lib/skills/roadmap-assess/SKILL.md +7 -7
- package/lib/skills/roadmap-create/SKILL.md +22 -22
- package/lib/skills/roadmap-next/SKILL.md +10 -10
- package/lib/skills/security-audit/SKILL.md +3 -0
- package/lib/skills/tackle/SKILL.md +3 -3
- package/lib/skills/task-add/SKILL.md +22 -22
- package/lib/skills/task-audit/SKILL.md +2 -2
- package/lib/skills/task-trash/SKILL.md +4 -4
- package/lib/skills/uat-generate/SKILL.md +22 -22
- package/lib/skills/uat-skip/SKILL.md +21 -21
- package/lib/skills/uat-walk/UAT-CORE.md +6 -6
- package/lib/skills/wiki-lint/SKILL.md +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ Bootstrap Claude Code projects with an LLM Wiki, reusable skills, enforcement ho
|
|
|
6
6
|
|
|
7
7
|
## Description
|
|
8
8
|
|
|
9
|
-
`@codewizard-dt/bootstrap` is an npm-distributed setup toolkit for Claude Code users who repeatedly configure the same agent workflow in new repositories. It installs Model Context Protocol servers, syncs a global skill library, copies hook scripts, scaffolds an LLM Wiki, assembles a project-specific MCP tools guide, and provides explicit
|
|
9
|
+
`@codewizard-dt/bootstrap` is an npm-distributed setup toolkit for Claude Code users who repeatedly configure the same agent workflow in new repositories. It installs Model Context Protocol servers, syncs a global skill library, copies hook scripts, scaffolds an LLM Wiki, assembles a project-specific MCP tools guide, and provides an explicit command for strict type-checking setup.
|
|
10
10
|
|
|
11
11
|
The project exists to move AI-agent state out of chat history and into structured, versioned markdown. Requirements, decisions, tasks, UAT specs, bug reports, roadmaps, source summaries, and operating logs all live in a predictable wiki layout, so future Claude Code sessions and subagents can resume work from file-system state instead of relying on prior conversation context.
|
|
12
12
|
|
|
@@ -26,16 +26,16 @@ At a glance, the package entry point selects a script, scripts copy or generate
|
|
|
26
26
|
|
|
27
27
|
- **Responsibility:** Routes `bootstrap <command>` and `npx @codewizard-dt/bootstrap <command>` invocations to the appropriate setup script.
|
|
28
28
|
- **Tech:** Node.js CommonJS, `child_process.execFileSync`
|
|
29
|
-
- **Inputs:** Commands such as `setup`, `update`, `install`, `
|
|
29
|
+
- **Inputs:** Commands such as `setup`, `update`, `install`, `migrate`, `typechecks`, and `dashboard`, plus optional extra arguments for migration and dashboard (port override) flows.
|
|
30
30
|
- **Outputs:** Executes the selected script with inherited stdio and propagates the script exit status.
|
|
31
31
|
- **Depends on:** Setup Scripts
|
|
32
32
|
|
|
33
33
|
#### Setup Scripts
|
|
34
34
|
|
|
35
|
-
- **Responsibility:** Coordinate project setup, updates, global installs,
|
|
35
|
+
- **Responsibility:** Coordinate project setup, updates, global installs, Serena bootstrapping, wiki migration, and strict type-checking setup.
|
|
36
36
|
- **Tech:** Bash, `rsync`, `find`, `grep`, `claude` CLI, npm-executed shell scripts
|
|
37
|
-
- **Inputs:** Target project path, interactive prompts, CLI flags such as `--dry-run`, API keys supplied by environment variables or stdin, and optional user context for
|
|
38
|
-
- **Outputs:** Global hooks and skills, MCP registrations, project-local `wiki/`, `raw/`, `wiki/guides/`, `.mcp.json`, `.serena/project.yml`, and optional
|
|
37
|
+
- **Inputs:** Target project path, interactive prompts, CLI flags such as `--dry-run`, API keys supplied by environment variables or stdin, and optional user context for typecheck setup.
|
|
38
|
+
- **Outputs:** Global hooks and skills, MCP registrations, project-local `wiki/`, `raw/`, `wiki/guides/`, `.mcp.json`, `.serena/project.yml`, and optional type-check configuration when that explicit command is run.
|
|
39
39
|
- **Depends on:** CLI Entry Point, Skills Library, Hooks Library, Wiki Scaffold Templates, Prompt Templates, Guide Stubs, Claude Code CLI, MCP servers
|
|
40
40
|
|
|
41
41
|
#### MCP Installer
|
|
@@ -80,20 +80,12 @@ At a glance, the package entry point selects a script, scripts copy or generate
|
|
|
80
80
|
|
|
81
81
|
#### Prompt Templates
|
|
82
82
|
|
|
83
|
-
- **Responsibility:** Provide Claude Code with structured instructions for
|
|
83
|
+
- **Responsibility:** Provide Claude Code with structured instructions for wiki migration, Serena configuration, and strict type-checking setup when static templates are too brittle.
|
|
84
84
|
- **Tech:** Markdown prompt files in `lib/prompts/`
|
|
85
|
-
- **Inputs:** Target project context, raw guide content, script interpolation, and optional user-provided
|
|
86
|
-
- **Outputs:** Claude-generated project configuration,
|
|
85
|
+
- **Inputs:** Target project context, raw guide content, script interpolation, and optional user-provided typecheck details.
|
|
86
|
+
- **Outputs:** Claude-generated project configuration, migrated wiki artifacts, and type-check tooling.
|
|
87
87
|
- **Depends on:** Claude Code CLI, raw guides, Setup Scripts
|
|
88
88
|
|
|
89
|
-
#### GitHub Actions Templates
|
|
90
|
-
|
|
91
|
-
- **Responsibility:** Supplies repository automation for secret scanning and a Docker/GHCR build-push template.
|
|
92
|
-
- **Tech:** GitHub Actions YAML, Gitleaks action, Docker Buildx actions
|
|
93
|
-
- **Inputs:** Pushes and pull requests to `main` for `security.yml`; manual `workflow_dispatch` for `build.yml`; root-level `Dockerfile` for container build execution.
|
|
94
|
-
- **Outputs:** Gitleaks scan results, optional GHCR container images, and a placeholder deploy job that must be customized before production use.
|
|
95
|
-
- **Depends on:** GitHub Actions, `.gitleaks.toml`, GitHub package permissions
|
|
96
|
-
|
|
97
89
|
### Component Interaction
|
|
98
90
|
|
|
99
91
|
```mermaid
|
|
@@ -113,7 +105,6 @@ flowchart LR
|
|
|
113
105
|
MCPS["install-mcps.sh"]
|
|
114
106
|
WIKI["sync-wiki-scaffold.sh"]
|
|
115
107
|
GUIDE["build-mcp-guide.sh"]
|
|
116
|
-
DEPLOY["setup-deployment.sh"]
|
|
117
108
|
SERENA["bootstrap-serena.sh"]
|
|
118
109
|
end
|
|
119
110
|
|
|
@@ -138,7 +129,6 @@ flowchart LR
|
|
|
138
129
|
DOCS["wiki/guides/mcp-tools.md"]
|
|
139
130
|
MCP_JSON["Serena (local scope)<br/>~/.claude.json project entry"]
|
|
140
131
|
SERENA_CFG[".serena/project.yml"]
|
|
141
|
-
WORKFLOWS[".github/workflows/"]
|
|
142
132
|
end
|
|
143
133
|
|
|
144
134
|
subgraph External ["External Tools"]
|
|
@@ -147,7 +137,6 @@ flowchart LR
|
|
|
147
137
|
DOCKER["Docker<br/>brave-search-mcp container<br/>http :8941"]
|
|
148
138
|
LAUNCHD["launchd<br/>playwright-mcp LaunchAgent<br/>http :8931 (macOS)"]
|
|
149
139
|
NPX["npx<br/>Playwright MCP (non-macOS stdio)"]
|
|
150
|
-
GHA["GitHub Actions"]
|
|
151
140
|
NPM["npm Registry"]
|
|
152
141
|
end
|
|
153
142
|
|
|
@@ -155,7 +144,6 @@ flowchart LR
|
|
|
155
144
|
BIN -->|execFileSync| SETUP
|
|
156
145
|
BIN -->|execFileSync| UPDATE
|
|
157
146
|
BIN -->|execFileSync| INSTALL
|
|
158
|
-
BIN -->|execFileSync| DEPLOY
|
|
159
147
|
SETUP -->|runs| MCPS
|
|
160
148
|
SETUP -->|runs| INSTALL
|
|
161
149
|
SETUP -->|runs| WIKI
|
|
@@ -176,12 +164,8 @@ flowchart LR
|
|
|
176
164
|
WIKI -->|writes| WIKI_DIR
|
|
177
165
|
GUIDE -->|assemble selected sections| STUBS
|
|
178
166
|
GUIDE -->|writes| DOCS
|
|
179
|
-
DEPLOY -->|claude -p| PROMPTS
|
|
180
|
-
DEPLOY -->|reads| RAW
|
|
181
|
-
DEPLOY -->|writes| WORKFLOWS
|
|
182
167
|
SERENA -->|claude -p| CLAUDE
|
|
183
168
|
SERENA -->|writes| SERENA_CFG
|
|
184
|
-
WORKFLOWS -->|runs| GHA
|
|
185
169
|
DEV -->|npm publish| NPM
|
|
186
170
|
```
|
|
187
171
|
|
|
@@ -247,7 +231,7 @@ sequenceDiagram
|
|
|
247
231
|
- **Project-scoped Serena:** Serena is registered against an absolute project path in `.mcp.json`, avoiding cross-project language-server bleed while keeping other MCPs available globally when appropriate.
|
|
248
232
|
- **Copy-once vs. always-refresh templates:** Project-owned files such as indexes and logs are not overwritten, while lifecycle specs, conventions, and guide content can be refreshed from the package.
|
|
249
233
|
- **Hooks enforce behavior where permissions cannot:** PreToolUse and PostToolUse hooks enforce `.env` safety, protected git operations, and Serena-first navigation even when normal allow/deny permissions are bypassed.
|
|
250
|
-
- **Claude-driven scaffolding handles project variance:**
|
|
234
|
+
- **Claude-driven scaffolding handles project variance:** Type-checking, Serena configuration, and wiki migration use prompt templates plus `claude -p` because the right output depends on the consumer project's stack.
|
|
251
235
|
|
|
252
236
|
## Technologies
|
|
253
237
|
|
|
@@ -255,7 +239,7 @@ sequenceDiagram
|
|
|
255
239
|
- Node.js CommonJS for the CLI and hook scripts
|
|
256
240
|
- Bash for installation, synchronization, migration, and setup orchestration
|
|
257
241
|
- Markdown for skills, prompts, wiki templates, raw guides, and project documentation
|
|
258
|
-
- YAML for
|
|
242
|
+
- YAML for generated Serena/project configuration
|
|
259
243
|
- JSON for `package.json`, `.mcp.json`, hook payloads, and Claude Code settings snippets
|
|
260
244
|
|
|
261
245
|
- **CLI and package distribution**
|
|
@@ -283,15 +267,9 @@ sequenceDiagram
|
|
|
283
267
|
- LLM Wiki structure with `raw/`, `wiki/knowledge/`, and `wiki/work/`
|
|
284
268
|
- Mermaid diagrams embedded in documentation
|
|
285
269
|
|
|
286
|
-
- **CI/CD and security**
|
|
287
|
-
- GitHub Actions
|
|
288
|
-
- Gitleaks and `.gitleaks.toml`
|
|
289
|
-
- Docker Buildx GitHub Actions template
|
|
290
|
-
- GitHub Container Registry template workflow
|
|
291
|
-
|
|
292
270
|
## Use Cases
|
|
293
271
|
|
|
294
|
-
- **New Claude Code project bootstrap:** Developers can run one command in a repository to install MCP tooling, global skills, global hooks, wiki scaffolding, MCP guides, and Serena configuration
|
|
272
|
+
- **New Claude Code project bootstrap:** Developers can run one command in a repository to install MCP tooling, global skills, global hooks, wiki scaffolding, MCP guides, and Serena configuration.
|
|
295
273
|
- **Global agent workflow installation:** Users can sync the latest skill and hook library into `~/.claude/` without modifying any project by running the install command.
|
|
296
274
|
- **Legacy documentation migration:** Existing `.docs/`-style projects can be migrated into the current LLM Wiki structure with branch isolation, path mapping, frontmatter synthesis, and link rewrites.
|
|
297
275
|
- **AI-native engineering operations:** Teams can manage requirements, decisions, tasks, UAT, roadmaps, bugs, evals, research, demos, and security audits as durable markdown artifacts that agents can read and update.
|
|
@@ -305,8 +283,7 @@ sequenceDiagram
|
|
|
305
283
|
- **Knowledge Management Architecture (LLM Wiki):** Modeled project memory as immutable raw sources, timeless knowledge synthesis, and lifecycle-managed work artifacts with conventions, indexes, logs, stable IDs, and typed links.
|
|
306
284
|
- **Model Context Protocol Integration:** Integrated Serena, Brave Search, Context7, and Playwright MCP servers with appropriate scope decisions, API-key handling, and generated MCP usage guidance.
|
|
307
285
|
- **Claude Code Hook Engineering (Node.js):** Built hook scripts that enforce file-safety and LSP-first navigation policies using Claude Code hook payloads, shared helper modules, and persistent navigation state.
|
|
308
|
-
- **Prompt Engineering for Developer Tooling:** Created prompt templates that let Claude Code generate context-sensitive
|
|
309
|
-
- **CI/CD Pipeline Configuration (GitHub Actions):** Provided security scanning and container build/push workflow templates using Gitleaks, Docker Buildx, GHCR, manual dispatch, and skip guards for repositories without Dockerfiles.
|
|
286
|
+
- **Prompt Engineering for Developer Tooling:** Created prompt templates that let Claude Code generate context-sensitive migration, type-checking, and Serena configuration changes in consumer projects.
|
|
310
287
|
- **Developer Experience Design:** Organized commands, skills, templates, guides, and troubleshooting paths so repeated Claude Code setup work can be performed from a small set of predictable commands.
|
|
311
288
|
- **Documentation Systems Engineering:** Generated machine-parseable project documentation, skill instructions, lifecycle specs, MCP guides, and runbooks that serve both humans and downstream AI tools.
|
|
312
289
|
|
|
@@ -314,7 +291,7 @@ sequenceDiagram
|
|
|
314
291
|
|
|
315
292
|
### Overview
|
|
316
293
|
|
|
317
|
-
This project deploys as a public npm CLI package. There is no hosted runtime, database, or production server; publishing a new npm version
|
|
294
|
+
This project deploys as a public npm CLI package. There is no hosted runtime, database, or production server, and no CI/CD automation; publishing a new npm version to the registry is the entire release process.
|
|
318
295
|
|
|
319
296
|
### Prerequisites
|
|
320
297
|
|
|
@@ -322,13 +299,12 @@ This project deploys as a public npm CLI package. There is no hosted runtime, da
|
|
|
322
299
|
- `npm` with publish access to the `@codewizard-dt` scope.
|
|
323
300
|
- An authenticated npm session via `npm login` or an npm automation token.
|
|
324
301
|
- Git access to the repository at `git@github.com:codewizard-dt/bootstrap-claude.git`.
|
|
325
|
-
- GitHub Actions enabled for repository CI checks.
|
|
326
302
|
- For local smoke tests of setup commands, install Claude Code with `npm install -g @anthropic-ai/claude-code`.
|
|
327
303
|
- For Serena setup smoke tests, install `uv` so `uvx` is available.
|
|
328
304
|
|
|
329
305
|
### Environment Variables
|
|
330
306
|
|
|
331
|
-
No environment variables are required to build or publish this package from a logged-in npm session. The setup scripts
|
|
307
|
+
No environment variables are required to build or publish this package from a logged-in npm session. The setup scripts reference the following variables and secrets:
|
|
332
308
|
|
|
333
309
|
| Variable | Required | Example | Description |
|
|
334
310
|
|---|---|---|---|
|
|
@@ -336,11 +312,6 @@ No environment variables are required to build or publish this package from a lo
|
|
|
336
312
|
| `BRAVE_MCP_PORT` | no — defaults to `8941` | `8941` | Host port for the shared Brave Search MCP Docker container (mapped to the container's fixed port `8941`); the registered endpoint is `http://127.0.0.1:<port>/mcp`. |
|
|
337
313
|
| `PLAYWRIGHT_MCP_PORT` | no — defaults to `8931` | `8931` | Port the shared Playwright MCP launchd agent listens on (macOS); the registered endpoint is `http://127.0.0.1:<port>/mcp`. |
|
|
338
314
|
| `CONTEXT7_API_KEY` | optional for Context7 MCP install | `ctx_...` | Optional secret sent as a Context7 MCP HTTP header; Context7 can be installed without it. |
|
|
339
|
-
| `GITHUB_TOKEN` | yes in GitHub Actions | `${{ secrets.GITHUB_TOKEN }}` | GitHub-provided token used by Gitleaks and GHCR login in workflows. |
|
|
340
|
-
| `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` | yes in workflows | `true` | Plain workflow config forcing JavaScript actions to run on Node 24. |
|
|
341
|
-
| `REGISTRY` | yes in `build.yml` | `ghcr.io` | Plain workflow config for the container registry in the template workflow. |
|
|
342
|
-
| `OWNER` | yes in `build.yml` | `${{ github.repository_owner }}` | Plain workflow config used to build GHCR image tags. |
|
|
343
|
-
| `IMAGE` | yes in `build.yml` | `${{ github.event.repository.name }}` | Plain workflow config used to build GHCR image tags. |
|
|
344
315
|
| `CLAUDE_MIGRATION` | optional | `1` | Plain flag recognized by some Serena enforcement hooks to bypass during migration flows. |
|
|
345
316
|
|
|
346
317
|
### Build
|
|
@@ -352,7 +323,7 @@ There is no transpilation or bundling step. The package ships source files direc
|
|
|
352
323
|
npm pack --dry-run
|
|
353
324
|
```
|
|
354
325
|
|
|
355
|
-
The publishable surface is `bin/`, `lib/`, `raw/`,
|
|
326
|
+
The publishable surface is `bin/`, `lib/`, and `raw/` (excluding `raw/research/`, `raw/companies/`, and `raw/*.pdf`, per `package.json` `files`).
|
|
356
327
|
|
|
357
328
|
### Run Locally
|
|
358
329
|
|
|
@@ -370,9 +341,6 @@ node bin/cli.js setup
|
|
|
370
341
|
# Serves on http://localhost:4317 by default; pass a port to override
|
|
371
342
|
node bin/cli.js dashboard
|
|
372
343
|
node bin/cli.js dashboard 4400
|
|
373
|
-
|
|
374
|
-
# Preview deployment-scaffold detection for the current repository
|
|
375
|
-
node lib/scripts/setup-deployment.sh --dry-run .
|
|
376
344
|
```
|
|
377
345
|
|
|
378
346
|
The setup command writes to the current project and to `~/.claude/`, so run it from a disposable test repository when validating a release candidate.
|
|
@@ -412,11 +380,7 @@ npm view @codewizard-dt/bootstrap version
|
|
|
412
380
|
npx @codewizard-dt/bootstrap@latest
|
|
413
381
|
```
|
|
414
382
|
|
|
415
|
-
CI/CD
|
|
416
|
-
|
|
417
|
-
- `.github/workflows/security.yml` runs Gitleaks on pushes and pull requests targeting `main`.
|
|
418
|
-
- `.github/workflows/build.yml` is manual-only via `workflow_dispatch`; its build job skips unless a root-level `Dockerfile` exists, and its deploy job is a placeholder.
|
|
419
|
-
- No workflow currently publishes the npm package automatically; npm release is manual.
|
|
383
|
+
This project does not offer GitHub Actions scaffolding or any other CI/CD automation as a feature — publishing to npm by hand is the only release process.
|
|
420
384
|
|
|
421
385
|
### Data & Migrations
|
|
422
386
|
|
|
@@ -435,9 +399,6 @@ npm view @codewizard-dt/bootstrap version
|
|
|
435
399
|
|
|
436
400
|
# The latest package should execute and print usage without a command
|
|
437
401
|
npx @codewizard-dt/bootstrap@latest
|
|
438
|
-
|
|
439
|
-
# Security workflow should pass in GitHub Actions
|
|
440
|
-
gh run list --workflow security.yml --limit 5
|
|
441
402
|
```
|
|
442
403
|
|
|
443
404
|
For end-to-end validation, run `npx @codewizard-dt/bootstrap@latest setup` inside a disposable repository and confirm `wiki/`, `raw/`, `wiki/guides/`, and the selected MCP configuration files are created.
|
|
@@ -462,24 +423,21 @@ For source rollback, revert the release commit and publish a new patch version r
|
|
|
462
423
|
|
|
463
424
|
### Observability
|
|
464
425
|
|
|
465
|
-
There is no runtime telemetry, metrics backend, dashboard, or alerting because the project is a CLI package. Operational signals come from
|
|
426
|
+
There is no runtime telemetry, metrics backend, dashboard, or alerting because the project is a CLI package. Operational signals come from npm package metadata, npm install/publish output, and user-reported command failures.
|
|
466
427
|
|
|
467
428
|
Useful first places to inspect:
|
|
468
429
|
|
|
469
|
-
- GitHub Actions security workflow runs in `.github/workflows/security.yml`.
|
|
470
|
-
- Manual build template runs in `.github/workflows/build.yml`.
|
|
471
430
|
- npm package metadata from `npm view @codewizard-dt/bootstrap`.
|
|
472
431
|
- Local command traces from the setup scripts' stdout/stderr.
|
|
473
432
|
|
|
474
433
|
### Troubleshooting
|
|
475
434
|
|
|
476
435
|
- **`command not found: bootstrap`:** The package binary is not on PATH; run through `npx @codewizard-dt/bootstrap <command>` or use `node bin/cli.js <command>` locally.
|
|
477
|
-
- **`claude: command not found`:** Claude Code is missing; install it with `npm install -g @anthropic-ai/claude-code` before running setup,
|
|
436
|
+
- **`claude: command not found`:** Claude Code is missing; install it with `npm install -g @anthropic-ai/claude-code` before running setup, migration, or typecheck setup.
|
|
478
437
|
- **`uv: command not found`:** Serena setup cannot launch; install uv so `uvx` is available, then rerun setup.
|
|
479
438
|
- **Brave MCP install prompts for an API key:** Set `BRAVE_API_KEY` before non-interactive installs or enter it when prompted by `install-mcps.sh`. The key is baked into the `brave-search-mcp` container at creation, so a re-run never re-prompts while the container exists; to change the key, `docker rm -f brave-search-mcp` and re-run `bootstrap update`. Brave install also requires Docker to be running — if it is not, the script skips brave-search until the next `bootstrap update`.
|
|
480
439
|
- **`brave-search endpoint not answering`:** The shared container should be serving `http://127.0.0.1:8941/mcp` (host port overridable via `BRAVE_MCP_PORT`). Check `docker logs brave-search-mcp` and confirm Docker Desktop is running; enable Docker Desktop's "Start when you sign in" so the container comes back after reboots.
|
|
481
440
|
- **`playwright endpoint not answering` (macOS):** The launchd agent `com.bootstrap-claude.playwright-mcp` should be serving `http://127.0.0.1:8931/mcp` (overridable via `PLAYWRIGHT_MCP_PORT`). Inspect it with `launchctl print gui/$(id -u)/com.bootstrap-claude.playwright-mcp` and check `~/Library/Logs/playwright-mcp.log`. Over SSH there is no GUI session for the agent to bootstrap into — log into the Mac GUI once, then re-run `bootstrap update`.
|
|
482
441
|
- **Context7 installs without authenticated access:** Set `CONTEXT7_API_KEY` if authenticated Context7 access is required; otherwise the script can register Context7 without the header.
|
|
483
442
|
- **Hooks copy but do not run:** `install-global.sh` copies scripts to `~/.claude/hooks/`, but hook registration in `~/.claude/settings.json` is a separate manual step documented in `lib/hooks/README.md`. The `permissions.deny` list is the exception: `install-global.sh` merges the canonical deny list from `lib/scripts/templates/settings-deny.json` into `~/.claude/settings.json` automatically (additive-only — your own entries are never removed or reordered). Deleting a canonical entry locally means it gets re-added on the next `install`/`setup`/`update` run; that re-convergence is the point of a canonical list.
|
|
484
|
-
- **Manual build workflow skips:** `.github/workflows/build.yml` intentionally skips the build job unless a root-level `Dockerfile` exists.
|
|
485
443
|
- **npm package points at unexpected repository metadata:** Check `package.json` `repository`, `homepage`, and `bugs` fields before publishing; they are independent of the local git remote.
|
package/lib/prompts/README.md
CHANGED
|
@@ -4,7 +4,6 @@ Markdown prompt templates for setup steps that are too context-sensitive for a s
|
|
|
4
4
|
|
|
5
5
|
| Prompt | Driven by | Purpose |
|
|
6
6
|
|--------|-----------|---------|
|
|
7
|
-
| `setup-deployment.md` | `lib/scripts/setup-deployment.sh` | Detects deployable services (Node/Python/Go/Rust) from manifest files, then creates or updates `.github/workflows/security.yml` (always overwritten — generic CodeQL + Gitleaks), `.github/workflows/build.yml` and `.gitleaks.toml` (create-once, confirm before overwrite), and `Makefile` Docker targets (merged with existing targets, never removed/reformatted). Refuses to guess service names/entrypoints it can't confidently identify — stops and asks instead. |
|
|
8
7
|
| `migrate-wiki.md` | `lib/scripts/migrate-project.sh` | Drives the semantic conversion from a legacy `.docs/`-layout project to the LLM Wiki structure, after `sync-wiki-scaffold.sh` has already created the empty scaffold. Runs headlessly with only Bash/Read/Edit/Write (explicitly told not to look for Serena MCP tools). Hard rules: `git mv` every file before editing it (preserves history), never touch `raw/` or template-owned files (`wiki/conventions.md`, `lifecycle.md`), never move a file once it lands at its new path, and never commit — leaves everything staged for the user to review. Contains the full old-path → new-path mapping table (`.docs/tasks/` → `wiki/work/tasks/TASK-NNN`, `.docs/adr/` → `wiki/work/decisions/DEC-NNNN`, etc.) and the per-family status-inference rules. |
|
|
9
8
|
| `setup-strict-typechecks.md` | `lib/scripts/setup-strict-typechecks.sh` | Scans the repo for every language with a type-checking/linting story, researches current strict-mode conventions per language (TypeScript `strict` + `typescript-eslint` strictTypeChecked, Python `mypy --strict`, Go `staticcheck`/`vet`, Rust `deny(warnings)`/Clippy, …) via Context7/Brave Search, installs the required toolchain packages, and wires the config files plus a `make typecheck` target. Accepts an optional language list from the script's CLI args to scope the run. |
|
|
10
9
|
| `setup-design-system.md` | *(none — not currently invoked by any script)* | A generic prompt for wiring an arbitrary design system into a frontend app: migrate tokens/assets into `<APP_SRC_PATH>/design-system/`, wire the CSS import into the app entry point, then convert each prototype reference component into a typed production component driven entirely by CSS custom properties. Takes `<DESIGN_SYSTEM_PATH>`, `<APP_SRC_PATH>`, `<APP_ROUTES_PATH>`, and `<SKILL_NAME>` placeholders. Kept for manual reuse (`claude < setup-design-system.md` with placeholders filled in) when onboarding a design system other than the one `lib/skills/frontend-taste` already automates (house-style, from `~/code/house-style`). |
|
package/lib/scripts/README.md
CHANGED
|
@@ -8,10 +8,9 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
|
|
|
8
8
|
|
|
9
9
|
| Script | `bootstrap` command | What it does |
|
|
10
10
|
|--------|---------------------|---------------|
|
|
11
|
-
| `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: global hooks/skills/settings install first (offline-safe, via `install-global.sh --skip-mcps` — includes the deny-list and hooks-wiring merges), then the interactive MCP install (guarded — a failure warns and continues), wiki scaffold + tiered guides sync (optional guides prompted), `.gitignore` merge, and Serena `project.yml` bootstrap.
|
|
11
|
+
| `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: global hooks/skills/settings install first (offline-safe, via `install-global.sh --skip-mcps` — includes the deny-list and hooks-wiring merges), then the interactive MCP install (guarded — a failure warns and continues), wiki scaffold + tiered guides sync (optional guides prompted), `.gitignore` merge, and Serena `project.yml` bootstrap. |
|
|
12
12
|
| `update-project.sh` | `update` | Re-runs the same shared sequence as `setup` (global hooks/skills/settings via `install-global.sh --skip-mcps`, then the guarded interactive MCP install) and re-syncs the wiki scaffold + tiered `wiki/guides/` into an existing project. Detects legacy `.docs/`-layout families (`tasks`, `uat`, `adr`, `prd`, `bugs`, `roadmaps`) and warns without touching them — migration is a separate, explicit step (`migrate`). Never touches `.github/`. |
|
|
13
13
|
| `install-global.sh` | `install` | Installs/updates hooks, skills, settings, and MCPs globally with **no project path** — the shared step both `setup` and `update` delegate to. Local/offline-safe steps run first: hooks rsync to `~/.claude/hooks/` (stderr warning if `lib/hooks` is missing), skills install (pruning stale skill folders from the wiki rename — `adr-*` → `decision-*`, `prd-*` → `req-*`), the canonical permission deny-list merge into `~/.claude/settings.json` via `merge-settings-deny.js`, then the hooks-wiring merge via `merge-settings-hooks.js` — registering the copied hook scripts in the settings `hooks` key, with a restart-your-session reminder when the wiring was created or changed. Then copies `templates/file-suggestion.sh` → `~/.claude/file-suggestion.sh` and registers it as the `fileSuggestion` `@`-autocomplete picker (`merge-settings-deny.js --set-key` mode) — printing a restart note on fresh registration, or leaving a pre-existing different `fileSuggestion` untouched. Then step 6 installs the preference helper — `bootstrap-prefs.js` → `~/.claude/bootstrap-prefs.js` and `templates/bootstrap-prefs-schema.json` → `~/.claude/templates/bootstrap-prefs-schema.json`, the layout that lets a skill read a preference with no `--schema` flag (see [Preference helper notes](#preference-helper-notes)); a missing helper or schema warns and continues. Step 7 then settles the seven `consumer: skill` preferences that have never been answered — asked once, in a batch, at global scope, gated on a tty as a whole, so a non-interactive run prints one note and writes no answers and no preferences file. MCPs install **last** (step 8) — the only network-dependent step, guarded so a failure warns instead of aborting the local installs — and `--skip-mcps` skips them when the caller already handled MCP install interactively. |
|
|
14
|
-
| `setup-deployment.sh` | `deploy` / `deployment` | Reads `raw/guides/deployment-strategy.md` as a prompt template, copies it into the target's `wiki/guides/` (deploy-only guide tier — the wiki sync never ships it), and runs `claude` to scaffold `.github/workflows/`, `Makefile` Docker targets, and `.gitleaks.toml` into the target project. Deliberately **not** called by `setup`/`update` — CI files get hand-customized per project (Dockerfile paths, runner labels, deploy steps) and must never be created or clobbered implicitly. `security.yml` is always overwritten (generic); `build.yml`/`.gitleaks.toml` are copy-once; `Makefile` targets are merged. |
|
|
15
14
|
| `migrate-project.sh` | `migrate` | Claude-driven migration of a legacy `.docs/`-layout project to the LLM Wiki structure (`wiki/knowledge/` + `wiki/work/`). Preflight requires a clean git tree; runs on a fresh `wiki-migration` branch so the whole migration is one reviewable diff. Scaffolds first via `sync-wiki-scaffold.sh --interactive`, assembles `wiki/guides/mcp-tools.md` via `build-mcp-guide.sh`, then drives the semantic conversion (frontmatter synthesis, ID renames, link rewrites, family indexes) with the prompt at `lib/prompts/migrate-wiki.md`. `git mv` before edit, so history is preserved. `--dry-run` prints the file inventory only and does not touch anything. |
|
|
16
15
|
| `setup-strict-typechecks.sh` | `typechecks` | Loads `lib/prompts/setup-strict-typechecks.md`, appends an optional language list (space- or comma-separated), and runs `claude` to detect languages, research current strict-mode conventions, install toolchains, and wire `make typecheck`. |
|
|
17
16
|
| `wiki-dashboard-server.js` | `dashboard` | Zero-dependency Node static file server (Node builtins only) that serves the live wiki dashboard client (`templates/wiki/dashboard.html`) at `/` and the project's `wiki/` tree read-only under `/wiki/*`, all with `no-store` cache headers so the polling client always sees current content. Runs in the foreground until Ctrl-C. Binds `http://localhost:4317` by default; pass a port to override (`bootstrap dashboard 4400`), and falls back to the next port (up to 10 tries) if the chosen one is in use. Unlike the other CLI scripts, this is Node, not Bash, and is long-running rather than one-shot. |
|
|
@@ -5,7 +5,7 @@ set -euo pipefail
|
|
|
5
5
|
# structure (wiki/knowledge/ + wiki/work/). The mechanical scaffold is done by
|
|
6
6
|
# sync-wiki-scaffold.sh; the semantic conversion (frontmatter synthesis, ID
|
|
7
7
|
# renames, link rewriting, family indexes) is performed by Claude using the
|
|
8
|
-
# prompt template at lib/prompts/migrate-wiki.md
|
|
8
|
+
# prompt template at lib/prompts/migrate-wiki.md.
|
|
9
9
|
#
|
|
10
10
|
# Safety: requires a clean git tree and runs on a fresh `wiki-migration` branch
|
|
11
11
|
# so the entire migration is one reviewable diff. Files are `git mv`d before
|
|
@@ -41,7 +41,6 @@ echo " 2. Open Claude Code: claude"
|
|
|
41
41
|
echo " 3. Run /init to initialize the project"
|
|
42
42
|
echo " 4. Run /primer to set up Serena's memory structure"
|
|
43
43
|
echo " 5. Drop source documents into raw/ and run /wiki-ingest <file> to grow the wiki"
|
|
44
|
-
echo " 6. Optional: run 'npx @codewizard-dt/bootstrap deploy' when you explicitly want deployment scaffolding"
|
|
45
44
|
echo ""
|
|
46
45
|
echo "API keys (if you skipped any during setup):"
|
|
47
46
|
echo " brave-search BRAVE_API_KEY https://brave.com/search/api/"
|
|
@@ -75,9 +75,8 @@ done
|
|
|
75
75
|
# missing => prompt in interactive mode (default no), skip silently
|
|
76
76
|
# otherwise. Opt out by deleting the file/dir (costs one default-no
|
|
77
77
|
# prompt per interactive update).
|
|
78
|
-
# mcp-tools.md is assembled per-project by build-mcp-guide.sh
|
|
79
|
-
#
|
|
80
|
-
# (`bootstrap deploy`) — neither is synced here.
|
|
78
|
+
# mcp-tools.md is assembled per-project by build-mcp-guide.sh and is not
|
|
79
|
+
# synced here.
|
|
81
80
|
GUIDES_SRC="$TEMPLATE_DIR/raw/guides"
|
|
82
81
|
GUIDES_DST="$PROJECT_DIR/wiki/guides"
|
|
83
82
|
LEGACY_GUIDES="$PROJECT_DIR/.docs/guides"
|
|
@@ -142,9 +141,7 @@ done
|
|
|
142
141
|
|
|
143
142
|
# 4b. LEGACY MIGRATION: guides used to live in .docs/guides/. Every
|
|
144
143
|
# template-owned guide found there is removed (fresh copies now land in
|
|
145
|
-
# wiki/guides/ above)
|
|
146
|
-
# when `bootstrap deploy` has run (its build.yml marker exists) and
|
|
147
|
-
# deleted otherwise. User-authored files in .docs/guides/ are untouched.
|
|
144
|
+
# wiki/guides/ above). User-authored files in .docs/guides/ are untouched.
|
|
148
145
|
# Also removes deprecated task-spec.md from either location (superseded by
|
|
149
146
|
# wiki/work/tasks/lifecycle.md, which it actively contradicts).
|
|
150
147
|
if [ -d "$LEGACY_GUIDES" ]; then
|
|
@@ -154,15 +151,6 @@ if [ -d "$LEGACY_GUIDES" ]; then
|
|
|
154
151
|
echo " Migrated: removed .docs/guides/$legacy (guides now live in wiki/guides/)."
|
|
155
152
|
fi
|
|
156
153
|
done
|
|
157
|
-
if [ -f "$LEGACY_GUIDES/deployment-strategy.md" ]; then
|
|
158
|
-
if [ -f "$PROJECT_DIR/.github/workflows/build.yml" ]; then
|
|
159
|
-
mv "$LEGACY_GUIDES/deployment-strategy.md" "$GUIDES_DST/deployment-strategy.md"
|
|
160
|
-
echo " Migrated: moved deployment-strategy.md to wiki/guides/ (deploy artifacts present)."
|
|
161
|
-
else
|
|
162
|
-
rm -f "$LEGACY_GUIDES/deployment-strategy.md"
|
|
163
|
-
echo " Removed deployment-strategy.md (deploy-only guide; delivered by 'npx @codewizard-dt/bootstrap deploy')."
|
|
164
|
-
fi
|
|
165
|
-
fi
|
|
166
154
|
# Drop the legacy dirs when empty; scratch content (.docs/demo etc.) is kept.
|
|
167
155
|
rmdir "$LEGACY_GUIDES" 2>/dev/null && echo " Removed empty .docs/guides/." || true
|
|
168
156
|
rmdir "$PROJECT_DIR/.docs" 2>/dev/null || true
|
|
@@ -19,11 +19,11 @@ CLAUDE.md This schema section.
|
|
|
19
19
|
|
|
20
20
|
**`wiki/work/`** — stateful lifecycle artifacts, organized by status. Active files are **never moved** after creation; state lives in the `status:` frontmatter field. Each family has a `lifecycle.md` (schema + valid transitions), an `index.md` listing **only active items**, and an `archive/` subdirectory for terminal items. When an item leaves the active set, delete its line from the family index; terminal items may be moved to `archive/` by `/wiki-archive`.
|
|
21
21
|
|
|
22
|
-
- `wiki/work/requirements/` — REQ-
|
|
22
|
+
- `wiki/work/requirements/` — REQ-NNNN
|
|
23
23
|
- `wiki/work/decisions/` — DEC-NNNN (per-decision `#DM`)
|
|
24
|
-
- `wiki/work/roadmaps/` — ROADMAP-
|
|
25
|
-
- `wiki/work/tasks/` — TASK-
|
|
26
|
-
- `wiki/work/uat/` — UAT-
|
|
24
|
+
- `wiki/work/roadmaps/` — ROADMAP-NNNN
|
|
25
|
+
- `wiki/work/tasks/` — TASK-NNNN
|
|
26
|
+
- `wiki/work/uat/` — UAT-NNNN (own family, one per task)
|
|
27
27
|
- `wiki/work/bugs/` — BUG-NNNN
|
|
28
28
|
|
|
29
29
|
**`wiki/guides/`** — template-owned reference guides delivered by the bootstrap tooling (MCP tool rules in `mcp-tools.md`, shell anti-patterns, opted-in frameworks like evals or type-checking templates). Read them and obey them; **never edit them** — they are refreshed by `npx @codewizard-dt/bootstrap update` and any local edit will be overwritten. They are infrastructure, not wiki content: no frontmatter, no index entries, exempt from the atomic-page rule.
|
|
@@ -66,7 +66,7 @@
|
|
|
66
66
|
"scope": "project",
|
|
67
67
|
"consumer": "installer",
|
|
68
68
|
"summary": "Install a specific optional guide into wiki/guides/",
|
|
69
|
-
"detail": "One key per entry in sync-wiki-scaffold.sh's OPTIONAL_GUIDES list (sync-wiki-scaffold.sh:
|
|
69
|
+
"detail": "One key per entry in sync-wiki-scaffold.sh's OPTIONAL_GUIDES list (sync-wiki-scaffold.sh:87), keyed by the exact entry text including any extension — today that is guides.evals-framework.md and guides.type-checking-templates. true delivers the guide into wiki/guides/ on every run; false keeps it out and suppresses the per-run prompt. A guide already present in wiki/guides/ (or in the legacy .docs/guides/) is refreshed regardless of this key — existing opt-in wins, because the file on disk is the stronger signal than a stored answer. The required guide tier is never gated by these keys.",
|
|
70
70
|
"values": "true | false",
|
|
71
71
|
"default": null,
|
|
72
72
|
"askedBy": "sync-wiki-scaffold.sh",
|
|
@@ -21,7 +21,7 @@ Why this is the one expensive-to-defer rule: typed links, Maps of Content, super
|
|
|
21
21
|
|
|
22
22
|
Reference pages by a **stable identity**, not a raw file path — so links survive reorganization.
|
|
23
23
|
|
|
24
|
-
- **Work families** carry an ID in frontmatter and filename: `REQ-
|
|
24
|
+
- **Work families** carry an ID in frontmatter and filename: `REQ-NNNN`, `DEC-NNNN` (per-decision `#DM`), `ROADMAP-NNNN`, `TASK-NNNN`, `UAT-NNNN`, `BUG-NNNN`.
|
|
25
25
|
- **Knowledge pages** carry an `id` (kebab-case slug) plus an `aliases:` list of alternative names. Link by title/alias (`[[Karpathy]]`) rather than by path; the alias makes the reference durable even if the file moves.
|
|
26
26
|
|
|
27
27
|
## 3. Typed links
|
|
@@ -850,12 +850,12 @@
|
|
|
850
850
|
// Two supported source formats:
|
|
851
851
|
//
|
|
852
852
|
// 1. Active-index bullet lines (all sub-parts optional):
|
|
853
|
-
// - [TASK-
|
|
853
|
+
// - [TASK-NNNN — Title](TASK-NNNN-slug.md) — summary · status
|
|
854
854
|
// Separators matched literally: em dash — (U+2014) between title and
|
|
855
855
|
// summary; middle dot · (U+00B7) before status suffix(es).
|
|
856
856
|
//
|
|
857
857
|
// 2. Archive-index table rows:
|
|
858
|
-
// | [[TASK-
|
|
858
|
+
// | [[TASK-NNNN]] | Title | Final Status | Archived |
|
|
859
859
|
// A data row is identified by its first cell being a [[...]] wiki-link
|
|
860
860
|
// (the header and |----| separator rows fail that gate). Escaped
|
|
861
861
|
// pipes (\|) inside cells are handled. Archive rows have no markdown
|
|
@@ -38,11 +38,11 @@ _(none yet)_ — one page per entity, filed by sub-type:
|
|
|
38
38
|
|
|
39
39
|
Each family's `index.md` lists its **active items only** (completed/terminal items drop off the list; files never move — status lives in frontmatter).
|
|
40
40
|
|
|
41
|
-
- **Requirements** — REQ-
|
|
41
|
+
- **Requirements** — REQ-NNNN. [Active index](work/requirements/index.md) · [lifecycle](work/requirements/lifecycle.md)
|
|
42
42
|
- **Decisions** — DEC-NNNN (per-decision `#DM`). [Active index](work/decisions/index.md) · [lifecycle](work/decisions/lifecycle.md)
|
|
43
|
-
- **Roadmaps** — ROADMAP-
|
|
44
|
-
- **Tasks** — TASK-
|
|
45
|
-
- **UAT** — UAT-
|
|
43
|
+
- **Roadmaps** — ROADMAP-NNNN. [Active index](work/roadmaps/index.md) · [lifecycle](work/roadmaps/lifecycle.md)
|
|
44
|
+
- **Tasks** — TASK-NNNN. [Active index](work/tasks/index.md) · [lifecycle](work/tasks/lifecycle.md)
|
|
45
|
+
- **UAT** — UAT-NNNN, one per task. [Active index](work/uat/index.md) · [lifecycle](work/uat/lifecycle.md)
|
|
46
46
|
- **Bugs** — BUG-NNNN. [Active index](work/bugs/index.md) · [lifecycle](work/bugs/lifecycle.md)
|
|
47
47
|
|
|
48
48
|
---
|
|
@@ -7,6 +7,6 @@ updated: 2026-06-11
|
|
|
7
7
|
|
|
8
8
|
Lists **only active** requirements (`draft`, `approved`). When an item leaves the active set (`retired`), delete its line here — the file itself never moves; status lives in its frontmatter. See the [lifecycle](lifecycle.md).
|
|
9
9
|
|
|
10
|
-
Entry format: `- [REQ-
|
|
10
|
+
Entry format: `- [REQ-NNNN — Title](REQ-NNNN-slug.md) — one-line summary · status`
|
|
11
11
|
|
|
12
12
|
_(none yet)_
|
|
@@ -5,7 +5,7 @@ updated: 2026-06-11
|
|
|
5
5
|
|
|
6
6
|
# Requirements Lifecycle
|
|
7
7
|
|
|
8
|
-
Requirements (PRDs) capture the problem, personas, user stories, success metrics, and non-goals for a body of work. ID scheme: **REQ-
|
|
8
|
+
Requirements (PRDs) capture the problem, personas, user stories, success metrics, and non-goals for a body of work. ID scheme: **REQ-NNNN** (4-digit, zero-padded, globally unique). Filename: `REQ-NNNN-slug.md`.
|
|
9
9
|
|
|
10
10
|
Active files are **never moved** after creation; state lives in the `status:` frontmatter field. Terminal items (`retired`) may be moved to [`archive/`](archive/) by `/wiki-archive`. The active set is tracked in [`index.md`](index.md).
|
|
11
11
|
|
|
@@ -13,7 +13,7 @@ Active files are **never moved** after creation; state lives in the `status:` fr
|
|
|
13
13
|
|
|
14
14
|
| Key | Required | Notes |
|
|
15
15
|
|-----|----------|-------|
|
|
16
|
-
| `id` | yes | `REQ-
|
|
16
|
+
| `id` | yes | `REQ-NNNN` |
|
|
17
17
|
| `title` | yes | short requirement name |
|
|
18
18
|
| `status` | yes | `draft \| approved \| retired` |
|
|
19
19
|
| `created` / `updated` | yes | `YYYY-MM-DD` |
|
|
@@ -7,6 +7,6 @@ updated: 2026-06-11
|
|
|
7
7
|
|
|
8
8
|
Lists **only active** roadmaps (`active`). When a roadmap completes (`done`), delete its line here — the file itself never moves; status lives in its frontmatter. See the [lifecycle](lifecycle.md).
|
|
9
9
|
|
|
10
|
-
Entry format: `- [ROADMAP-
|
|
10
|
+
Entry format: `- [ROADMAP-NNNN — Title](ROADMAP-NNNN-slug.md) — one-line summary · N/M items checked`
|
|
11
11
|
|
|
12
12
|
_(none yet)_
|
|
@@ -5,7 +5,7 @@ updated: 2026-06-11
|
|
|
5
5
|
|
|
6
6
|
# Roadmaps Lifecycle
|
|
7
7
|
|
|
8
|
-
Execution-plan roadmaps: a goal, phases, and a hybrid checklist where each item is either a **task link** (`[TASK-
|
|
8
|
+
Execution-plan roadmaps: a goal, phases, and a hybrid checklist where each item is either a **task link** (`[TASK-NNNN](../tasks/TASK-NNNN-slug.md)`) or an **inline** checkbox item. ID scheme: **ROADMAP-NNNN** (4-digit, zero-padded). Filename: `ROADMAP-NNNN-slug.md`.
|
|
9
9
|
|
|
10
10
|
Active files are **never moved** after creation; state lives in the `status:` frontmatter field. Terminal items (`done`) may be moved to [`archive/`](archive/) by `/wiki-archive`. The active set is tracked in [`index.md`](index.md).
|
|
11
11
|
|
|
@@ -13,12 +13,12 @@ Active files are **never moved** after creation; state lives in the `status:` fr
|
|
|
13
13
|
|
|
14
14
|
| Key | Required | Notes |
|
|
15
15
|
|-----|----------|-------|
|
|
16
|
-
| `id` | yes | `ROADMAP-
|
|
16
|
+
| `id` | yes | `ROADMAP-NNNN` |
|
|
17
17
|
| `title` | yes | roadmap goal |
|
|
18
18
|
| `status` | yes | `active \| done` |
|
|
19
19
|
| `created` / `updated` | yes | `YYYY-MM-DD` |
|
|
20
20
|
| `owner` | no | accountable person/role |
|
|
21
|
-
| `linked_requirements` | no | `REQ-
|
|
21
|
+
| `linked_requirements` | no | `REQ-NNNN` back-links |
|
|
22
22
|
| `linked_decisions` | no | `DEC-NNNN` back-links |
|
|
23
23
|
| `tags` | no | discovery only |
|
|
24
24
|
|
|
@@ -28,5 +28,5 @@ Active files are **never moved** after creation; state lives in the `status:` fr
|
|
|
28
28
|
active ──▶ done
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
- **active** — at least one unchecked item remains. Items are added by editing the roadmap file directly, at creation via `/roadmap-create`, or via `/task-add --roadmap ROADMAP-
|
|
31
|
+
- **active** — at least one unchecked item remains. Items are added by editing the roadmap file directly, at creation via `/roadmap-create`, or via `/task-add --roadmap ROADMAP-NNNN` (auto-links a new task); task-linked items auto-check when their task completes.
|
|
32
32
|
- **done** — every checklist item is checked. Completion is implicit; flip `status` to `done` when the last box is ticked.
|
|
@@ -7,6 +7,6 @@ updated: 2026-06-11
|
|
|
7
7
|
|
|
8
8
|
Lists **only active** tasks (`todo`, `in-progress`). When a task leaves the active set (`done`, `trashed`), delete its line here — the file itself never moves; status lives in its frontmatter. See the [lifecycle](lifecycle.md).
|
|
9
9
|
|
|
10
|
-
Entry format: `- [TASK-
|
|
10
|
+
Entry format: `- [TASK-NNNN — Title](TASK-NNNN-slug.md) — one-line summary · status`
|
|
11
11
|
|
|
12
12
|
_(none yet)_
|
|
@@ -5,7 +5,7 @@ updated: 2026-06-11
|
|
|
5
5
|
|
|
6
6
|
# Tasks Lifecycle
|
|
7
7
|
|
|
8
|
-
Execution-ready task files with `## Steps` checklists. ID scheme: **TASK-
|
|
8
|
+
Execution-ready task files with `## Steps` checklists. ID scheme: **TASK-NNNN** (4-digit, zero-padded). Filename: `TASK-NNNN-slug.md`. UAT test files mirror task naming (**UAT-NNNN**) and live in the sibling [`../uat/`](../uat/) family.
|
|
9
9
|
|
|
10
10
|
Active files are **never moved** after creation; state lives in the `status:` frontmatter field. Terminal items (`done`, `trashed`) may be moved to [`archive/`](archive/) by `/wiki-archive`. The active set is tracked in [`index.md`](index.md).
|
|
11
11
|
|
|
@@ -13,14 +13,14 @@ Active files are **never moved** after creation; state lives in the `status:` fr
|
|
|
13
13
|
|
|
14
14
|
| Key | Required | Notes |
|
|
15
15
|
|-----|----------|-------|
|
|
16
|
-
| `id` | yes | `TASK-
|
|
16
|
+
| `id` | yes | `TASK-NNNN` |
|
|
17
17
|
| `title` | yes | task title |
|
|
18
18
|
| `status` | yes | `todo \| in-progress \| done \| trashed` |
|
|
19
19
|
| `created` / `updated` | yes | `YYYY-MM-DD` |
|
|
20
|
-
| `depends_on` | no | `TASK-
|
|
21
|
-
| `blocks` | no | `TASK-
|
|
22
|
-
| `parallel_safe_with` | no | `TASK-
|
|
23
|
-
| `uat` | no | link to the matching `../uat/UAT-
|
|
20
|
+
| `depends_on` | no | `TASK-NNNN` IDs that must finish first |
|
|
21
|
+
| `blocks` | no | `TASK-NNNN` IDs this one gates |
|
|
22
|
+
| `parallel_safe_with` | no | `TASK-NNNN` IDs safe to run concurrently |
|
|
23
|
+
| `uat` | no | link to the matching `../uat/UAT-NNNN-slug.md` |
|
|
24
24
|
| `tags` | no | discovery only |
|
|
25
25
|
|
|
26
26
|
## Status transitions
|
|
@@ -7,6 +7,6 @@ updated: 2026-06-11
|
|
|
7
7
|
|
|
8
8
|
Lists **only active** UAT files (`pending`, `in-progress`, `failed`). When a UAT leaves the active set (`passed`, `skipped`, `trashed`), delete its line here — the file itself never moves; status lives in its frontmatter. See the [lifecycle](lifecycle.md).
|
|
9
9
|
|
|
10
|
-
Entry format: `- [UAT-
|
|
10
|
+
Entry format: `- [UAT-NNNN — Title](UAT-NNNN-slug.md) — verifies TASK-NNNN · status`
|
|
11
11
|
|
|
12
12
|
_(none yet)_
|
|
@@ -5,7 +5,7 @@ updated: 2026-06-11
|
|
|
5
5
|
|
|
6
6
|
# UAT Lifecycle
|
|
7
7
|
|
|
8
|
-
User-acceptance test files, one per task. ID scheme: **UAT-
|
|
8
|
+
User-acceptance test files, one per task. ID scheme: **UAT-NNNN** (4-digit, zero-padded) — the number **mirrors the task it verifies** (`UAT-0014` ↔ `TASK-0014`). Filename: `UAT-NNNN-slug.md`.
|
|
9
9
|
|
|
10
10
|
Active files are **never moved** after creation; state lives in the `status:` frontmatter field. Terminal items (`passed`, `skipped`, `trashed`) may be moved to [`archive/`](archive/) by `/wiki-archive`. The active set is tracked in [`index.md`](index.md).
|
|
11
11
|
|
|
@@ -13,14 +13,14 @@ Active files are **never moved** after creation; state lives in the `status:` fr
|
|
|
13
13
|
|
|
14
14
|
| Key | Required | Notes |
|
|
15
15
|
|-----|----------|-------|
|
|
16
|
-
| `id` | yes | `UAT-
|
|
16
|
+
| `id` | yes | `UAT-NNNN` |
|
|
17
17
|
| `title` | yes | UAT title |
|
|
18
18
|
| `status` | yes | `pending \| in-progress \| passed \| failed \| skipped \| trashed` |
|
|
19
|
-
| `task` | yes | `TASK-
|
|
19
|
+
| `task` | yes | `TASK-NNNN` back-link to the task under test |
|
|
20
20
|
| `created` / `updated` | yes | `YYYY-MM-DD` |
|
|
21
21
|
| `tags` | no | discovery only |
|
|
22
22
|
|
|
23
|
-
The body carries an `implements::[[TASK-
|
|
23
|
+
The body carries an `implements::[[TASK-NNNN]]` typed link; the task carries a `uat:` frontmatter link back (`../uat/UAT-NNNN-slug.md`).
|
|
24
24
|
|
|
25
25
|
## Per-test markers
|
|
26
26
|
|
package/lib/skills/README.md
CHANGED
|
@@ -19,7 +19,7 @@ Most skills operate on the LLM Wiki (`wiki/`, `raw/`) described in the root `CLA
|
|
|
19
19
|
|
|
20
20
|
| Skill | Purpose |
|
|
21
21
|
|-------|---------|
|
|
22
|
-
| `req-create` | Draft a new requirement (REQ-
|
|
22
|
+
| `req-create` | Draft a new requirement (REQ-NNNN) via Socratic Q&A — problem, personas, user stories, success metrics, non-goals |
|
|
23
23
|
| `req-finalize` | Run a completeness audit on a draft requirement, resolve gaps via Q&A, flip `status: draft → approved` |
|
|
24
24
|
| `req-extract-decisions` | Extract Architecturally Significant Requirements from an approved requirement and propose Decision Group candidates |
|
|
25
25
|
| `req-update` | Amend an approved requirement with a tracked, append-only Amendment block; direct edits for drafts |
|
|
@@ -104,6 +104,7 @@ Most skills operate on the LLM Wiki (`wiki/`, `raw/`) described in the root `CLA
|
|
|
104
104
|
| Skill | Purpose |
|
|
105
105
|
|-------|---------|
|
|
106
106
|
| `security-audit` | Audit an LLM/AI application across 11 categories — internal posture (observability, rate limiting, access controls, HITL policy, benchmarking) and external threats (prompt injection, data leakage, output XSS, excessive agency, supply chain, token DoS) |
|
|
107
|
+
| `architecture-audit` | Audit an AI agent/application's architecture across 9 categories — design fit (single- vs. multi-agent justification, orchestration topology, delegation hygiene, framework/SDK fit, compounding-error containment) and operational readiness (observability, cost/resource controls, context/state management, cross-agent safety composition) |
|
|
107
108
|
|
|
108
109
|
## Porting & extraction
|
|
109
110
|
|