@codewizard-dt/bootstrap 2.10.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/.github/workflows/build.yml +88 -0
- package/.github/workflows/security.yml +24 -0
- package/.gitleaks.toml +15 -0
- package/README.md +472 -0
- package/bin/cli.js +47 -0
- package/lib/README.md +27 -0
- package/lib/hooks/README.md +316 -0
- package/lib/hooks/env-file-guard.js +45 -0
- package/lib/hooks/git-protected-ops-block.js +77 -0
- package/lib/hooks/lib/serena-languages.js +158 -0
- package/lib/hooks/lib/serena.js +787 -0
- package/lib/hooks/mv-absolute-path-block.js +53 -0
- package/lib/hooks/serena-bash-grep-block.js +501 -0
- package/lib/hooks/serena-edit-guard.js +74 -0
- package/lib/hooks/serena-first-glob-guard.js +94 -0
- package/lib/hooks/serena-first-guard.js +74 -0
- package/lib/hooks/serena-first-read-guard.js +167 -0
- package/lib/hooks/serena-pre-delegation.js +117 -0
- package/lib/hooks/serena-session-reset.js +45 -0
- package/lib/hooks/serena-usage-tracker.js +186 -0
- package/lib/hooks/serena-write-guard.js +58 -0
- package/lib/prompts/README.md +16 -0
- package/lib/prompts/migrate-wiki.md +111 -0
- package/lib/prompts/setup-deployment.md +322 -0
- package/lib/prompts/setup-design-system.md +162 -0
- package/lib/prompts/setup-strict-typechecks.md +139 -0
- package/lib/scripts/README.md +49 -0
- package/lib/scripts/bootstrap-serena.sh +145 -0
- package/lib/scripts/build-mcp-guide.sh +108 -0
- package/lib/scripts/install-global.sh +78 -0
- package/lib/scripts/install-mcps.sh +131 -0
- package/lib/scripts/lib.sh +154 -0
- package/lib/scripts/merge-gitignore.sh +65 -0
- package/lib/scripts/migrate-project.sh +273 -0
- package/lib/scripts/setup-deployment.sh +104 -0
- package/lib/scripts/setup-project.sh +55 -0
- package/lib/scripts/setup-runner.sh +99 -0
- package/lib/scripts/setup-strict-typechecks.sh +29 -0
- package/lib/scripts/startup.sh +42 -0
- package/lib/scripts/sync-wiki-scaffold.sh +104 -0
- package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
- package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
- package/lib/scripts/templates/gitignore +136 -0
- package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
- package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
- package/lib/scripts/templates/guides/stubs/context7.md +26 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
- package/lib/scripts/templates/guides/stubs/serena.md +219 -0
- package/lib/scripts/templates/wiki/conventions.md +100 -0
- package/lib/scripts/templates/wiki/dashboard.html +1733 -0
- package/lib/scripts/templates/wiki/hot.md +21 -0
- package/lib/scripts/templates/wiki/index.md +46 -0
- package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/log.md +14 -0
- package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
- package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
- package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
- package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
- package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
- package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
- package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
- package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
- package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
- package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
- package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
- package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
- package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
- package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
- package/lib/scripts/update-project.sh +75 -0
- package/lib/scripts/wiki-dashboard-server.js +146 -0
- package/lib/skills/README.md +146 -0
- package/lib/skills/anti-slop/SKILL.md +183 -0
- package/lib/skills/bug-close/SKILL.md +136 -0
- package/lib/skills/bug-file/SKILL.md +114 -0
- package/lib/skills/bug-triage/SKILL.md +140 -0
- package/lib/skills/company-align/SKILL.md +203 -0
- package/lib/skills/debug-logs/SKILL.md +129 -0
- package/lib/skills/decision-create/SKILL.md +220 -0
- package/lib/skills/decision-finalize/SKILL.md +181 -0
- package/lib/skills/decision-next/SKILL.md +129 -0
- package/lib/skills/decision-walkthrough/SKILL.md +169 -0
- package/lib/skills/demo/SKILL.md +183 -0
- package/lib/skills/elevator-pitch/SKILL.md +125 -0
- package/lib/skills/eval-create/SKILL.md +344 -0
- package/lib/skills/eval-gap/SKILL.md +150 -0
- package/lib/skills/eval-run/SKILL.md +214 -0
- package/lib/skills/extract-feature/SKILL.md +344 -0
- package/lib/skills/flashcard/SKILL.md +513 -0
- package/lib/skills/frontend-taste/SKILL.md +184 -0
- package/lib/skills/gap-assess/SKILL.md +97 -0
- package/lib/skills/git-commit/SKILL.md +164 -0
- package/lib/skills/lint/SKILL.md +99 -0
- package/lib/skills/marp-slideshow/SKILL.md +212 -0
- package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
- package/lib/skills/now/SKILL.md +36 -0
- package/lib/skills/port-feature/SKILL.md +315 -0
- package/lib/skills/power-mode/SKILL.md +184 -0
- package/lib/skills/primer/SKILL.md +84 -0
- package/lib/skills/project-readme/SKILL.md +166 -0
- package/lib/skills/req-compile/SKILL.md +131 -0
- package/lib/skills/req-create/SKILL.md +124 -0
- package/lib/skills/req-extract-decisions/SKILL.md +241 -0
- package/lib/skills/req-finalize/SKILL.md +251 -0
- package/lib/skills/req-retire/SKILL.md +185 -0
- package/lib/skills/req-update/SKILL.md +265 -0
- package/lib/skills/research/SKILL.md +250 -0
- package/lib/skills/research-company/SKILL.md +345 -0
- package/lib/skills/roadmap-add/SKILL.md +238 -0
- package/lib/skills/roadmap-create/SKILL.md +223 -0
- package/lib/skills/roadmap-next/SKILL.md +132 -0
- package/lib/skills/security-audit/SKILL.md +246 -0
- package/lib/skills/serena-config/SKILL.md +92 -0
- package/lib/skills/simplify/SKILL.md +227 -0
- package/lib/skills/tackle/SKILL.md +156 -0
- package/lib/skills/task-add/SKILL.md +208 -0
- package/lib/skills/task-audit/SKILL.md +294 -0
- package/lib/skills/task-trash/SKILL.md +115 -0
- package/lib/skills/task-update/SKILL.md +136 -0
- package/lib/skills/uat-auto/SKILL.md +69 -0
- package/lib/skills/uat-auto-plus/SKILL.md +115 -0
- package/lib/skills/uat-generate/SKILL.md +289 -0
- package/lib/skills/uat-skip/SKILL.md +169 -0
- package/lib/skills/uat-walk/SKILL.md +164 -0
- package/lib/skills/uat-walk/UAT-CORE.md +140 -0
- package/lib/skills/update-docs/SKILL.md +75 -0
- package/lib/skills/wiki-archive/SKILL.md +96 -0
- package/lib/skills/wiki-ingest/SKILL.md +139 -0
- package/lib/skills/wiki-lint/SKILL.md +131 -0
- package/lib/skills/wiki-query/SKILL.md +71 -0
- package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
- package/lib/skills/wiki-tidy/SKILL.md +107 -0
- package/package.json +32 -0
- package/raw/.gitkeep +0 -0
- package/raw/design-principles.md +65 -0
- package/raw/guides/command-anti-patterns.md +79 -0
- package/raw/guides/deployment-strategy.md +448 -0
- package/raw/guides/evals-framework.md +452 -0
- package/raw/guides/mcp-tools.md +335 -0
- package/raw/guides/task-spec.md +79 -0
- package/raw/guides/type-checking-templates/README.md +112 -0
- package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
- package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
- package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
- package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
- package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
- package/raw/harness-notes.md +20 -0
- package/raw/house-style/components/Badge.tsx +16 -0
- package/raw/house-style/components/Button.tsx +32 -0
- package/raw/house-style/components/Card.tsx +26 -0
- package/raw/house-style/components/Chip.tsx +57 -0
- package/raw/house-style/components/IconButton.tsx +67 -0
- package/raw/house-style/components/Modal.tsx +18 -0
- package/raw/house-style/components/Stepper.tsx +141 -0
- package/raw/house-style/components/icons.tsx +128 -0
- package/raw/house-style/preview/src/index.css +46 -0
- package/raw/house-style/tokens/tailwind.preset.ts +49 -0
- package/raw/house-style/tokens/tokens.json +62 -0
- package/raw/llm-wiki-2.md +162 -0
- package/raw/llm-wiki.md +75 -0
- package/raw/research/dark-mode-theme/index.md +85 -0
- package/raw/research/dark-mode-theme/sources.md +49 -0
- package/raw/research/serena-mcp-disconnect/index.md +81 -0
- package/raw/research/serena-mcp-disconnect/sources.md +87 -0
- package/raw/research/wiki-tooling-improvements/index.md +126 -0
- package/raw/research/wiki-tooling-improvements/sources.md +73 -0
- package/raw/software-factory-case-study.pdf +0 -0
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mermaid-flowchart
|
|
3
|
+
description: Summarize an architecture file (markdown, YAML, Docker Compose) into a Mermaid flowchart in a new markdown file
|
|
4
|
+
category: executing
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
argument-hint: <path to source file> [optional output path]
|
|
7
|
+
disable-model-invocation: false
|
|
8
|
+
user-invocable: true
|
|
9
|
+
---
|
|
10
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
11
|
+
|
|
12
|
+
# Mermaid Flowchart
|
|
13
|
+
|
|
14
|
+
Read a source file at the path supplied in `$ARGUMENTS`, distill it into a structured set of nodes and edges, and emit a **Markdown file containing a Mermaid `flowchart` block** that visualizes the architecture, services, or component relationships.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
**Source / args**: `$ARGUMENTS`
|
|
19
|
+
|
|
20
|
+
The first whitespace-separated token is the **input path** (required). An optional second token is the **output path**. If not provided, derive `<input-stem>.flowchart.md` next to the input file (e.g. `architecture.md` → `architecture.flowchart.md`, `docker-compose.yml` → `docker-compose.flowchart.md`).
|
|
21
|
+
|
|
22
|
+
If `$ARGUMENTS` is empty, ask the user for the input path before proceeding.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Phase 1 — Read & Detect Type
|
|
27
|
+
|
|
28
|
+
1. Read the input file with `Read` (markdown / YAML / config). Never `cat`/`head`. For source code referenced from the architecture doc, use `mcp__serena__get_symbols_overview` if you need to verify a claim.
|
|
29
|
+
2. **Detect the input shape** — your extraction strategy depends on this:
|
|
30
|
+
- **Docker Compose YAML** (filename contains `docker-compose` or top-level `services:` key with `image:`/`build:` children) → use the Docker Compose extraction rules in Phase 2A.
|
|
31
|
+
- **Generic YAML / config** (Kubernetes manifests, Terraform-ish, CI configs, `serverless.yml`, etc.) → use the Generic YAML extraction rules in Phase 2B.
|
|
32
|
+
- **Markdown architecture doc** → use the Markdown extraction rules in Phase 2C.
|
|
33
|
+
3. If the file is ambiguous (e.g. markdown that embeds a compose snippet), pick the dominant content type and treat embedded snippets as supplementary.
|
|
34
|
+
|
|
35
|
+
## Phase 2 — Extract Nodes & Edges
|
|
36
|
+
|
|
37
|
+
Aim for **5–25 nodes**. If the source has more, group related items into subgraphs and collapse leaf detail. Fewer than 5 means the diagram is probably not worth drawing — ask the user whether to proceed.
|
|
38
|
+
|
|
39
|
+
### 2A — Docker Compose
|
|
40
|
+
|
|
41
|
+
For each top-level `services.<name>`:
|
|
42
|
+
|
|
43
|
+
- **Node** = the service. Pick a shape:
|
|
44
|
+
- Database images (`postgres`, `mysql`, `mongo`, `redis`, `mariadb`, `cockroach`, etc.) → cylinder `[(name)]`
|
|
45
|
+
- Message brokers / queues (`rabbitmq`, `kafka`, `nats`, `redis` used as broker) → hexagon `{{name}}`
|
|
46
|
+
- Web/API/app services → rounded rectangle `(name)` or rectangle `[name]`
|
|
47
|
+
- Reverse proxies / load balancers (`nginx`, `traefik`, `caddy`, `haproxy`) → parallelogram `[/name\]`
|
|
48
|
+
- Workers / cron / one-shot jobs → stadium `([name])`
|
|
49
|
+
- **Edges** from explicit relationships:
|
|
50
|
+
- `depends_on:` → `dependent --> dependency`
|
|
51
|
+
- `links:` (legacy) → same as depends_on
|
|
52
|
+
- Env vars that reference another service hostname (e.g. `DATABASE_URL=postgres://db:5432`) → labelled edge `app -->|sql| db`
|
|
53
|
+
- `ports:` exposed to host → add an external entry node `Client((Client))` with edge `Client -->|:8080| app`
|
|
54
|
+
- **Subgraphs** for `networks:` if more than one network is defined. Otherwise omit.
|
|
55
|
+
- **Volumes** are usually noise — only include when a named volume connects multiple services or the user explicitly wants storage shown.
|
|
56
|
+
|
|
57
|
+
### 2B — Generic YAML / Config
|
|
58
|
+
|
|
59
|
+
Look for the structural patterns the file uses to define components:
|
|
60
|
+
|
|
61
|
+
- Top-level lists or maps of named items (`resources:`, `components:`, `functions:`, `pipelines:`, `jobs:`, `steps:`) → each item is a candidate node.
|
|
62
|
+
- Cross-references (a value that names another key in the file) → candidate edge.
|
|
63
|
+
- For Kubernetes: `Deployment` / `StatefulSet` / `Service` / `Ingress` → nodes; `selector` / `serviceName` / `backend.service.name` → edges.
|
|
64
|
+
- For CI configs (`needs:`, `requires:`, `dependsOn:`) → DAG edges.
|
|
65
|
+
|
|
66
|
+
If the file's structure is unclear, summarize what you found and ask the user which level of detail to render before writing the deck.
|
|
67
|
+
|
|
68
|
+
### 2C — Markdown Architecture Doc
|
|
69
|
+
|
|
70
|
+
Scan headings and prose for:
|
|
71
|
+
|
|
72
|
+
- Lists of components, services, modules, layers — each becomes a node.
|
|
73
|
+
- ASCII art diagrams (e.g. `[A] -> [B]`) — translate them directly.
|
|
74
|
+
- Phrases that imply edges: "X calls Y", "X publishes to Y", "Y subscribes from X", "data flows from X to Y", "X depends on Y", "X writes to Y", "Y reads from X".
|
|
75
|
+
- Existing Mermaid blocks — if the doc already contains one, treat it as the source of truth and *enhance* rather than reinvent (e.g. add missing edges from prose, normalize node IDs).
|
|
76
|
+
|
|
77
|
+
Group nodes into subgraphs when the doc uses section headings like "Frontend", "Backend", "Data layer", "External services" — those headings usually map cleanly onto subgraph boundaries.
|
|
78
|
+
|
|
79
|
+
## Phase 3 — Plan the Diagram
|
|
80
|
+
|
|
81
|
+
Decide before writing:
|
|
82
|
+
|
|
83
|
+
- **Direction**: `TD` (top-down) for layered architectures (client → app → data); `LR` (left-right) for pipelines, request flows, or DAGs with many sequential steps. Default to `LR` for compose files, `TD` for layered markdown architectures.
|
|
84
|
+
- **Subgraphs**: group nodes that share a tier, network, or bounded context. Do not nest subgraphs more than 2 deep — Mermaid renders them poorly.
|
|
85
|
+
- **Edge labels**: add a short label (`-->|HTTP|`, `-->|gRPC|`, `-->|publishes|`) when the edge type is non-obvious. Skip labels when every edge is the same kind ("depends on") — the diagram is cleaner without them.
|
|
86
|
+
- **Styling**: define 2–4 classes for visual grouping (e.g. `classDef db fill:#fef3c7,stroke:#b45309;`). Don't go beyond 4 — more becomes noise.
|
|
87
|
+
- **External actors**: if requests originate from outside the system, add a `Client((Client))` or `User((User))` node so the entry point is explicit.
|
|
88
|
+
|
|
89
|
+
## Phase 4 — Write the Output
|
|
90
|
+
|
|
91
|
+
Use the `Write` tool to create the output markdown file. The file **must** follow this template:
|
|
92
|
+
|
|
93
|
+
````markdown
|
|
94
|
+
# {Title derived from source filename or H1 of source}
|
|
95
|
+
|
|
96
|
+
> Auto-generated from `{relative path to source}` by `/mermaid-flowchart`.
|
|
97
|
+
|
|
98
|
+
```mermaid
|
|
99
|
+
flowchart LR
|
|
100
|
+
%% Node definitions
|
|
101
|
+
Client((Client))
|
|
102
|
+
Web[Web app]
|
|
103
|
+
API(API service)
|
|
104
|
+
DB[(Postgres)]
|
|
105
|
+
Cache[(Redis)]
|
|
106
|
+
Queue{{RabbitMQ}}
|
|
107
|
+
Worker([Worker])
|
|
108
|
+
|
|
109
|
+
%% Edges
|
|
110
|
+
Client -->|HTTPS| Web
|
|
111
|
+
Web -->|REST| API
|
|
112
|
+
API -->|SQL| DB
|
|
113
|
+
API -->|cache| Cache
|
|
114
|
+
API -->|publish| Queue
|
|
115
|
+
Queue -->|consume| Worker
|
|
116
|
+
Worker -->|SQL| DB
|
|
117
|
+
|
|
118
|
+
%% Subgraphs
|
|
119
|
+
subgraph Data
|
|
120
|
+
DB
|
|
121
|
+
Cache
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
%% Styling
|
|
125
|
+
classDef db fill:#fef3c7,stroke:#b45309,color:#111;
|
|
126
|
+
classDef queue fill:#ede9fe,stroke:#6d28d9,color:#111;
|
|
127
|
+
class DB,Cache db;
|
|
128
|
+
class Queue queue;
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Notes
|
|
132
|
+
|
|
133
|
+
- {1–4 short bullets capturing assumptions, ambiguities, or items the source did not specify}
|
|
134
|
+
- {Any `<!-- TODO: verify ... -->` items should also be summarized here}
|
|
135
|
+
````
|
|
136
|
+
|
|
137
|
+
Key rules:
|
|
138
|
+
|
|
139
|
+
- The mermaid block must use a fenced code block tagged ` ```mermaid `. GitHub, GitLab, Obsidian, and the VS Code Markdown Preview Mermaid Support extension all render this.
|
|
140
|
+
- Open the diagram with `flowchart TD` or `flowchart LR` (not the legacy `graph` keyword).
|
|
141
|
+
- **Node IDs** are alphanumeric, no spaces, no hyphens. Use the display label inside brackets: `WebApp[Web app]`. Reuse the same ID consistently — Mermaid silently creates duplicate nodes if you typo an ID.
|
|
142
|
+
- **Edges**: `-->` solid, `-.->` dotted (use for async/optional), `==>` thick (use for hot path). Labels: `-->|label|`. Keep labels under ~20 characters.
|
|
143
|
+
- **Subgraphs**: `subgraph Name ... end`. Do not put `flowchart` direction inside a subgraph unless it differs from the parent (Mermaid supports per-subgraph direction with `direction TD`, but use sparingly).
|
|
144
|
+
- **No raw HTML** inside node labels except `<br/>` for line breaks. Quote labels with special characters: `Node["label: with colon"]`.
|
|
145
|
+
- **Comments** with `%%` are allowed and useful for sectioning the source. They render as nothing.
|
|
146
|
+
|
|
147
|
+
### Node shape cheatsheet
|
|
148
|
+
|
|
149
|
+
| Shape | Syntax | Use for |
|
|
150
|
+
|-------|--------|---------|
|
|
151
|
+
| Rectangle | `A[Label]` | Generic component, service, module |
|
|
152
|
+
| Rounded | `A(Label)` | App / process / API |
|
|
153
|
+
| Stadium | `A([Label])` | Worker, job, scheduled task |
|
|
154
|
+
| Subroutine | `A[[Label]]` | Library, internal package |
|
|
155
|
+
| Cylinder | `A[(Label)]` | Database, persistent store |
|
|
156
|
+
| Circle | `A((Label))` | External actor (Client, User) |
|
|
157
|
+
| Hexagon | `A{{Label}}` | Queue, broker, event bus |
|
|
158
|
+
| Rhombus | `A{Label}` | Decision / branch |
|
|
159
|
+
| Parallelogram | `A[/Label\]` | Load balancer, gateway, ingress |
|
|
160
|
+
| Trapezoid | `A[/Label/]` | Input / output |
|
|
161
|
+
|
|
162
|
+
## Phase 5 — Best-practice Checklist
|
|
163
|
+
|
|
164
|
+
Before calling `Write`, mentally verify:
|
|
165
|
+
|
|
166
|
+
- [ ] First line of the mermaid block is `flowchart TD` or `flowchart LR`
|
|
167
|
+
- [ ] Every node ID is alphanumeric and reused consistently
|
|
168
|
+
- [ ] No more than ~25 nodes; if exceeded, group into subgraphs or split into multiple diagrams
|
|
169
|
+
- [ ] Subgraphs are at most 2 levels deep
|
|
170
|
+
- [ ] At most 4 `classDef` styles; classes are actually applied with `class A,B name;`
|
|
171
|
+
- [ ] Edge labels are short and only present where the edge type is non-obvious
|
|
172
|
+
- [ ] No raw HTML other than `<br/>`; labels with `:` `#` `(` `)` are wrapped in `"..."`
|
|
173
|
+
- [ ] External actors / entry points are explicitly drawn (Client, User, External API)
|
|
174
|
+
- [ ] No claims that aren't in the source — ambiguous items are flagged in the **Notes** section, not invented in the diagram
|
|
175
|
+
- [ ] Output filename ends in `.flowchart.md` and lives next to the source unless the user gave an explicit path
|
|
176
|
+
|
|
177
|
+
## Phase 6 — Write & Confirm
|
|
178
|
+
|
|
179
|
+
1. `Write` the file to the output path.
|
|
180
|
+
2. Print a short summary to the user:
|
|
181
|
+
- Output path
|
|
182
|
+
- Node count, edge count, subgraph count
|
|
183
|
+
- Preview suggestion: open in any Markdown viewer that renders Mermaid (GitHub, GitLab, Obsidian, VS Code with **Markdown Preview Mermaid Support**), or render to SVG via `npx @mermaid-js/mermaid-cli -i <output>.flowchart.md -o diagram.svg`.
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## CRITICAL Rules
|
|
188
|
+
|
|
189
|
+
1. **Never** modify the source file — only read it.
|
|
190
|
+
2. Use `Read` for markdown/YAML/config source. Use Serena MCP only if you need to cross-check a code symbol referenced from the architecture doc.
|
|
191
|
+
3. Use `Write` (not `Edit`) to create the output — it's a new file.
|
|
192
|
+
4. Do not invent components, services, or relationships not present in the source. If a relationship is implied but not explicit, mark it with a `%% TODO: verify` comment in the mermaid block and call it out in the **Notes** section.
|
|
193
|
+
5. If the source describes more than ~25 components, ask the user whether to (a) collapse via subgraphs, (b) emit multiple diagrams in one file, or (c) limit to a single tier — do not silently truncate.
|
|
194
|
+
6. Maximum of 3 sub-processes if you delegate extraction. Always terminate.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: now
|
|
3
|
+
description: Plan and delegate a task to subagents (max 3 concurrent)
|
|
4
|
+
category: executing
|
|
5
|
+
model: claude-sonnet-4-6
|
|
6
|
+
effort: high
|
|
7
|
+
argument-hint: <task description>
|
|
8
|
+
disable-model-invocation: false
|
|
9
|
+
user-invocable: true
|
|
10
|
+
---
|
|
11
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
12
|
+
|
|
13
|
+
$ARGUMENTS
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
**Instructions:**
|
|
18
|
+
|
|
19
|
+
1) **Context**: Summarize the input from the user, determine desired outcomes, and determine what parts of the codebase to assess.
|
|
20
|
+
2) **Recall Serena memories**: Before planning, check for relevant project knowledge:
|
|
21
|
+
- `mcp__serena__list_memories` → scan for memories related to the task area (use `topic` filter if applicable)
|
|
22
|
+
- `mcp__serena__read_memory` → read any relevant memories to inform your plan
|
|
23
|
+
- Factor recalled knowledge (architecture decisions, known gotchas, integration patterns) into your approach
|
|
24
|
+
3) **Research**: If the task involves technology choices, architectural decisions, or unfamiliar patterns, run the `/research` workflow (see `lib/skills/research/SKILL.md`) to gather internal and external context before planning.
|
|
25
|
+
4) Assess all relevant files (use serena mcp) and make a comprehensive plan to achieve desired outcomes.
|
|
26
|
+
5) Delegate each step of the plan to the proper sub-agent.
|
|
27
|
+
6) **Update memories after completion**: Once all steps are done:
|
|
28
|
+
- Update stale memories with `mcp__serena__edit_memory` if the task changed documented patterns
|
|
29
|
+
- Write new memories with `mcp__serena__write_memory` for non-obvious knowledge discovered during execution (use `/` in names for topic hierarchy, e.g. `api/auth/jwt-flow`)
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
**CRITICAL**
|
|
34
|
+
|
|
35
|
+
1) Absolute maximum of 3 sub-processes at a time
|
|
36
|
+
2) **ALWAYS** terminate processes when done** (dev servers, type checkers, long-running commands)
|
|
@@ -0,0 +1,315 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: port-feature
|
|
3
|
+
description: Assess a feature or set of functionality in an external project and produce a concrete porting plan for adapting it into the current project
|
|
4
|
+
category: planning
|
|
5
|
+
model: claude-opus-4-8
|
|
6
|
+
effort: high
|
|
7
|
+
argument-hint: <absolute-path-to-source-project> <functionality description>
|
|
8
|
+
disable-model-invocation: false
|
|
9
|
+
user-invocable: true
|
|
10
|
+
---
|
|
11
|
+
**Prereqs:** obey `.docs/guides/mcp-tools.md`; run /primer if not done this session.
|
|
12
|
+
|
|
13
|
+
# Port Feature
|
|
14
|
+
|
|
15
|
+
Assess a specific feature or area of functionality in an external (source) project and produce a concrete, step-by-step plan for porting it into the current project. The plan accounts for differences in architecture, tech stack, conventions, and dependencies between the two codebases.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
**Arguments**: $ARGUMENTS
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Phase 0: Parse Arguments & Validate
|
|
24
|
+
|
|
25
|
+
1. **Parse `$ARGUMENTS`**:
|
|
26
|
+
- The **first token that is an absolute path** (starts with `/`) is the `<source-path>`
|
|
27
|
+
- Everything after the path is the `<functionality>` description
|
|
28
|
+
- Example: `/home/user/other-app authentication with JWT` → source path = `/home/user/other-app`, functionality = `authentication with JWT`
|
|
29
|
+
|
|
30
|
+
2. **Validate**:
|
|
31
|
+
- If `<source-path>` is missing or not absolute: stop and ask the user for the absolute path to the source project
|
|
32
|
+
- If `<functionality>` is empty: stop and ask the user what functionality to port
|
|
33
|
+
- Confirm the source directory exists: use `mcp__serena__find_file` or Bash `ls <source-path>` to verify it is accessible
|
|
34
|
+
|
|
35
|
+
3. **Clarifying questions** (ask before proceeding if ambiguous):
|
|
36
|
+
- Should the port plan produce a task file in `wiki/work/tasks/`, a report in `.docs/port/`, or both?
|
|
37
|
+
- Is there a preferred output level of detail (high-level steps vs. file-by-file implementation plan)?
|
|
38
|
+
- Are there any known constraints (e.g., "must stay in TypeScript", "no new dependencies")?
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Phase 1: Explore the Source Project
|
|
43
|
+
|
|
44
|
+
**Note**: Serena is scoped to the current project. Use `Read` and `Bash` to explore the source project at `<source-path>`. Do NOT use Serena tools on the source project's files.
|
|
45
|
+
|
|
46
|
+
### 1a. Project Overview
|
|
47
|
+
|
|
48
|
+
- Read `<source-path>/README.md` (if present) for declared purpose, setup, and architecture
|
|
49
|
+
- Read `<source-path>/package.json` / `<source-path>/pyproject.toml` / `<source-path>/go.mod` / `<source-path>/Cargo.toml` (whichever is present) for declared dependencies, scripts, and tech stack
|
|
50
|
+
- Run `ls <source-path>` and `ls <source-path>/src` (or equivalent source root) to understand the top-level structure
|
|
51
|
+
- Check for `CLAUDE.md`, `ARCHITECTURE.md`, `docs/`, or similar for documented design decisions
|
|
52
|
+
|
|
53
|
+
### 1b. Locate the Target Functionality
|
|
54
|
+
|
|
55
|
+
Search for the specific functionality described in `<functionality>`:
|
|
56
|
+
|
|
57
|
+
1. **Identify candidate directories and files** — look for modules, routes, services, components, or packages whose names relate to the functionality
|
|
58
|
+
- Use Bash: `find <source-path> -type f -name "*.ts" | xargs grep -l "<keyword>" 2>/dev/null | head -20` (adapt extension to the detected language)
|
|
59
|
+
- Navigate into the most relevant directories with `ls`
|
|
60
|
+
2. **Read key implementation files** — read the entry points, main logic files, interfaces/types, and any configuration for the target feature
|
|
61
|
+
3. **Trace data flow** — identify:
|
|
62
|
+
- Entry points (API routes, CLI commands, event handlers, exported functions)
|
|
63
|
+
- Core logic (services, business rules, transformations)
|
|
64
|
+
- Data models / schemas / types
|
|
65
|
+
- External dependencies (third-party libraries, APIs, databases, queues)
|
|
66
|
+
- Configuration (env vars, config files, feature flags)
|
|
67
|
+
4. **Read test files** — test files often give the clearest picture of intended behaviour; find and read relevant tests
|
|
68
|
+
|
|
69
|
+
### 1c. Build a Source Feature Inventory
|
|
70
|
+
|
|
71
|
+
Produce an internal summary documenting:
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
SOURCE FEATURE: <feature name>
|
|
75
|
+
Language / Runtime: <language + version if visible>
|
|
76
|
+
Frameworks / Libraries used by this feature:
|
|
77
|
+
- <lib>: <what role it plays>
|
|
78
|
+
Entry points:
|
|
79
|
+
- <file:line> — <description>
|
|
80
|
+
Core files:
|
|
81
|
+
- <file> — <responsibility>
|
|
82
|
+
Data models / types:
|
|
83
|
+
- <name> — <shape and purpose>
|
|
84
|
+
External dependencies (infra/services):
|
|
85
|
+
- <database / queue / 3rd-party API>
|
|
86
|
+
Configuration:
|
|
87
|
+
- <env var / config key> — <purpose>
|
|
88
|
+
Test coverage:
|
|
89
|
+
- <test file> — <what it covers>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Phase 2: Explore the Current (Target) Project
|
|
95
|
+
|
|
96
|
+
Use Serena for all current-project exploration. Do NOT use Bash `ls`/`cat`/`find`/`grep` on the current project's code files.
|
|
97
|
+
|
|
98
|
+
### 2a. Recall Context
|
|
99
|
+
|
|
100
|
+
- `mcp__serena__list_memories` → scan for memories related to the feature area and any architectural decisions
|
|
101
|
+
- `mcp__serena__read_memory` on relevant memories
|
|
102
|
+
- Read `wiki/work/decisions/` index (if present) for accepted architectural decisions that constrain the port
|
|
103
|
+
|
|
104
|
+
### 2b. Architecture & Tech Stack
|
|
105
|
+
|
|
106
|
+
- `mcp__serena__list_dir(".", recursive=false)` — top-level shape
|
|
107
|
+
- `mcp__serena__list_dir("<src-root>", recursive=false)` — source structure
|
|
108
|
+
- Read `package.json` / equivalent for declared dependencies and scripts
|
|
109
|
+
- `mcp__serena__get_symbols_overview` on main source directories — identify modules, services, key interfaces
|
|
110
|
+
|
|
111
|
+
### 2c. Find Analogous Functionality
|
|
112
|
+
|
|
113
|
+
Search for anything in the current project that overlaps with or is adjacent to the feature being ported:
|
|
114
|
+
|
|
115
|
+
- `mcp__serena__find_symbol` with name patterns from the source feature inventory
|
|
116
|
+
- `mcp__serena__search_for_pattern` for key terms, library names, or data model names from the source
|
|
117
|
+
- Check `wiki/work/tasks/`, `wiki/work/requirements/`, and `wiki/work/roadmaps/` for any planned or in-progress work in this area
|
|
118
|
+
|
|
119
|
+
### 2d. Build a Target Project Profile
|
|
120
|
+
|
|
121
|
+
Produce an internal summary:
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
TARGET PROJECT PROFILE
|
|
125
|
+
Language / Runtime: <language + version>
|
|
126
|
+
Primary frameworks:
|
|
127
|
+
- <framework>: <role>
|
|
128
|
+
Relevant existing modules:
|
|
129
|
+
- <module/file> — <what it does>
|
|
130
|
+
Existing analogous functionality:
|
|
131
|
+
- <description of overlap or adjacent features>
|
|
132
|
+
Conventions observed:
|
|
133
|
+
- File organisation: <pattern>
|
|
134
|
+
- Naming: <pattern>
|
|
135
|
+
- Error handling: <pattern>
|
|
136
|
+
- Testing: <pattern>
|
|
137
|
+
- State management / data access: <pattern>
|
|
138
|
+
Existing dependencies relevant to the port:
|
|
139
|
+
- <dep>: <why relevant>
|
|
140
|
+
Missing dependencies (source uses, target does not have):
|
|
141
|
+
- <dep>: <what source uses it for>
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Phase 3: Gap Analysis & Adaptation Strategy
|
|
147
|
+
|
|
148
|
+
With both inventories in hand, perform a structured comparison.
|
|
149
|
+
|
|
150
|
+
### 3a. Technology Mapping
|
|
151
|
+
|
|
152
|
+
For each component of the source feature, determine the target equivalent:
|
|
153
|
+
|
|
154
|
+
| Source Component | Source Technology | Target Equivalent | Notes |
|
|
155
|
+
|------------------|-------------------|-------------------|-------|
|
|
156
|
+
| HTTP routing | express Router | fastify routes | pattern change needed |
|
|
157
|
+
| ORM | Sequelize | Prisma | schema migration required |
|
|
158
|
+
| Auth tokens | jsonwebtoken | jose | API differs |
|
|
159
|
+
| … | | | |
|
|
160
|
+
|
|
161
|
+
### 3b. Complexity Classification
|
|
162
|
+
|
|
163
|
+
Classify each source file or module by porting effort:
|
|
164
|
+
|
|
165
|
+
| File / Module | Effort | Reason |
|
|
166
|
+
|---------------|:------:|--------|
|
|
167
|
+
| `<file>` | **Direct** | Same language, same library, minimal changes |
|
|
168
|
+
| `<file>` | **Adapt** | Same language, different library — logic preserved, API calls change |
|
|
169
|
+
| `<file>` | **Rewrite** | Different patterns, framework mismatch, or significant architectural delta |
|
|
170
|
+
| `<file>` | **Skip** | Already exists in target / out of scope |
|
|
171
|
+
|
|
172
|
+
**Effort levels**: **Direct** (copy + light edits) · **Adapt** (rework API calls, preserve logic) · **Rewrite** (logic must be re-expressed from scratch in target conventions)
|
|
173
|
+
|
|
174
|
+
### 3c. Dependency Assessment
|
|
175
|
+
|
|
176
|
+
For each dependency the source feature uses that the target project lacks:
|
|
177
|
+
|
|
178
|
+
| Missing Dependency | Source Role | Target Option | Decision |
|
|
179
|
+
|--------------------|-------------|---------------|----------|
|
|
180
|
+
| `<lib>` | <what it does> | `<target equivalent or "add <lib>">` | Add / Replace / Avoid |
|
|
181
|
+
|
|
182
|
+
Prefer using existing target project dependencies before recommending new ones.
|
|
183
|
+
|
|
184
|
+
### 3d. Integration Points
|
|
185
|
+
|
|
186
|
+
Identify where the ported feature will need to connect with existing target code:
|
|
187
|
+
|
|
188
|
+
- **Entry points**: Where does the feature get wired in (router, DI container, main module, CLI command, etc.)?
|
|
189
|
+
- **Data layer**: Does the feature need new tables/collections/indexes, or can it reuse existing ones?
|
|
190
|
+
- **Auth / security**: Does the feature touch auth — and how does the target project handle auth today?
|
|
191
|
+
- **Config / env**: What new env vars or config keys are needed?
|
|
192
|
+
- **Tests**: What test infrastructure does the target project use (jest, pytest, go test, etc.) and how should tests be structured?
|
|
193
|
+
|
|
194
|
+
### 3e. Risks & Constraints
|
|
195
|
+
|
|
196
|
+
List risks that could complicate the port:
|
|
197
|
+
|
|
198
|
+
| Risk | Likelihood | Impact | Mitigation |
|
|
199
|
+
|------|:----------:|:------:|------------|
|
|
200
|
+
| <risk> | Low/Med/High | Low/Med/High | <mitigation> |
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Phase 4: Produce the Port Plan
|
|
205
|
+
|
|
206
|
+
### 4a. Write the Port Plan File
|
|
207
|
+
|
|
208
|
+
Write a structured port plan to `.docs/port/<kebab-feature-name>.md`:
|
|
209
|
+
|
|
210
|
+
```markdown
|
|
211
|
+
---
|
|
212
|
+
source-project: <source-path>
|
|
213
|
+
feature: <feature name>
|
|
214
|
+
assessed: <YYYY-MM-DD>
|
|
215
|
+
effort: <Low / Medium / High / Very High>
|
|
216
|
+
status: draft
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
# Port Plan: <Feature Name>
|
|
220
|
+
|
|
221
|
+
> **Source**: `<source-path>`
|
|
222
|
+
> **Feature**: <functionality description>
|
|
223
|
+
> **Overall effort**: <Low / Medium / High / Very High>
|
|
224
|
+
> **Summary**: <One sentence on what this port involves.>
|
|
225
|
+
|
|
226
|
+
## Source Feature Summary
|
|
227
|
+
|
|
228
|
+
<Condensed version of the Source Feature Inventory from Phase 1c>
|
|
229
|
+
|
|
230
|
+
## Target Project Context
|
|
231
|
+
|
|
232
|
+
<Condensed version of the Target Project Profile from Phase 2d>
|
|
233
|
+
|
|
234
|
+
## Technology Mapping
|
|
235
|
+
|
|
236
|
+
<Table from 3a>
|
|
237
|
+
|
|
238
|
+
## Complexity Breakdown
|
|
239
|
+
|
|
240
|
+
<Table from 3b>
|
|
241
|
+
|
|
242
|
+
## Dependency Changes
|
|
243
|
+
|
|
244
|
+
<Table from 3c>
|
|
245
|
+
|
|
246
|
+
## Integration Points
|
|
247
|
+
|
|
248
|
+
<Bullet list from 3d>
|
|
249
|
+
|
|
250
|
+
## Risks
|
|
251
|
+
|
|
252
|
+
<Table from 3e>
|
|
253
|
+
|
|
254
|
+
## Porting Steps
|
|
255
|
+
|
|
256
|
+
Ordered, dependency-respecting steps. Each step is concrete and actionable.
|
|
257
|
+
|
|
258
|
+
### Step 1: <title>
|
|
259
|
+
|
|
260
|
+
**Effort**: <Direct / Adapt / Rewrite>
|
|
261
|
+
**Files affected**:
|
|
262
|
+
- `<target file path>` — <create / modify / delete>
|
|
263
|
+
|
|
264
|
+
**What to do**:
|
|
265
|
+
<Specific instructions: what to copy, what to change, how to adapt the API, what conventions to follow>
|
|
266
|
+
|
|
267
|
+
**Definition of done**: <How to know this step is complete>
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
### Step 2: <title>
|
|
272
|
+
|
|
273
|
+
… (repeat for each step)
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## Suggested Next Actions
|
|
278
|
+
|
|
279
|
+
- To create a task from this plan: `/task-add "Port <feature name> from <source-path>" --roadmap <if applicable>`
|
|
280
|
+
- To explore the source further: use Read on `<most important source file>`
|
|
281
|
+
- If a dependency decision is needed: <frame the specific decision>
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
### 4b. Optionally Create a Task File
|
|
285
|
+
|
|
286
|
+
If the user requested a task file (or if the plan is actionable enough to execute), suggest:
|
|
287
|
+
|
|
288
|
+
```
|
|
289
|
+
/task-add "Port <feature name> from <source-project-name>"
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
And note what context from the port plan should be included in the task.
|
|
293
|
+
|
|
294
|
+
---
|
|
295
|
+
|
|
296
|
+
## Phase 5: Report to User
|
|
297
|
+
|
|
298
|
+
After writing the plan file:
|
|
299
|
+
|
|
300
|
+
1. State the path written: `.docs/port/<kebab-feature-name>.md`
|
|
301
|
+
2. Give a one-line overall effort verdict (e.g., "Medium effort — 4 files to adapt, 1 rewrite, no new dependencies required")
|
|
302
|
+
3. List the top 3 porting steps in brief
|
|
303
|
+
4. Call out the single biggest risk or blocker
|
|
304
|
+
5. Suggest the most useful next action (task creation, further exploration, or a specific decision to make)
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## CRITICAL Rules
|
|
309
|
+
|
|
310
|
+
1. **Serena for the current project only** — all current-project code exploration must use Serena tools; no Bash `ls`/`cat`/`find`/`grep` on current project code files
|
|
311
|
+
2. **Read + Bash for the source project** — Serena cannot reach outside the current project; use `Read` and `Bash` to explore `<source-path>`
|
|
312
|
+
3. **No speculation** — every claim in the port plan must be grounded in what you actually read from either codebase
|
|
313
|
+
4. **Prefer existing dependencies** — do not recommend adding a new dependency if the target project already has something that covers the need
|
|
314
|
+
5. **Respect target conventions** — the port plan must describe porting the feature in the style and patterns of the target project, not a direct copy of the source
|
|
315
|
+
6. **Brave Search only if needed** — use Brave Search (up to 50 req/sec, parallel OK) only to compare alternative dependency options; do not use it to look up library docs (use Context7 instead)
|