archgen-mcp 0.0.6 → 0.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 +14 -9
- package/assets/briefs/investigate.md +16 -17
- package/assets/briefs/review.md +41 -29
- package/assets/briefs/survey.md +17 -20
- package/assets/briefs/verifier.md +52 -40
- package/assets/harness-mcp.json +285 -55
- package/assets/platform-capabilities.json +387 -71
- package/assets/references/artifact-templates.md +68 -219
- package/assets/references/interview.md +83 -199
- package/assets/references/mcp-and-skills.md +35 -125
- package/assets/references/orchestration.md +96 -209
- package/assets/references/platforms.md +41 -108
- package/assets/skill-registry.json +10 -1
- package/assets/templates/adr.md +3 -3
- package/assets/templates/architecture.yaml +31 -28
- package/assets/templates/edge-matrix.md +8 -8
- package/assets/templates/mermaid.md +3 -10
- package/assets/templates/prd.md +15 -15
- package/assets/templates/tasks.yaml +25 -18
- package/bin/archgen-mcp.mjs +6 -4
- package/package.json +2 -2
- package/src/cli.mjs +1 -2
- package/src/context.mjs +55 -45
- package/src/core/brief-context.mjs +106 -0
- package/src/core/brief-scope.mjs +218 -0
- package/src/core/briefs.mjs +121 -0
- package/src/core/codegraph-manager.mjs +124 -48
- package/src/core/compat.mjs +13 -3
- package/src/core/doc-navigator.mjs +127 -24
- package/src/core/errors.mjs +1 -1
- package/src/core/fs-safety.mjs +98 -10
- package/src/core/graph.mjs +8 -3
- package/src/core/harness-wiring.mjs +194 -37
- package/src/core/jsonc-config.mjs +706 -0
- package/src/core/mcp-server-manager.mjs +2 -3
- package/src/core/plan-coverage.mjs +43 -6
- package/src/core/plan-grapher.mjs +13 -5
- package/src/core/platform-caps.mjs +9 -2
- package/src/core/resume-snapshot.mjs +16 -4
- package/src/core/scope.mjs +39 -5
- package/src/core/skill-manager.mjs +181 -13
- package/src/core/skill-roots.mjs +92 -0
- package/src/core/status-mutator.mjs +34 -3
- package/src/core/tokens.mjs +78 -0
- package/src/core/validator.mjs +16 -3
- package/src/core/verifier.mjs +3 -9
- package/src/core/worker-contract.mjs +161 -20
- package/src/core/yaml.mjs +31 -6
- package/src/server.mjs +0 -3
- package/src/tools/_register.mjs +5 -4
- package/src/tools/codegraph.mjs +0 -2
- package/src/tools/docs.mjs +6 -6
- package/src/tools/help.mjs +18 -35
- package/src/tools/plan.mjs +58 -7
- package/src/tools/setup.mjs +7 -3
- package/src/tools/skills.mjs +67 -5
- package/src/tools/tasks.mjs +82 -23
- package/src/core/ui-channel.mjs +0 -171
- package/src/tools/ui.mjs +0 -67
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version":
|
|
2
|
+
"version": 3,
|
|
3
3
|
"_readme": [
|
|
4
4
|
"Capability-skill registry — the SINGLE source of truth for which external",
|
|
5
5
|
"skill a task needs, where it comes from, and how it is installed.",
|
|
@@ -35,6 +35,7 @@
|
|
|
35
35
|
"skills": [
|
|
36
36
|
{
|
|
37
37
|
"id": "ui-baseline",
|
|
38
|
+
"domain": "Design",
|
|
38
39
|
"slug": "baseline-ui",
|
|
39
40
|
"family": "ui-skills",
|
|
40
41
|
"repo": "ibelick/ui-skills",
|
|
@@ -44,6 +45,7 @@
|
|
|
44
45
|
},
|
|
45
46
|
{
|
|
46
47
|
"id": "ui-motion",
|
|
48
|
+
"domain": "Motion",
|
|
47
49
|
"slug": "fixing-motion-performance",
|
|
48
50
|
"family": "ui-skills",
|
|
49
51
|
"repo": "ibelick/ui-skills",
|
|
@@ -53,6 +55,7 @@
|
|
|
53
55
|
},
|
|
54
56
|
{
|
|
55
57
|
"id": "ui-interaction",
|
|
58
|
+
"domain": "Accessibility",
|
|
56
59
|
"slug": "fixing-accessibility",
|
|
57
60
|
"family": "ui-skills",
|
|
58
61
|
"repo": "ibelick/ui-skills",
|
|
@@ -62,6 +65,7 @@
|
|
|
62
65
|
},
|
|
63
66
|
{
|
|
64
67
|
"id": "ui-metadata",
|
|
68
|
+
"domain": "Metadata",
|
|
65
69
|
"slug": "fixing-metadata",
|
|
66
70
|
"family": "ui-skills",
|
|
67
71
|
"repo": "ibelick/ui-skills",
|
|
@@ -71,6 +75,7 @@
|
|
|
71
75
|
},
|
|
72
76
|
{
|
|
73
77
|
"id": "ui-improve",
|
|
78
|
+
"domain": "UI polish",
|
|
74
79
|
"slug": "improve-ui",
|
|
75
80
|
"family": "ui-skills",
|
|
76
81
|
"repo": "ibelick/ui-skills",
|
|
@@ -80,6 +85,7 @@
|
|
|
80
85
|
},
|
|
81
86
|
{
|
|
82
87
|
"id": "ui-canvas",
|
|
88
|
+
"domain": "Component canvas",
|
|
83
89
|
"slug": "component-canvas",
|
|
84
90
|
"family": "ui-skills",
|
|
85
91
|
"repo": "ibelick/ui-skills",
|
|
@@ -89,6 +95,7 @@
|
|
|
89
95
|
},
|
|
90
96
|
{
|
|
91
97
|
"id": "design-system",
|
|
98
|
+
"domain": "Design system",
|
|
92
99
|
"slug": "create-design-md",
|
|
93
100
|
"family": "ui-skills",
|
|
94
101
|
"repo": "ibelick/ui-skills",
|
|
@@ -98,6 +105,7 @@
|
|
|
98
105
|
},
|
|
99
106
|
{
|
|
100
107
|
"id": "ui-create-canvas",
|
|
108
|
+
"domain": "Canvas scaffold",
|
|
101
109
|
"slug": "create-canvas",
|
|
102
110
|
"family": "ui-skills",
|
|
103
111
|
"repo": "ibelick/ui-skills",
|
|
@@ -109,6 +117,7 @@
|
|
|
109
117
|
"routing": {
|
|
110
118
|
"_readme": "The ui-skills-root entry routes a task to the right specialised skill. It is the fallback when a task touches UI but matches no specific skill above.",
|
|
111
119
|
"id": "ui-router",
|
|
120
|
+
"domain": "UI",
|
|
112
121
|
"slug": "ui-skills-root",
|
|
113
122
|
"family": "ui-skills",
|
|
114
123
|
"repo": "ibelick/ui-skills",
|
package/assets/templates/adr.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# NNNN. <decision title>
|
|
2
2
|
Date: YYYY-MM-DD · Status: accepted
|
|
3
3
|
## Context
|
|
4
|
-
<forces at play>
|
|
4
|
+
<forces and constraints at play>
|
|
5
5
|
## Decision
|
|
6
|
-
<
|
|
6
|
+
<chosen option and rationale>
|
|
7
7
|
## Consequences
|
|
8
|
-
<positive
|
|
8
|
+
<positive, negative, and neutral trade-offs>
|
|
@@ -1,58 +1,61 @@
|
|
|
1
|
+
# schema_version: 1
|
|
2
|
+
# generator: archgen
|
|
3
|
+
# generated_at: 2026-08-26T09:00:00.000Z
|
|
1
4
|
name: Acme Shop
|
|
2
|
-
slug: acme-shop
|
|
5
|
+
slug: acme-shop # maps to .archgen/acme-shop/
|
|
3
6
|
stack:
|
|
4
7
|
language: typescript
|
|
5
8
|
runtime: node20
|
|
6
9
|
framework: nextjs
|
|
7
10
|
database: postgres
|
|
8
|
-
structure:
|
|
11
|
+
structure: # planned folder tree defined BEFORE coding
|
|
9
12
|
- path: src/features/<feature>/
|
|
10
|
-
purpose: feature modules (api, internal, tests
|
|
13
|
+
purpose: feature modules (api, internal, colocated tests)
|
|
11
14
|
- path: src/shared/
|
|
12
|
-
purpose: cross-feature utilities
|
|
15
|
+
purpose: cross-feature utilities; MUST NOT import from features/
|
|
13
16
|
- path: src/config/
|
|
14
|
-
purpose: env parsing + constants
|
|
15
|
-
naming_conventions:
|
|
16
|
-
file_naming: kebab-case files
|
|
17
|
-
dir_layout: "<module>/{api,internal,tests}; shared
|
|
18
|
-
symbol_casing: PascalCase types, camelCase functions, SCREAMING_SNAKE env
|
|
19
|
-
test_placement: colocated <name>.test.ts
|
|
17
|
+
purpose: typed env parsing + constants
|
|
18
|
+
naming_conventions: # referenced by every task step and file_ownership entry
|
|
19
|
+
file_naming: kebab-case files; feature folder matches module name
|
|
20
|
+
dir_layout: "<module>/{api,internal,tests}; shared utilities in src/shared/ only"
|
|
21
|
+
symbol_casing: PascalCase types, camelCase functions, SCREAMING_SNAKE env vars
|
|
22
|
+
test_placement: colocated <name>.test.ts beside unit under test
|
|
20
23
|
modules:
|
|
21
24
|
- name: catalog
|
|
22
25
|
responsibility: product browsing + search
|
|
23
26
|
owns: ["src/features/catalog/**"]
|
|
24
|
-
depends_on_modules: []
|
|
25
|
-
key_interfaces:
|
|
27
|
+
depends_on_modules: [] # DAG; drives task depends_on edges
|
|
28
|
+
key_interfaces: # ONLY exports other modules may import
|
|
26
29
|
- CatalogApi (src/features/catalog/api/index.ts)
|
|
27
30
|
- name: checkout
|
|
28
|
-
responsibility: cart
|
|
31
|
+
responsibility: cart -> payment orchestration
|
|
29
32
|
owns: ["src/features/checkout/**"]
|
|
30
33
|
depends_on_modules: [catalog]
|
|
31
34
|
key_interfaces:
|
|
32
35
|
- CheckoutApi (src/features/checkout/api/index.ts)
|
|
33
|
-
data_contracts:
|
|
36
|
+
data_contracts:
|
|
34
37
|
orders:
|
|
35
|
-
storage: postgres table orders (
|
|
38
|
+
storage: postgres table orders (migrations/NNNN_orders.sql)
|
|
36
39
|
fields:
|
|
37
|
-
- {field: id,
|
|
38
|
-
- {field: session_id, type: uuid,
|
|
39
|
-
- {field: total_cents, type: integer,
|
|
40
|
-
- {field: status,
|
|
41
|
-
- {field: created_at, type: timestamptz, required: true, notes: db default now()}
|
|
42
|
-
api_contracts:
|
|
40
|
+
- { field: id, type: uuid, required: true, notes: pk }
|
|
41
|
+
- { field: session_id, type: uuid, required: true, notes: fk sessions }
|
|
42
|
+
- { field: total_cents, type: integer, required: true, notes: ">= 0" }
|
|
43
|
+
- { field: status, type: "enum(pending,paid,failed)", required: true }
|
|
44
|
+
- { field: created_at, type: timestamptz, required: true, notes: db default now() }
|
|
45
|
+
api_contracts:
|
|
43
46
|
payments:
|
|
44
47
|
- endpoint: /api/checkout/pay
|
|
45
48
|
method: POST
|
|
46
49
|
auth: session cookie; 401 when absent
|
|
47
|
-
request_payload: {order_id: uuid}
|
|
50
|
+
request_payload: { order_id: uuid }
|
|
48
51
|
success: "200 {payment_id: uuid, status: paid}"
|
|
49
|
-
error_shape: {code: string, message: string, retryable: boolean}
|
|
50
|
-
environment_matrix:
|
|
51
|
-
- {var: DATABASE_URL, dev: local docker postgres, ci: ephemeral service, prod: secret ref, required: true}
|
|
52
|
-
- {var: PAYMENT_API_KEY, dev: stub key, ci: stub key, prod: secret ref, required: true}
|
|
53
|
-
decisions:
|
|
52
|
+
error_shape: { code: string, message: string, retryable: boolean }
|
|
53
|
+
environment_matrix: # unparsed vars fail fast at startup in src/config/
|
|
54
|
+
- { var: DATABASE_URL, dev: local docker postgres, ci: ephemeral service, prod: secret ref, required: true }
|
|
55
|
+
- { var: PAYMENT_API_KEY, dev: stub key, ci: stub key, prod: secret ref, required: true }
|
|
56
|
+
decisions: # summary index; full records live in decisions/NNNN-title.md
|
|
54
57
|
- id: D1
|
|
55
58
|
title: Postgres over MongoDB
|
|
56
|
-
context:
|
|
59
|
+
context: ACID order transactions + relational reporting
|
|
57
60
|
decision: Postgres 16 with Prisma
|
|
58
61
|
consequences: schema migrations required per release
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
| Case | Input/state
|
|
2
|
-
| ---- | ------------------------------- |
|
|
3
|
-
| E1
|
|
4
|
-
| E2
|
|
5
|
-
| E3
|
|
6
|
-
| E4
|
|
7
|
-
| E5
|
|
8
|
-
| E6
|
|
1
|
+
| Case | Input/state | Expected behavior | Covered by |
|
|
2
|
+
| ---- | ------------------------------- | ------------------------------------- | ---------- |
|
|
3
|
+
| E1 | empty/null: cart with 0 items | 200, total 0, no gateway call | PAY-2#1 |
|
|
4
|
+
| E2 | boundary: qty = max allowed 999 | accepted; 1000 rejected with 422 | PAY-2#1 |
|
|
5
|
+
| E3 | concurrent: same order paid 2x | idempotency key -> single charge | PAY-2#1 |
|
|
6
|
+
| E4 | authz denied: expired session | 401 error_shape, no state mutation | PAY-2#2 |
|
|
7
|
+
| E5 | failure/retry: gateway 5xx x3 | exponential backoff then PaymentFailed| PAY-2#2 |
|
|
8
|
+
| E6 | i18n: locale de-DE, zero-dec ¥ | EUR comma decimal; JPY integer math | PAY-2#4 |
|
|
@@ -18,15 +18,9 @@ graph LR
|
|
|
18
18
|
|
|
19
19
|
## Per-module diagram (LARGE)
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
internal components plus its `depends_on_modules` edges (arrow points from
|
|
23
|
-
consumer to provider). Plus ONE integration diagram wiring all modules —
|
|
24
|
-
edges between modules only, no internals. HARD LIMIT: ≤15 nodes per diagram;
|
|
25
|
-
split into two diagrams rather than cramming. Internals stay ≤6 nodes per
|
|
26
|
-
module.
|
|
27
|
-
|
|
28
|
-
Catalog module (internal + inbound depends_on edge):
|
|
21
|
+
Rules: One flowchart per `modules:` entry in `architecture.yaml` showing internal components ($\le 6$ nodes) + inbound `depends_on_modules` edges (consumer $\rightarrow$ provider), plus ONE integration diagram wiring modules as atomic nodes. **Hard limit:** $\le 15$ nodes per diagram.
|
|
29
22
|
|
|
23
|
+
Catalog module (internals + inbound `depends_on` edge):
|
|
30
24
|
```mermaid
|
|
31
25
|
graph LR
|
|
32
26
|
subgraph catalog
|
|
@@ -36,8 +30,7 @@ graph LR
|
|
|
36
30
|
checkout -.->|depends_on CatalogApi| routes
|
|
37
31
|
```
|
|
38
32
|
|
|
39
|
-
Integration (
|
|
40
|
-
|
|
33
|
+
Integration (module-level DAG mirroring `depends_on_modules`):
|
|
41
34
|
```mermaid
|
|
42
35
|
graph LR
|
|
43
36
|
accounts --> catalog
|
package/assets/templates/prd.md
CHANGED
|
@@ -1,31 +1,31 @@
|
|
|
1
1
|
# PRD — <project name>
|
|
2
2
|
|
|
3
3
|
## Problem statement & goals
|
|
4
|
-
- <
|
|
5
|
-
- Goals: <3–5 outcome bullets
|
|
4
|
+
- <quantified user/system pain>
|
|
5
|
+
- Goals: <3–5 measurable outcome bullets>
|
|
6
6
|
|
|
7
7
|
## Non-goals
|
|
8
|
-
- <
|
|
8
|
+
- <explicit exclusions to prevent scope creep>
|
|
9
9
|
|
|
10
10
|
## Personas / stakeholders
|
|
11
|
-
- <persona>: <
|
|
11
|
+
- <persona>: <core job-to-be-done> -> <measurable success state>
|
|
12
12
|
|
|
13
|
-
## Functional requirements — <module-name>
|
|
14
|
-
- FR-<MODULE>-01: <single verifiable behavior
|
|
15
|
-
- FR-<MODULE>-02:
|
|
16
|
-
<!--
|
|
13
|
+
## Functional requirements — <module-name> (repeat per module)
|
|
14
|
+
- FR-<MODULE>-01: <single objectively verifiable behavior>
|
|
15
|
+
- FR-<MODULE>-02: <single objectively verifiable behavior>
|
|
16
|
+
<!-- FR IDs are immutable once cited in tasks.yaml -->
|
|
17
17
|
|
|
18
|
-
## Non-functional requirements (
|
|
18
|
+
## Non-functional requirements (concrete numbers mandatory; no adjectives)
|
|
19
19
|
- Perf: p95 API latency < 300 ms at 50 rps; LCP < 2.5 s
|
|
20
|
-
- Security: authz
|
|
21
|
-
- i18n:
|
|
22
|
-
- A11y: WCAG 2.
|
|
20
|
+
- Security: authz enforced on all routes; zero secrets in repo; OWASP Top 10 mitigated
|
|
21
|
+
- i18n: externalized copy; ICU pluralization; RTL-safe layout
|
|
22
|
+
- A11y: WCAG 2.2 AA compliance; full keyboard navigation; contrast >= 4.5:1
|
|
23
23
|
|
|
24
24
|
## Success metrics
|
|
25
|
-
- <metric>: <baseline>
|
|
25
|
+
- <metric>: <baseline> -> <target> within <evaluation window>
|
|
26
26
|
|
|
27
27
|
## Risks & mitigations
|
|
28
|
-
- <risk>
|
|
28
|
+
- <risk> -> <mitigation>, owned by <task ID or ADR ref>
|
|
29
29
|
|
|
30
30
|
## Open questions
|
|
31
|
-
- <question> — owner <name/role>, blocks <task
|
|
31
|
+
- <question> — owner: <name/role>, blocks: <task ID | none>
|
|
@@ -1,40 +1,47 @@
|
|
|
1
|
-
#
|
|
1
|
+
# schema_version: 1
|
|
2
|
+
# generator: archgen
|
|
3
|
+
# generated_at: 2026-08-26T09:00:00.000Z
|
|
4
|
+
# comment lines are preserved by archgen_tasks{set_status}
|
|
2
5
|
tasks:
|
|
3
|
-
#
|
|
6
|
+
# Wave 1 — Foundation
|
|
4
7
|
- id: C
|
|
5
|
-
title: Scaffold project skeleton + config
|
|
8
|
+
title: Scaffold project skeleton + typed config loader
|
|
6
9
|
depends_on: []
|
|
7
|
-
file_ownership: ["src/config/**", "package.json"]
|
|
10
|
+
file_ownership: ["src/config/**", "package.json"] # full repo-root-relative paths ONLY
|
|
8
11
|
acceptance:
|
|
9
12
|
- "npm run build exits 0"
|
|
10
|
-
- "config loads from env
|
|
13
|
+
- "config loads from env and fails fast on missing required vars"
|
|
14
|
+
|
|
15
|
+
# Wave 2 — Core domain
|
|
11
16
|
- id: B
|
|
12
17
|
title: Catalog API endpoints
|
|
13
18
|
depends_on: [C]
|
|
14
19
|
file_ownership: ["src/features/catalog/**"]
|
|
15
20
|
acceptance:
|
|
16
|
-
- "GET /products returns seeded list"
|
|
21
|
+
- "GET /products returns seeded catalog list with 200 status"
|
|
22
|
+
|
|
23
|
+
# Wave 3 — Feature integration
|
|
17
24
|
- id: A
|
|
18
25
|
title: Checkout flow wired to catalog
|
|
19
26
|
depends_on: [B]
|
|
20
27
|
parallel_group: wave-final
|
|
21
|
-
file_ownership: ["src/features/checkout/**"]
|
|
22
|
-
artifacts: ["docs/checkout-flow.md"]
|
|
28
|
+
file_ownership: ["src/features/checkout/**", "docs/checkout-flow.md"]
|
|
29
|
+
artifacts: ["docs/checkout-flow.md"] # must be a subset of file_ownership
|
|
23
30
|
acceptance:
|
|
24
|
-
- "e2e test completes purchase
|
|
31
|
+
- "e2e test completes purchase flow against stub payment gateway"
|
|
25
32
|
|
|
26
|
-
# LARGE-
|
|
27
|
-
# minimal ones above, never replaces them):
|
|
33
|
+
# LARGE-scope task example (traces edge-matrix rows E1-En and PRD FR-* IDs)
|
|
28
34
|
- id: PAY-2
|
|
29
|
-
title: Order payment capture with retry
|
|
35
|
+
title: Order payment capture with exponential backoff retry
|
|
30
36
|
depends_on: [A]
|
|
31
37
|
parallel_group: wave-payments
|
|
32
38
|
file_ownership:
|
|
33
|
-
- src/features/checkout/internal/capture.ts
|
|
34
|
-
- src/features/checkout/internal/capture.test.ts
|
|
39
|
+
- src/features/checkout/internal/capture.ts # per naming_conventions.dir_layout
|
|
40
|
+
- src/features/checkout/internal/capture.test.ts # per naming_conventions.test_placement
|
|
41
|
+
- docs/payment-retry.md
|
|
35
42
|
artifacts: ["docs/payment-retry.md"]
|
|
36
43
|
acceptance:
|
|
37
|
-
- "capture() sends idempotency key;
|
|
38
|
-
- "gateway 5xx retries 3x exponential backoff, then raises PaymentFailed (E5)"
|
|
39
|
-
- "
|
|
40
|
-
- "amounts
|
|
44
|
+
- "capture() sends idempotency key; duplicate submission charges once (E3)"
|
|
45
|
+
- "gateway 5xx retries 3x with exponential backoff, then raises PaymentFailed (E5)"
|
|
46
|
+
- "declined card returns 402 matching ../architecture.yaml api_contracts.payments.error_shape (FR-PAYMENTS-02)"
|
|
47
|
+
- "currency amounts format via session locale using integer cents math (E6)"
|
package/bin/archgen-mcp.mjs
CHANGED
|
@@ -16,11 +16,13 @@ import { createServer } from '../src/server.mjs';
|
|
|
16
16
|
import { runCli } from '../src/cli.mjs';
|
|
17
17
|
|
|
18
18
|
const argv = process.argv.slice(2);
|
|
19
|
-
const CLI_COMMANDS = new Set(['exec', 'bootstrap', 'doctor', 'uninstall-mcp', 'help']);
|
|
20
19
|
const first = argv[0];
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
|
|
20
|
+
// The stdio server is the DEFAULT, and only for no argument at all or the
|
|
21
|
+
// explicit word 'serve'. Anything else is the command-line facade — a known
|
|
22
|
+
// command, a flag, or an unknown word, which must say "unknown command"
|
|
23
|
+
// rather than silently start a server and block on stdin (which is what it
|
|
24
|
+
// used to do, making the mistake look like a hang).
|
|
25
|
+
const wantsCli = !(first === undefined || first === 'serve');
|
|
24
26
|
|
|
25
27
|
if (wantsCli) {
|
|
26
28
|
const code = await runCli(argv);
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "archgen-mcp",
|
|
3
|
-
"version": "0.0
|
|
4
|
-
"description": "MCP server for archgen \u2014 the single runtime that owns architecture-plan validation, wave execution, artifact navigation, CodeGraph bootstrap
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "MCP server for archgen \u2014 the single runtime that owns architecture-plan validation, wave execution, artifact navigation, CodeGraph bootstrap and harness MCP wiring for coding agents.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"bin": {
|
package/src/cli.mjs
CHANGED
|
@@ -1,10 +1,9 @@
|
|
|
1
1
|
// cli.mjs — the command-line facade over the MCP server.
|
|
2
2
|
//
|
|
3
|
-
// WHY A CLI FACADE:
|
|
3
|
+
// WHY A CLI FACADE: two consumers need the same capability, and they must
|
|
4
4
|
// never drift apart:
|
|
5
5
|
// - agents -> MCP over stdio
|
|
6
6
|
// - the CLI installer -> `archgen-mcp bootstrap`
|
|
7
|
-
// - the VS Code extension -> `archgen-mcp exec archgen_tasks '{"action":"next",…}'`
|
|
8
7
|
//
|
|
9
8
|
// `exec` runs the SAME tool handlers the MCP server exposes — there is no
|
|
10
9
|
// second implementation of any capability, only a second way to reach it.
|
package/src/context.mjs
CHANGED
|
@@ -11,7 +11,8 @@ import { homedir } from 'node:os';
|
|
|
11
11
|
import { dirname, isAbsolute, join, resolve } from 'node:path';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
13
13
|
import { invalidInput } from './core/errors.mjs';
|
|
14
|
-
import { containPath } from './core/fs-safety.mjs';
|
|
14
|
+
import { assertWithinRoot, containPath } from './core/fs-safety.mjs';
|
|
15
|
+
import { GLOBAL_SKILL_ROOTS, PROJECT_SKILL_ROOTS, skillSearchPaths } from './core/skill-roots.mjs';
|
|
15
16
|
|
|
16
17
|
const HERE = dirname(fileURLToPath(import.meta.url));
|
|
17
18
|
|
|
@@ -39,34 +40,14 @@ export function serverVersion() {
|
|
|
39
40
|
/**
|
|
40
41
|
* Skill install locations, project-local first.
|
|
41
42
|
*
|
|
42
|
-
* Mirrors references/platforms.md § "Skill install paths".
|
|
43
|
-
*
|
|
44
|
-
*
|
|
43
|
+
* Mirrors references/platforms.md § "Skill install paths". The canonical list
|
|
44
|
+
* lives in core/skill-roots.mjs so the archgen skill and the CAPABILITY
|
|
45
|
+
* skills are resolved against the same roots — one list, one answer.
|
|
45
46
|
*/
|
|
46
|
-
export const PROJECT_SKILL_DIRS =
|
|
47
|
-
'.agents/skills/archgen',
|
|
48
|
-
'.claude/skills/archgen',
|
|
49
|
-
'.github/skills/archgen',
|
|
50
|
-
'.gemini/skills/archgen',
|
|
51
|
-
'.cursor/skills/archgen',
|
|
52
|
-
'.opencode/skills/archgen',
|
|
53
|
-
'.codex/skills/archgen',
|
|
54
|
-
'.kiro/skills/archgen',
|
|
55
|
-
'.trae/skills/archgen',
|
|
56
|
-
'.windsurf/skills/archgen',
|
|
57
|
-
];
|
|
47
|
+
export const PROJECT_SKILL_DIRS = PROJECT_SKILL_ROOTS.map((r) => join(r, 'archgen'));
|
|
58
48
|
|
|
59
49
|
/** User-global skill locations (same shape, under $HOME). */
|
|
60
|
-
export const GLOBAL_SKILL_DIRS =
|
|
61
|
-
'.agents/skills/archgen',
|
|
62
|
-
'.claude/skills/archgen',
|
|
63
|
-
'.config/opencode/skills/archgen',
|
|
64
|
-
'.gemini/skills/archgen',
|
|
65
|
-
'.copilot/skills/archgen',
|
|
66
|
-
'.codex/skills/archgen',
|
|
67
|
-
'.kiro/skills/archgen',
|
|
68
|
-
'.trae/skills/archgen',
|
|
69
|
-
];
|
|
50
|
+
export const GLOBAL_SKILL_DIRS = GLOBAL_SKILL_ROOTS.map((r) => join(r, 'archgen'));
|
|
70
51
|
|
|
71
52
|
/**
|
|
72
53
|
* Locate the installed archgen skill.
|
|
@@ -89,23 +70,12 @@ export function resolveSkill(projectRoot, home = homedir(), env = process.env) {
|
|
|
89
70
|
if (existsSync(join(abs, 'SKILL.md'))) return { path: abs, version: readSkillVersion(abs), scope: 'override' };
|
|
90
71
|
}
|
|
91
72
|
|
|
92
|
-
//
|
|
93
|
-
//
|
|
94
|
-
|
|
95
|
-
for (
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
if (existsSync(join(abs, 'SKILL.md'))) return { path: abs, version: readSkillVersion(abs), scope: 'project' };
|
|
99
|
-
}
|
|
100
|
-
const parent = dirname(dir);
|
|
101
|
-
if (parent === dir) break;
|
|
102
|
-
dir = parent;
|
|
103
|
-
}
|
|
104
|
-
|
|
105
|
-
if (home) {
|
|
106
|
-
for (const rel of GLOBAL_SKILL_DIRS) {
|
|
107
|
-
const abs = join(home, rel);
|
|
108
|
-
if (existsSync(join(abs, 'SKILL.md'))) return { path: abs, version: readSkillVersion(abs), scope: 'global' };
|
|
73
|
+
// The project chain (walking UP) and the user-global roots come from the
|
|
74
|
+
// ONE skill-root list, so the archgen skill and the capability skills are
|
|
75
|
+
// resolved against the same places.
|
|
76
|
+
for (const candidate of skillSearchPaths(projectRoot, 'archgen', { home })) {
|
|
77
|
+
if (existsSync(join(candidate.dir, 'SKILL.md'))) {
|
|
78
|
+
return { path: candidate.dir, version: readSkillVersion(candidate.dir), scope: candidate.scope };
|
|
109
79
|
}
|
|
110
80
|
}
|
|
111
81
|
|
|
@@ -148,19 +118,59 @@ export function loadAsset(name) {
|
|
|
148
118
|
|
|
149
119
|
/**
|
|
150
120
|
* The per-call context: project root + resolved skill + versions.
|
|
121
|
+
*
|
|
122
|
+
* THE ANCHOR. `anchorRoot` is the boundary the server works inside. It is
|
|
123
|
+
* set when the server starts — the directory the server was launched in, or
|
|
124
|
+
* the project the CLI named — and it does NOT change per call.
|
|
125
|
+
*
|
|
126
|
+
* `projectRoot` selects a directory INSIDE the anchor. It is a selector, not
|
|
127
|
+
* a boundary: naming a different root cannot move the edge of what the
|
|
128
|
+
* server may read or write. Before this, every containment check was
|
|
129
|
+
* relative to a root the MODEL chose, so the guard defended nothing — a
|
|
130
|
+
* model that named `/etc` simply moved the boundary to `/etc`.
|
|
151
131
|
*/
|
|
152
132
|
export class Context {
|
|
153
133
|
/**
|
|
154
|
-
* @param {{projectRoot?: string, home?: string, env?: Record<string, string|undefined>}} [opts]
|
|
134
|
+
* @param {{projectRoot?: string, anchorRoot?: string, home?: string, env?: Record<string, string|undefined>}} [opts]
|
|
155
135
|
*/
|
|
156
136
|
constructor(opts = {}) {
|
|
157
137
|
this.env = opts.env ?? process.env;
|
|
158
138
|
this.home = opts.home ?? homedir();
|
|
159
|
-
|
|
139
|
+
// The anchor is the server's DECLARED root: what the server was started
|
|
140
|
+
// with. The cwd is only the fallback for a server started without one.
|
|
141
|
+
this.anchorRoot = resolve(
|
|
142
|
+
opts.anchorRoot ?? opts.projectRoot ?? this.env.ARCHGEN_PROJECT_ROOT ?? process.cwd(),
|
|
143
|
+
);
|
|
144
|
+
this.projectRoot = resolve(opts.projectRoot ?? this.anchorRoot);
|
|
160
145
|
this.skill = resolveSkill(this.projectRoot, this.home, this.env);
|
|
161
146
|
this.serverVersion = serverVersion();
|
|
162
147
|
}
|
|
163
148
|
|
|
149
|
+
/**
|
|
150
|
+
* A context for a directory inside the anchor.
|
|
151
|
+
*
|
|
152
|
+
* The candidate is resolved and proved to be inside the anchor; a path
|
|
153
|
+
* outside it is refused with PERMISSION_DENIED. The returned context
|
|
154
|
+
* keeps the SAME anchor, so containment checks made with it cannot be
|
|
155
|
+
* widened either.
|
|
156
|
+
*
|
|
157
|
+
* @param {string} candidate
|
|
158
|
+
* @returns {Context}
|
|
159
|
+
*/
|
|
160
|
+
withProjectRoot(candidate) {
|
|
161
|
+
if (typeof candidate !== 'string' || candidate.trim() === '') {
|
|
162
|
+
throw invalidInput('projectRoot must be a non-empty string', { projectRoot: candidate });
|
|
163
|
+
}
|
|
164
|
+
const abs = resolve(this.anchorRoot, candidate);
|
|
165
|
+
assertWithinRoot(this.anchorRoot, abs);
|
|
166
|
+
return new Context({
|
|
167
|
+
projectRoot: abs,
|
|
168
|
+
anchorRoot: this.anchorRoot,
|
|
169
|
+
env: this.env,
|
|
170
|
+
home: this.home,
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
|
|
164
174
|
/**
|
|
165
175
|
* Resolve a caller-supplied path and prove it stays inside the project root.
|
|
166
176
|
* Relative paths are resolved against the project root.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
// brief-context.mjs — what a dispatch brief carries besides its task.
|
|
2
|
+
//
|
|
3
|
+
// WHY A SEPARATE MODULE: the brief TEMPLATE holds the protocol (what to
|
|
4
|
+
// examine, what to return). The CONTEXT holds the facts (which files exist,
|
|
5
|
+
// which sections they have, what the tools already said). They change for
|
|
6
|
+
// different reasons and at different times, so they are assembled separately
|
|
7
|
+
// and composed once.
|
|
8
|
+
//
|
|
9
|
+
// THE RENDERING RULE: everything here is computed BY THE TOOL, not requested
|
|
10
|
+
// by the orchestrator. The old review brief said "attach the mermaid graph
|
|
11
|
+
// and the docs-validate result", which cost two tool calls per gate round —
|
|
12
|
+
// and the graph call failed on every plan, so the reviewer ran without it.
|
|
13
|
+
// Rendering it once, into the brief, removes the extra calls AND the
|
|
14
|
+
// dependency.
|
|
15
|
+
import { existsSync } from 'node:fs';
|
|
16
|
+
import { join } from 'node:path';
|
|
17
|
+
import { docIndex } from './doc-navigator.mjs';
|
|
18
|
+
import { planGraph } from './plan-grapher.mjs';
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* The archgen calls each brief kind is ALLOWED to make.
|
|
22
|
+
*
|
|
23
|
+
* The list is exhaustive on purpose: a sub-agent that runs the archgen tool
|
|
24
|
+
* suite is re-deriving facts the brief already carries, and can drift from
|
|
25
|
+
* the protocol the orchestrator is following.
|
|
26
|
+
*/
|
|
27
|
+
const ALLOWED_CALLS = {
|
|
28
|
+
verifier: ["archgen_plan{action:'verify'}", "archgen_docs{action:'validate'}"],
|
|
29
|
+
review: [],
|
|
30
|
+
survey: [],
|
|
31
|
+
investigate: ["archgen_plan{action:'impact'}"],
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
/** The archgen calls each brief kind may make — the single source of truth. */
|
|
35
|
+
export { ALLOWED_CALLS };
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Build the context block for one brief.
|
|
39
|
+
*
|
|
40
|
+
* @param {string} kind the brief kind
|
|
41
|
+
* @param {{slug: string, slugDir: string, plansDir: string, tasksYaml: string}} scope
|
|
42
|
+
* @param {{projectRoot: string}} ctx
|
|
43
|
+
* @returns {{
|
|
44
|
+
* scope: object,
|
|
45
|
+
* allowedCalls: string[],
|
|
46
|
+
* evidence: {files: Array<{path: string, sections: Array<{slug: string, title: string}>}>, fileCount: number}|null,
|
|
47
|
+
* graph: string|null,
|
|
48
|
+
* docsValidation: {valid: boolean, broken: unknown[], warnings: unknown[]}|null,
|
|
49
|
+
* }}
|
|
50
|
+
*/
|
|
51
|
+
export function buildBriefContext(kind, scope, ctx) {
|
|
52
|
+
const out = {
|
|
53
|
+
scope,
|
|
54
|
+
allowedCalls: ALLOWED_CALLS[kind] ?? [],
|
|
55
|
+
evidence: null,
|
|
56
|
+
graph: null,
|
|
57
|
+
docsValidation: null,
|
|
58
|
+
};
|
|
59
|
+
|
|
60
|
+
// The evidence map: every markdown artifact under the slug, with its
|
|
61
|
+
// section anchors. A MAP, not a copy — the agent reads the sections it
|
|
62
|
+
// needs and never re-reads the whole plan.
|
|
63
|
+
try {
|
|
64
|
+
if (existsSync(scope.slugDir)) {
|
|
65
|
+
const digest = docIndex(scope.slugDir, { mode: 'digest', projectRoot: ctx.projectRoot });
|
|
66
|
+
const files = (digest.data.files ?? []).map((f) => ({
|
|
67
|
+
path: f.path,
|
|
68
|
+
sections: (f.sections ?? []).map((s) => ({ slug: s.slug, title: s.title })),
|
|
69
|
+
}));
|
|
70
|
+
out.evidence = { files, fileCount: files.length };
|
|
71
|
+
}
|
|
72
|
+
} catch {
|
|
73
|
+
out.evidence = null; // a missing artifact space is not a brief failure
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
// The dependency graph — rendered once, so the reviewer reads it instead of
|
|
77
|
+
// spending a tool call to fetch it.
|
|
78
|
+
try {
|
|
79
|
+
if (existsSync(scope.tasksYaml)) {
|
|
80
|
+
const g = planGraph(scope.tasksYaml, {
|
|
81
|
+
mermaid: true,
|
|
82
|
+
status: true,
|
|
83
|
+
projectRoot: ctx.projectRoot,
|
|
84
|
+
});
|
|
85
|
+
out.graph = typeof g.data === 'string' ? g.data : null;
|
|
86
|
+
}
|
|
87
|
+
} catch {
|
|
88
|
+
out.graph = null; // a plan that cannot be graphed is reported by the verifier
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// The reference-integrity result — the deterministic floor's second half.
|
|
92
|
+
try {
|
|
93
|
+
if (existsSync(scope.slugDir)) {
|
|
94
|
+
const v = docIndex(scope.slugDir, { mode: 'validate', projectRoot: ctx.projectRoot });
|
|
95
|
+
out.docsValidation = {
|
|
96
|
+
valid: v.data.valid === true,
|
|
97
|
+
broken: v.data.broken ?? [],
|
|
98
|
+
warnings: v.data.warnings ?? [],
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
} catch {
|
|
102
|
+
out.docsValidation = null;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
return out;
|
|
106
|
+
}
|