@cliangdev/conductor 0.44.0 → 0.46.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/assets/claude/agents/conductor-coder.md +1 -1
- package/assets/claude/commands/conductor/implement.md +3 -2
- package/assets/claude/commands/conductor/prd.md +162 -32
- package/assets/cli-manifest.json +2 -2
- package/dist/commands/lint.d.ts +3 -1
- package/dist/commands/lint.d.ts.map +1 -1
- package/dist/commands/lint.js +174 -7
- package/dist/commands/lint.js.map +1 -1
- package/dist/daemon/watcher.d.ts.map +1 -1
- package/dist/daemon/watcher.js +2 -1
- package/dist/daemon/watcher.js.map +1 -1
- package/dist/lib/content-type.d.ts +7 -0
- package/dist/lib/content-type.d.ts.map +1 -0
- package/dist/lib/content-type.js +9 -0
- package/dist/lib/content-type.js.map +1 -0
- package/dist/mcp/index.js +8 -8
- package/dist/mcp/index.js.map +1 -1
- package/dist/mcp/tools/comments.d.ts +7 -0
- package/dist/mcp/tools/comments.d.ts.map +1 -1
- package/dist/mcp/tools/comments.js.map +1 -1
- package/dist/mcp/tools/documents.d.ts.map +1 -1
- package/dist/mcp/tools/documents.js +7 -5
- package/dist/mcp/tools/documents.js.map +1 -1
- package/dist/mcp/tools/posts.d.ts +2 -2
- package/dist/mcp/tools/posts.d.ts.map +1 -1
- package/dist/mcp/tools/posts.js +5 -4
- package/dist/mcp/tools/posts.js.map +1 -1
- package/package.json +2 -1
|
@@ -18,7 +18,7 @@ You will be given:
|
|
|
18
18
|
- **Task description** — what to build
|
|
19
19
|
- **Acceptance criteria** — tagged `[auto]` (must have automated test) or `[manual]` (document verification steps)
|
|
20
20
|
- **Epic context** — background and goals
|
|
21
|
-
- **PRD path** — for deeper context if needed
|
|
21
|
+
- **PRD path (.html or .md)** — for deeper context if needed. In an HTML PRD, a feature is an `<article data-feature>` and each acceptance criterion an `<li data-ac="AC-...">`
|
|
22
22
|
|
|
23
23
|
Read all of it before writing any code.
|
|
24
24
|
|
|
@@ -58,7 +58,8 @@ Load the PRD if not already in context.
|
|
|
58
58
|
|
|
59
59
|
2. **If the PRD is not in context**:
|
|
60
60
|
- Call `get_work_item` with the resolved `issueId` — note the returned `absolutePath` (the issue directory on disk); use it for any subsequent `Read` / `Write` / `Edit` calls in this skill (the `Read`, `Write`, and `Edit` tools require absolute paths)
|
|
61
|
-
- Read the local
|
|
61
|
+
- Read the local PRD at `{absolutePath}prd.html` if it exists, otherwise `{absolutePath}prd.md`. Remember which one exists as `prdPath` (the full absolute path) and pass it to coders
|
|
62
|
+
- Acceptance-criteria IDs: for `prd.html`, take them from the `data-ac` attributes (`<li data-ac="AC-P0-1.1">`; each sits inside the `<article data-feature>` it belongs to); for `prd.md`, use the checkbox regex ``^- \[[ x]\] `AC-P[01]-\d+\.\d+` ``
|
|
62
63
|
|
|
63
64
|
---
|
|
64
65
|
|
|
@@ -295,7 +296,7 @@ For each batch, spawn `conductor-coder` subagents in parallel using the Agent to
|
|
|
295
296
|
## Context
|
|
296
297
|
- Epic: {epic.id} - {epic.title}
|
|
297
298
|
- Issue: {issue_id} - {issue_title}
|
|
298
|
-
- Full PRD:
|
|
299
|
+
- Full PRD: {prdPath} (prd.html or prd.md, whichever exists; read if more context needed)
|
|
299
300
|
|
|
300
301
|
## Workflow
|
|
301
302
|
1. Write tests for each [auto] criterion FIRST
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: conductor:prd
|
|
3
|
-
description: Create PRDs for Conductor projects through discovery, research, and guided writing
|
|
4
|
-
|
|
3
|
+
description: Create PRDs for Conductor projects through discovery, research, and guided writing. Writes an HTML PRD by default (markdown on request), or imports an existing HTML page / claude.ai artifact as a PRD.
|
|
4
|
+
argument-hint: "[import <claude.ai artifact URL or .html path>]"
|
|
5
|
+
allowed-tools: mcp__conductor__*, AskUserQuestion, Task, Read, Write, Glob, Grep, WebSearch, Bash, Artifact
|
|
5
6
|
---
|
|
6
7
|
|
|
7
8
|
# /conductor:prd
|
|
@@ -11,6 +12,8 @@ You are a PRD creation assistant for the Conductor workflow.
|
|
|
11
12
|
## Trigger
|
|
12
13
|
This skill runs when the user invokes `/conductor:prd`.
|
|
13
14
|
|
|
15
|
+
If the argument starts with `import` (`/conductor:prd import <claude.ai artifact URL or .html path>`), skip Phases 1-3 and follow **Import Route** at the end of this file. Otherwise continue with the phases below.
|
|
16
|
+
|
|
14
17
|
## Prerequisites Check
|
|
15
18
|
Read `~/.conductor/config.json`. If missing or lacking `localPath`, `projectId`, or `apiKey`, respond:
|
|
16
19
|
> Run `conductor login` and `conductor init` first to set up Conductor in this project.
|
|
@@ -98,22 +101,129 @@ Use AskUserQuestion:
|
|
|
98
101
|
|
|
99
102
|
### 3b. Write Full PRD
|
|
100
103
|
|
|
101
|
-
Write the PRD
|
|
104
|
+
**Format.** Write the PRD as **HTML** (`prd.html`) unless the user asked for markdown, in which case use the markdown fallback (`prd.md`). Both formats carry the same schema-v2 content: seven required sections in a fixed order, stable feature and acceptance-criterion IDs, and a contract block on every P0 feature. Target 1-2 pages — concise enough to review in under 5 minutes.
|
|
102
105
|
|
|
103
|
-
**
|
|
104
|
-
-
|
|
105
|
-
-
|
|
106
|
-
- If `Glossary` or `Reference Patterns` truly has nothing to add, write `_None._` rather than omitting the section
|
|
106
|
+
**Content guidelines (both formats):**
|
|
107
|
+
- The seven required sections appear in this exact order: Problem, Glossary, Goals, Non-Goals, Users, Reference Patterns, Features. Optional sections (Out of Scope, Open Questions, Supporting Documents) come after.
|
|
108
|
+
- If Glossary or Reference Patterns truly has nothing to add, say so explicitly ("None") rather than omitting the section or leaving it empty
|
|
107
109
|
- Features get stable IDs that restart within each priority: `P0-1`, `P0-2`, ... and `P1-1`, `P1-2`, ...
|
|
108
|
-
- Every P0 feature
|
|
109
|
-
-
|
|
110
|
-
-
|
|
111
|
-
-
|
|
112
|
-
-
|
|
113
|
-
|
|
114
|
-
|
|
110
|
+
- Every P0 feature carries What, Not, Inputs, Outputs, Invariants and Acceptance Criteria. For a P0 feature with no exclusions, write "None" under Not. P1 features may omit Not, Inputs, Outputs and Invariants
|
|
111
|
+
- Every acceptance criterion gets a stable ID matching `^AC-P[01]-\d+\.\d+$` (e.g. `AC-P0-1.1`), unique within the PRD, with the feature's ID inside it (`AC-P0-3.2` belongs to `P0-3`)
|
|
112
|
+
- Acceptance criteria are verifiable: Given/When/Then or measurable thresholds, not "works correctly"
|
|
113
|
+
- Keep technical implementation details out of the PRD (they go in `architecture.md`) and edge cases out (they go in implementation specs)
|
|
114
|
+
- Leave Supporting Documents empty until documents exist
|
|
115
|
+
|
|
116
|
+
**HTML contract (`prd.html`):**
|
|
117
|
+
- `<head>` has `<title>` and three metas: `conductor:doc-type` = `prd`, `conductor:schema-version` = `2`, `conductor:issue-id` = the Work Item ID
|
|
118
|
+
- Each section is `<section id="{name}" data-prd-section="{name}">` with an `<h2>`; names, in order: `problem`, `glossary`, `goals`, `non-goals`, `users`, `reference-patterns`, `features`, then optional `out-of-scope`, `open-questions`, `supporting-documents`
|
|
119
|
+
- An empty Glossary or Reference Patterns contains exactly `<p><em>None.</em></p>`
|
|
120
|
+
- Each feature is `<article id="P0-1" data-feature="P0-1">` with an `<h3>`, then a `<dl>` whose `<dt>`s are What, Not, Inputs, Outputs, Invariants, then `<ul data-acs>` of `<li data-ac="AC-P0-1.1">…</li>`
|
|
121
|
+
- Self-contained: inline `<style>` and `<script>`, Google Fonts, and pinned CDN scripts only from cdnjs.cloudflare.com, cdn.jsdelivr.net, unpkg.com, cdn.tailwindcss.com or code.jquery.com. No `fetch`/XHR/WebSocket (the viewer's CSP blocks them), no `window.claude`, no `window.open` (popups are blocked). Links are plain `<a href>`: `#hash` scrolls inside the page and `http(s)` links open in a new tab through the Conductor app. The page needs no script; add one only when it earns its place
|
|
122
|
+
- Escape `<`, `>` and `&` in text. Keep ids stable: reviewers' comments reference the nearest section id. Comment quotes are rendered text (tags dropped, whitespace collapsed), so write section text that reads naturally
|
|
123
|
+
|
|
124
|
+
### HTML PRD Template
|
|
125
|
+
|
|
126
|
+
Keep this structure and token block; adapt the visual style to the product's design language from Phase 2a when the PRD is UI-heavy.
|
|
127
|
+
|
|
128
|
+
```html
|
|
129
|
+
<!doctype html>
|
|
130
|
+
<html lang="en">
|
|
131
|
+
<head>
|
|
132
|
+
<meta charset="utf-8">
|
|
133
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
134
|
+
<meta name="conductor:doc-type" content="prd">
|
|
135
|
+
<meta name="conductor:schema-version" content="2">
|
|
136
|
+
<meta name="conductor:issue-id" content="{issueId}">
|
|
137
|
+
<title>{title}</title>
|
|
138
|
+
<style>
|
|
139
|
+
:root{--bg:#fff;--fg:#1a1d21;--muted:#5b6470;--line:#e3e6ea;--card:#f6f7f9;--accent:#2f5bea}
|
|
140
|
+
@media (prefers-color-scheme:dark){:root{--bg:#14161a;--fg:#e8eaed;--muted:#9aa3ae;--line:#2a2e35;--card:#1c1f25;--accent:#7b9bff}}
|
|
141
|
+
*{box-sizing:border-box}
|
|
142
|
+
body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.6 system-ui,-apple-system,"Segoe UI",sans-serif}
|
|
143
|
+
nav{position:sticky;top:0;z-index:1;display:flex;gap:16px;overflow-x:auto;white-space:nowrap;padding:10px 16px;background:var(--bg);border-bottom:1px solid var(--line);font-size:14px}
|
|
144
|
+
nav a{color:var(--muted);text-decoration:none}nav a:hover{color:var(--accent)}
|
|
145
|
+
main{max-width:760px;margin:0 auto;padding:0 16px 64px}
|
|
146
|
+
h1{font-size:2rem;line-height:1.2;margin:32px 0 4px}
|
|
147
|
+
h2{font-size:1.25rem;margin:0 0 12px}
|
|
148
|
+
h3{font-size:1.05rem;margin:0 0 8px}
|
|
149
|
+
.sub{color:var(--muted);margin:0 0 8px}
|
|
150
|
+
section{padding:24px 0;border-top:1px solid var(--line);scroll-margin-top:56px}
|
|
151
|
+
article{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:16px;margin:12px 0}
|
|
152
|
+
dl{display:grid;grid-template-columns:max-content 1fr;gap:6px 16px;margin:0 0 12px}
|
|
153
|
+
dt{color:var(--muted);font-weight:600}dd{margin:0}
|
|
154
|
+
ul[data-acs]{margin:0;padding-left:20px}
|
|
155
|
+
@media (max-width:560px){dl{grid-template-columns:1fr}dd{margin-bottom:6px}}
|
|
156
|
+
</style>
|
|
157
|
+
</head>
|
|
158
|
+
<body>
|
|
159
|
+
<nav>
|
|
160
|
+
<a href="#problem">Problem</a><a href="#glossary">Glossary</a><a href="#goals">Goals</a><a href="#non-goals">Non-Goals</a><a href="#users">Users</a><a href="#reference-patterns">Reference Patterns</a><a href="#features">Features</a>
|
|
161
|
+
</nav>
|
|
162
|
+
<main>
|
|
163
|
+
<h1>{title}</h1>
|
|
164
|
+
<p class="sub">PRD · {issueId}</p>
|
|
165
|
+
|
|
166
|
+
<section id="problem" data-prd-section="problem"><h2>Problem</h2>
|
|
167
|
+
<p>{2-3 sentences: what hurts, for whom, and how we know}</p></section>
|
|
168
|
+
|
|
169
|
+
<section id="glossary" data-prd-section="glossary"><h2>Glossary</h2>
|
|
170
|
+
<dl><dt>{Term}</dt><dd>{project-specific definition}</dd></dl>
|
|
171
|
+
<!-- nothing to define: replace the <dl> with <p><em>None.</em></p> --></section>
|
|
172
|
+
|
|
173
|
+
<section id="goals" data-prd-section="goals"><h2>Goals</h2>
|
|
174
|
+
<ul><li>{Measurable outcome}</li></ul></section>
|
|
175
|
+
|
|
176
|
+
<section id="non-goals" data-prd-section="non-goals"><h2>Non-Goals</h2>
|
|
177
|
+
<ul><li>{Explicit exclusion}</li></ul></section>
|
|
178
|
+
|
|
179
|
+
<section id="users" data-prd-section="users"><h2>Users</h2>
|
|
180
|
+
<p>{Target users and their primary needs, 2-4 sentences}</p></section>
|
|
181
|
+
|
|
182
|
+
<section id="reference-patterns" data-prd-section="reference-patterns"><h2>Reference Patterns</h2>
|
|
183
|
+
<ul><li><strong>{Aspect}</strong>: {existing file or convention to mirror}</li></ul>
|
|
184
|
+
<!-- none apply: replace the <ul> with <p><em>None.</em></p> --></section>
|
|
185
|
+
|
|
186
|
+
<section id="features" data-prd-section="features"><h2>Features</h2>
|
|
187
|
+
<h3 class="sub">P0: Must Have</h3>
|
|
188
|
+
<article id="P0-1" data-feature="P0-1"><h3>P0-1: {Feature Name}</h3>
|
|
189
|
+
<dl>
|
|
190
|
+
<dt>What</dt><dd>{precise scope in 1 sentence}</dd>
|
|
191
|
+
<dt>Not</dt><dd>{explicit exclusions, or <em>None.</em>}</dd>
|
|
192
|
+
<dt>Inputs</dt><dd>{what triggers this / what data flows in}</dd>
|
|
193
|
+
<dt>Outputs</dt><dd>{artifact, response or state change}</dd>
|
|
194
|
+
<dt>Invariants</dt><dd>{properties that must always hold}</dd>
|
|
195
|
+
</dl>
|
|
196
|
+
<ul data-acs>
|
|
197
|
+
<li data-ac="AC-P0-1.1">{Given/When/Then or measurable threshold}</li>
|
|
198
|
+
<li data-ac="AC-P0-1.2">{testable criterion}</li>
|
|
199
|
+
</ul></article>
|
|
200
|
+
|
|
201
|
+
<h3 class="sub">P1: Should Have</h3>
|
|
202
|
+
<article id="P1-1" data-feature="P1-1"><h3>P1-1: {Feature Name}</h3>
|
|
203
|
+
<dl><dt>What</dt><dd>{precise scope in 1 sentence}</dd></dl>
|
|
204
|
+
<ul data-acs><li data-ac="AC-P1-1.1">{testable criterion}</li></ul></article>
|
|
205
|
+
</section>
|
|
206
|
+
|
|
207
|
+
<section id="out-of-scope" data-prd-section="out-of-scope"><h2>Out of Scope</h2>
|
|
208
|
+
<ul><li>{Item explicitly deferred}</li></ul></section>
|
|
209
|
+
|
|
210
|
+
<section id="open-questions" data-prd-section="open-questions"><h2>Open Questions</h2>
|
|
211
|
+
<ul><li>{unresolved item}</li></ul></section>
|
|
212
|
+
|
|
213
|
+
<section id="supporting-documents" data-prd-section="supporting-documents"><h2>Supporting Documents</h2>
|
|
214
|
+
<p>Links are added here as supporting documents are created.</p></section>
|
|
215
|
+
</main>
|
|
216
|
+
</body>
|
|
217
|
+
</html>
|
|
218
|
+
```
|
|
115
219
|
|
|
116
|
-
###
|
|
220
|
+
### Markdown fallback (`prd.md`, only when the user asks for markdown)
|
|
221
|
+
|
|
222
|
+
Same content rules. Markdown specifics:
|
|
223
|
+
- Frontmatter MUST include `schemaVersion: 2`
|
|
224
|
+
- If `Glossary` or `Reference Patterns` has nothing to add, write `_None._`
|
|
225
|
+
- Every P0 feature includes all six bold-prefix lines: `**What**`, `**Not**`, `**Inputs**`, `**Outputs**`, `**Invariants**`, `**Acceptance Criteria**` (`**Not**: _None._` when nothing is excluded)
|
|
226
|
+
- Each AC line is `- [ ] \`AC-P0-1.1\` …`
|
|
117
227
|
|
|
118
228
|
```markdown
|
|
119
229
|
---
|
|
@@ -130,7 +240,6 @@ schemaVersion: 2
|
|
|
130
240
|
|
|
131
241
|
## Glossary
|
|
132
242
|
- **{Term}**: {project-specific definition, distinguishing it from generic usage}
|
|
133
|
-
- **{Term}**: {definition}
|
|
134
243
|
|
|
135
244
|
(If truly nothing to define, write `_None._`)
|
|
136
245
|
|
|
@@ -140,14 +249,12 @@ schemaVersion: 2
|
|
|
140
249
|
|
|
141
250
|
## Non-Goals
|
|
142
251
|
- {Explicit exclusion 1}
|
|
143
|
-
- {Explicit exclusion 2}
|
|
144
252
|
|
|
145
253
|
## Users
|
|
146
254
|
{Target users and their primary needs — 2-4 sentences}
|
|
147
255
|
|
|
148
256
|
## Reference Patterns
|
|
149
257
|
- **{Aspect}**: {existing file or convention to mirror, e.g. "follow `src/commands/doctor.ts` — same Commander registration, `--json` output mode, exit codes"}
|
|
150
|
-
- **{Aspect}**: {pattern}
|
|
151
258
|
|
|
152
259
|
(If truly no reference patterns apply, write `_None._`)
|
|
153
260
|
|
|
@@ -165,15 +272,6 @@ schemaVersion: 2
|
|
|
165
272
|
- [ ] `AC-P0-1.1` {Given/When/Then or measurable threshold}
|
|
166
273
|
- [ ] `AC-P0-1.2` {testable criterion}
|
|
167
274
|
|
|
168
|
-
#### P0-2: {Feature Name}
|
|
169
|
-
- **What**: {precise scope in 1 sentence}
|
|
170
|
-
- **Not**: _None._
|
|
171
|
-
- **Inputs**: {inputs}
|
|
172
|
-
- **Outputs**: {outputs}
|
|
173
|
-
- **Invariants**: {invariants}
|
|
174
|
-
- **Acceptance Criteria**:
|
|
175
|
-
- [ ] `AC-P0-2.1` {testable criterion}
|
|
176
|
-
|
|
177
275
|
### P1: Should Have
|
|
178
276
|
|
|
179
277
|
#### P1-1: {Feature Name}
|
|
@@ -193,8 +291,19 @@ schemaVersion: 2
|
|
|
193
291
|
|
|
194
292
|
### 3c. Self-Check
|
|
195
293
|
|
|
196
|
-
Before showing the PRD to the user in Step 3d, run through
|
|
294
|
+
Before showing the PRD to the user in Step 3d, run through the checklist for the format you wrote and fix any item that fails. Do not skip — this is the gate that keeps schema v2 PRDs deterministic for downstream agents. `conductor lint {issueId}` runs the same checks after saving.
|
|
197
295
|
|
|
296
|
+
**If HTML (`prd.html`):**
|
|
297
|
+
- [ ] `<head>` has `<title>` and the metas `conductor:doc-type` = `prd`, `conductor:schema-version` = `2`, `conductor:issue-id`
|
|
298
|
+
- [ ] Seven `<section id data-prd-section>` elements in order: `problem`, `glossary`, `goals`, `non-goals`, `users`, `reference-patterns`, `features` — each with an `<h2>`
|
|
299
|
+
- [ ] `glossary` and `reference-patterns` hold real entries or exactly `<p><em>None.</em></p>`
|
|
300
|
+
- [ ] Every feature is `<article id="P0-n" data-feature="P0-n">` (numbering restarts per priority) with an `<h3>`
|
|
301
|
+
- [ ] Every P0 feature's `<dl>` has `<dt>`s What, Not, Inputs, Outputs, Invariants, and a `<ul data-acs>` follows (P1 features may omit all but What)
|
|
302
|
+
- [ ] Every criterion is `<li data-ac="AC-P0-1.1">` with an id matching `^AC-P[01]-\d+\.\d+$`
|
|
303
|
+
- [ ] Every AC id is unique, and its feature part matches the enclosing article (`AC-P0-3.2` only inside `P0-3`)
|
|
304
|
+
- [ ] No `fetch`/XHR/`window.claude`/`window.open`; scripts, if any, are inline or pinned from cdnjs.cloudflare.com, cdn.jsdelivr.net, unpkg.com, cdn.tailwindcss.com or code.jquery.com
|
|
305
|
+
|
|
306
|
+
**If markdown (`prd.md`):**
|
|
198
307
|
- [ ] Frontmatter contains `schemaVersion: 2`
|
|
199
308
|
- [ ] All seven H2 sections are present in this exact order: `Problem`, `Glossary`, `Goals`, `Non-Goals`, `Users`, `Reference Patterns`, `Features`
|
|
200
309
|
- [ ] `Glossary` and `Reference Patterns` are non-empty (either real entries, or the literal text `_None._`)
|
|
@@ -225,10 +334,10 @@ Call MCP tools in this exact sequence:
|
|
|
225
334
|
2. **Create the Work Item**: `create_work_item({workflow, type: "PRD", title, description})`
|
|
226
335
|
- Receive: `{issueId, displayId, localPath}`
|
|
227
336
|
|
|
228
|
-
3. **Scaffold document**: `scaffold_document({issueId, filename: "prd.
|
|
229
|
-
- Receive: `{localPath: ".conductor/issues/{issueId}/prd.
|
|
337
|
+
3. **Scaffold document**: `scaffold_document({issueId, filename: "prd.html"})` (or `"prd.md"` when writing markdown). The filename extension sets the content type.
|
|
338
|
+
- Receive: `{localPath: ".conductor/issues/{issueId}/prd.html", absolutePath: "/abs/path/to/.conductor/issues/{issueId}/prd.html"}`
|
|
230
339
|
|
|
231
|
-
4. **Write content**: Use the Write tool with the `absolutePath` from step 3 (Write requires absolute paths) to write the full PRD with
|
|
340
|
+
4. **Write content**: Use the Write tool with the `absolutePath` from step 3 (Write requires absolute paths) to write the full PRD, with the `issueId` from step 2 in the `conductor:issue-id` meta tag (HTML) or the YAML frontmatter (markdown).
|
|
232
341
|
|
|
233
342
|
5. **Move to IN_REVIEW** (definition-driven): call `get_available_transitions({issueId})` to confirm `IN_REVIEW` is an available next status from the Workflow's initial status, then `transition_work_item({issueId, toStatus: "IN_REVIEW"})`, signalling the PRD is ready for team review.
|
|
234
343
|
|
|
@@ -246,7 +355,9 @@ Options:
|
|
|
246
355
|
For each accepted supporting document:
|
|
247
356
|
1. `scaffold_document({issueId, filename: "{doc-filename}"})`
|
|
248
357
|
2. Write the template content (see templates below) using the Write tool with the returned `absolutePath`
|
|
249
|
-
3. **Update the PRD's Supporting Documents section**: Read the saved
|
|
358
|
+
3. **Update the PRD's Supporting Documents section**: Read the saved PRD file (use the `absolutePath` returned from step 3 of the main save sequence), replace the placeholder line with a relative link entry, and write it back.
|
|
359
|
+
- HTML PRD: add `<li><a href="./architecture.md">Architecture</a> (architecture.md)</li>` inside a `<ul>` in the `supporting-documents` section. Conductor's HTML viewer does not yet turn `./` links into document tabs, so keep the filename visible as text next to the link.
|
|
360
|
+
- Markdown PRD: `- [Architecture](./architecture.md)` (the markdown viewer opens it as a tab).
|
|
250
361
|
|
|
251
362
|
**UI/UX quality bar for wireframes and HTML mocks:**
|
|
252
363
|
Before writing any UI artifact, recall the design language catalogued in Phase 2a. All wireframes and mocks must:
|
|
@@ -418,3 +529,22 @@ Write a valid standalone HTML file with inline CSS — no external dependencies.
|
|
|
418
529
|
- Use the same component vocabulary: if the product uses card containers with subtle shadows, use that here; if it uses bordered panels, do that instead
|
|
419
530
|
- Show at least two states: the default/happy-path view AND one of empty/loading/error
|
|
420
531
|
- Add a small `<!-- note: ... -->` comment for any placeholder or approximation that differs from the real product
|
|
532
|
+
|
|
533
|
+
## Import Route
|
|
534
|
+
|
|
535
|
+
`/conductor:prd import <claude.ai artifact URL or .html path>` brings an existing HTML page into Conductor as a PRD. It uses your Claude Code access to the artifact, because Conductor's backend cannot fetch private claude.ai pages.
|
|
536
|
+
|
|
537
|
+
1. **Read the page.**
|
|
538
|
+
- A `.html` / `.htm` path: Read the file.
|
|
539
|
+
- A claude.ai artifact URL (`claude.ai/artifact/{id}` or `claude.ai/code/artifact/{id}`): call the Artifact tool with `action: "read"` and the URL.
|
|
540
|
+
- If the result is only a summary because the artifact belongs to someone else, **stop**. Say the full page is only readable for artifacts the user owns, and ask them to download the `.html` file and re-run `/conductor:prd import <path>`.
|
|
541
|
+
- If the result lists declared runtime capabilities (live data, shared state, Claude calls), warn the user: Conductor renders pages in a sandbox that blocks `fetch`/XHR and popups and has no `window.claude`, so those parts will not work there.
|
|
542
|
+
- For the user's own artifact the result names a saved file that holds the full page: Read that file.
|
|
543
|
+
2. **Detect whether it already meets the HTML PRD contract**: the `conductor:doc-type` = `prd` meta tag plus `data-prd-section` and `data-ac` markers (Grep the content).
|
|
544
|
+
- **Meets it**: keep the page verbatim. Skip to step 3 and only set `conductor:issue-id` (adding the meta tag if absent) once the Work Item exists. Run the HTML self-check from 3c and report any failures to the user rather than rewriting their page.
|
|
545
|
+
- **Does not meet it**: use AskUserQuestion with these options:
|
|
546
|
+
- "Convert to Conductor PRD (keeps content and styling, adds the structure)" (Recommended) — restructure the page into the seven sections, feature articles and `data-ac` criteria; keep the author's wording, CSS and layout. Do not invent content: put real source material in each section, write "None" where the page has nothing, and draft any missing P0 fields (Not, Inputs, Outputs, Invariants, acceptance criteria) from the page's own content, flagging them for review. Run the 3c self-check, then 3d.
|
|
547
|
+
- "Attach as-is as a supporting document"
|
|
548
|
+
- "Cancel" — stop.
|
|
549
|
+
- **Attach as-is**: ask (AskUserQuestion) which Work Item to attach to — an existing one (`list_work_items`) or a new one (resolve the Workflow and create it as in Phase 4 steps 1-2). Then `scaffold_document({issueId, filename})` with a descriptive `.html` filename that is not `prd.html`, Write the page verbatim to the returned `absolutePath`, and confirm. No status transition.
|
|
550
|
+
3. **Save a PRD** (meets the contract, or converted) with the Phase 4 sequence: resolve the Workflow, `create_work_item` (title from `<title>` or the `<h1>`, description from the Problem section), `scaffold_document({issueId, filename: "prd.html"})`, Write, then the IN_REVIEW transition and confirmation. Offer supporting documents as in Phase 4.
|
package/assets/cli-manifest.json
CHANGED
|
@@ -155,7 +155,7 @@
|
|
|
155
155
|
"slashCommands": [
|
|
156
156
|
{
|
|
157
157
|
"name": "conductor:prd",
|
|
158
|
-
"description": "Create a PRD for the current project through guided discovery, research, and writing."
|
|
158
|
+
"description": "Create a PRD for the current project through guided discovery, research, and writing. Writes HTML by default; `import` turns an existing HTML page or claude.ai artifact into a PRD."
|
|
159
159
|
},
|
|
160
160
|
{
|
|
161
161
|
"name": "conductor:implement",
|
|
@@ -291,7 +291,7 @@
|
|
|
291
291
|
},
|
|
292
292
|
{
|
|
293
293
|
"name": "list_work_item_comments",
|
|
294
|
-
"description": "List comments on a Work Item, optionally filtered by resolved status.",
|
|
294
|
+
"description": "List comments on a Work Item, optionally filtered by resolved status. HTML-document comments include a rendered-text anchor and an outdated flag.",
|
|
295
295
|
"category": "comments",
|
|
296
296
|
"requiredParams": [
|
|
297
297
|
"issueId"
|
package/dist/commands/lint.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { Command } from 'commander';
|
|
2
|
-
interface PrdResult {
|
|
2
|
+
export interface PrdResult {
|
|
3
3
|
errors: string[];
|
|
4
4
|
warnings: string[];
|
|
5
5
|
acIds: string[];
|
|
@@ -13,6 +13,8 @@ interface TasksResult {
|
|
|
13
13
|
}
|
|
14
14
|
export declare function parseFrontmatter(content: string): Record<string, string> | null;
|
|
15
15
|
export declare function validatePrd(content: string): PrdResult;
|
|
16
|
+
/** Validate an HTML PRD (`prd.html`, schema v2) against the same rules as the markdown validator. */
|
|
17
|
+
export declare function validatePrdHtml(content: string): PrdResult;
|
|
16
18
|
export declare function validateTasks(content: string, prdAcIds: string[]): TasksResult;
|
|
17
19
|
export declare function registerLint(program: Command): void;
|
|
18
20
|
export {};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../src/commands/lint.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;
|
|
1
|
+
{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../../src/commands/lint.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAoDnC,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,IAAI,EAAE,OAAO,CAAA;CACd;AAED,UAAU,WAAW;IACnB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACvB,IAAI,EAAE,OAAO,CAAA;CACd;AAiCD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAY/E;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAuEtD;AAkBD,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAiI1D;AA8ED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,WAAW,CA6E9E;AA4ED,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0HnD"}
|
package/dist/commands/lint.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import * as fs from 'fs';
|
|
2
2
|
import * as path from 'path';
|
|
3
|
+
import { parse as parseHtml, NodeType } from 'node-html-parser';
|
|
3
4
|
import { readConfig } from '../lib/config.js';
|
|
4
5
|
import { lintMermaid } from '../lib/mermaid-lint.js';
|
|
5
6
|
const REQUIRED_SECTIONS = [
|
|
@@ -21,6 +22,30 @@ const REQUIRED_FEATURE_LINES = [
|
|
|
21
22
|
];
|
|
22
23
|
const AC_LINE_REGEX = /^- \[[ x]\] `AC-P[01]-\d+\.\d+`/;
|
|
23
24
|
const AC_ID_IN_LINE = /`(AC-P[01]-\d+\.\d+)`/;
|
|
25
|
+
const AC_ID_REGEX = /^AC-P[01]-\d+\.\d+$/;
|
|
26
|
+
const FEATURE_ID_REGEX = /^P[01]-\d+$/;
|
|
27
|
+
// HTML PRD (schema v2): section ids in required order, with their display names.
|
|
28
|
+
const HTML_REQUIRED_SECTIONS = [
|
|
29
|
+
['problem', 'Problem'],
|
|
30
|
+
['glossary', 'Glossary'],
|
|
31
|
+
['goals', 'Goals'],
|
|
32
|
+
['non-goals', 'Non-Goals'],
|
|
33
|
+
['users', 'Users'],
|
|
34
|
+
['reference-patterns', 'Reference Patterns'],
|
|
35
|
+
['features', 'Features'],
|
|
36
|
+
];
|
|
37
|
+
const HTML_NONEMPTY_SECTIONS = new Set(['glossary', 'reference-patterns']);
|
|
38
|
+
const HTML_P0_FIELDS = ['What', 'Not', 'Inputs', 'Outputs', 'Invariants'];
|
|
39
|
+
// Script origins the viewer's CSP allows (script-src). Must stay in sync with the policy in
|
|
40
|
+
// conductor-frontend/src/components/markdown/htmlDocument.ts; docs/html-documents.md is the
|
|
41
|
+
// written source of truth, since the two packages cannot share code.
|
|
42
|
+
const HTML_SCRIPT_ORIGINS = new Set([
|
|
43
|
+
'https://cdnjs.cloudflare.com',
|
|
44
|
+
'https://cdn.jsdelivr.net',
|
|
45
|
+
'https://unpkg.com',
|
|
46
|
+
'https://cdn.tailwindcss.com',
|
|
47
|
+
'https://code.jquery.com',
|
|
48
|
+
]);
|
|
24
49
|
/** Lint every ```mermaid block across all .md docs in an issue directory. */
|
|
25
50
|
function lintIssueMermaid(issueDir) {
|
|
26
51
|
const errors = [];
|
|
@@ -125,6 +150,145 @@ export function validatePrd(content) {
|
|
|
125
150
|
}
|
|
126
151
|
return { errors, warnings, acIds, isV2: true };
|
|
127
152
|
}
|
|
153
|
+
/** Visible text of a node, skipping <script>/<style> and (optionally) <h2> headings. */
|
|
154
|
+
function htmlText(node, skipH2 = false) {
|
|
155
|
+
let out = '';
|
|
156
|
+
for (const child of node.childNodes) {
|
|
157
|
+
if (child.nodeType === NodeType.TEXT_NODE) {
|
|
158
|
+
out += ` ${child.rawText}`;
|
|
159
|
+
}
|
|
160
|
+
else if (child.nodeType === NodeType.ELEMENT_NODE) {
|
|
161
|
+
const el = child;
|
|
162
|
+
const tag = el.tagName.toLowerCase();
|
|
163
|
+
if (tag === 'script' || tag === 'style' || (skipH2 && tag === 'h2'))
|
|
164
|
+
continue;
|
|
165
|
+
out += ` ${htmlText(el)}`;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
return out.replace(/\s+/g, ' ').trim();
|
|
169
|
+
}
|
|
170
|
+
/** Validate an HTML PRD (`prd.html`, schema v2) against the same rules as the markdown validator. */
|
|
171
|
+
export function validatePrdHtml(content) {
|
|
172
|
+
const errors = [];
|
|
173
|
+
const warnings = [];
|
|
174
|
+
const acIds = [];
|
|
175
|
+
const F = 'prd.html';
|
|
176
|
+
const root = parseHtml(content);
|
|
177
|
+
const meta = (name) => root.querySelector(`meta[name="${name}"]`)?.getAttribute('content')?.trim();
|
|
178
|
+
if (meta('conductor:schema-version') !== '2') {
|
|
179
|
+
errors.push(`${F}: missing <meta name="conductor:schema-version" content="2">`);
|
|
180
|
+
return { errors, warnings, acIds, isV2: false };
|
|
181
|
+
}
|
|
182
|
+
if (meta('conductor:doc-type') !== 'prd') {
|
|
183
|
+
errors.push(`${F}: missing <meta name="conductor:doc-type" content="prd">`);
|
|
184
|
+
}
|
|
185
|
+
// Sections: present, in order, each with an <h2>.
|
|
186
|
+
const sections = root.querySelectorAll('section[data-prd-section]');
|
|
187
|
+
const byName = new Map();
|
|
188
|
+
for (const sec of sections) {
|
|
189
|
+
const name = sec.getAttribute('data-prd-section') ?? '';
|
|
190
|
+
if (!byName.has(name))
|
|
191
|
+
byName.set(name, sec);
|
|
192
|
+
}
|
|
193
|
+
for (const [name, label] of HTML_REQUIRED_SECTIONS) {
|
|
194
|
+
const sec = byName.get(name);
|
|
195
|
+
if (!sec) {
|
|
196
|
+
errors.push(`${F}: missing required section: ${label}`);
|
|
197
|
+
continue;
|
|
198
|
+
}
|
|
199
|
+
if (!sec.querySelector('h2')) {
|
|
200
|
+
errors.push(`${F}: section ${label}: missing <h2> heading`);
|
|
201
|
+
}
|
|
202
|
+
if (HTML_NONEMPTY_SECTIONS.has(name) && htmlText(sec, true) === '' && !sec.querySelector('img, svg, table')) {
|
|
203
|
+
errors.push(`${F}: section ${label}: empty — write entries or <p><em>None.</em></p>`);
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
const requiredNames = HTML_REQUIRED_SECTIONS.map(([n]) => n);
|
|
207
|
+
const seenOrder = sections
|
|
208
|
+
.map(sec => sec.getAttribute('data-prd-section') ?? '')
|
|
209
|
+
.filter((n, i, arr) => requiredNames.includes(n) && arr.indexOf(n) === i);
|
|
210
|
+
const expectedOrder = requiredNames.filter(n => seenOrder.includes(n));
|
|
211
|
+
if (seenOrder.join('|') !== expectedOrder.join('|')) {
|
|
212
|
+
errors.push(`${F}: sections out of order: expected ${requiredNames.join(', ')}`);
|
|
213
|
+
}
|
|
214
|
+
// Features and acceptance criteria.
|
|
215
|
+
const featuresRoot = byName.get('features') ?? root;
|
|
216
|
+
const seenFeatures = new Set();
|
|
217
|
+
const seenAcs = new Set();
|
|
218
|
+
for (const art of featuresRoot.querySelectorAll('article[data-feature]')) {
|
|
219
|
+
const fid = (art.getAttribute('data-feature') ?? '').trim();
|
|
220
|
+
if (!FEATURE_ID_REGEX.test(fid)) {
|
|
221
|
+
errors.push(`${F}: feature ${fid || '?'}: malformed feature id (expected P0-1, P1-2, ...)`);
|
|
222
|
+
continue;
|
|
223
|
+
}
|
|
224
|
+
if (seenFeatures.has(fid))
|
|
225
|
+
errors.push(`${F}: duplicate feature id: ${fid}`);
|
|
226
|
+
seenFeatures.add(fid);
|
|
227
|
+
const priority = fid.slice(0, 2);
|
|
228
|
+
if (!art.querySelector('h3'))
|
|
229
|
+
errors.push(`${F}: feature ${fid}: missing <h3> heading`);
|
|
230
|
+
if (priority === 'P0') {
|
|
231
|
+
const fields = new Set(art.querySelectorAll('dt').map(dt => htmlText(dt).replace(/:$/, '').trim().toLowerCase()));
|
|
232
|
+
for (const field of HTML_P0_FIELDS) {
|
|
233
|
+
if (!fields.has(field.toLowerCase())) {
|
|
234
|
+
errors.push(`${F}: feature ${fid}: missing required field: ${field}`);
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
if (!art.querySelector('ul[data-acs]')) {
|
|
238
|
+
errors.push(`${F}: feature ${fid}: missing required field: Acceptance Criteria`);
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
for (const li of art.querySelectorAll('ul[data-acs] > li')) {
|
|
242
|
+
if (!li.hasAttribute('data-ac')) {
|
|
243
|
+
errors.push(`${F}: feature ${fid}: acceptance criterion missing data-ac: ${htmlText(li).slice(0, 60)}`);
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
for (const li of art.querySelectorAll('[data-ac]')) {
|
|
247
|
+
const id = (li.getAttribute('data-ac') ?? '').trim();
|
|
248
|
+
if (!AC_ID_REGEX.test(id)) {
|
|
249
|
+
errors.push(`${F}: feature ${fid}: malformed acceptance criterion id: ${id || '(empty)'}`);
|
|
250
|
+
continue;
|
|
251
|
+
}
|
|
252
|
+
if (!id.startsWith(`AC-${fid}.`)) {
|
|
253
|
+
errors.push(`${F}: feature ${fid}: AC ${id} does not belong to this feature`);
|
|
254
|
+
}
|
|
255
|
+
if (seenAcs.has(id)) {
|
|
256
|
+
errors.push(`${F}: duplicate AC id: ${id}`);
|
|
257
|
+
}
|
|
258
|
+
else {
|
|
259
|
+
seenAcs.add(id);
|
|
260
|
+
acIds.push(id);
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
// Self-containment: Conductor renders the page with connect-src 'none'.
|
|
265
|
+
for (const script of root.querySelectorAll('script')) {
|
|
266
|
+
const src = script.getAttribute('src');
|
|
267
|
+
if (src) {
|
|
268
|
+
let origin = '';
|
|
269
|
+
try {
|
|
270
|
+
origin = new URL(src).origin;
|
|
271
|
+
}
|
|
272
|
+
catch {
|
|
273
|
+
origin = '';
|
|
274
|
+
}
|
|
275
|
+
if (!HTML_SCRIPT_ORIGINS.has(origin)) {
|
|
276
|
+
warnings.push(`${F}: script src ${src} is not from an allowed CDN (${[...HTML_SCRIPT_ORIGINS].map(o => o.replace('https://', '')).join(', ')})`);
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
const code = script.innerHTML;
|
|
280
|
+
if (/window\.claude\b/.test(code)) {
|
|
281
|
+
warnings.push(`${F}: script uses window.claude, which is unavailable in Conductor`);
|
|
282
|
+
}
|
|
283
|
+
if (/\bwindow\.open\s*\(/.test(code)) {
|
|
284
|
+
warnings.push(`${F}: script calls window.open, but the sandbox blocks popups (use a plain https link)`);
|
|
285
|
+
}
|
|
286
|
+
if (/\bfetch\s*\(|XMLHttpRequest/.test(code)) {
|
|
287
|
+
warnings.push(`${F}: script makes network requests, which Conductor blocks (connect-src 'none')`);
|
|
288
|
+
}
|
|
289
|
+
}
|
|
290
|
+
return { errors, warnings, acIds, isV2: true };
|
|
291
|
+
}
|
|
128
292
|
function collectFeatures(lines) {
|
|
129
293
|
const features = [];
|
|
130
294
|
let currentPriority = null;
|
|
@@ -270,7 +434,10 @@ export function validateTasks(content, prdAcIds) {
|
|
|
270
434
|
}
|
|
271
435
|
function lintIssue(localPath, issueId) {
|
|
272
436
|
const issueDir = path.join(localPath, '.conductor', 'issues', issueId);
|
|
273
|
-
const
|
|
437
|
+
const htmlPrdPath = path.join(issueDir, 'prd.html');
|
|
438
|
+
const useHtml = fs.existsSync(htmlPrdPath);
|
|
439
|
+
const prdFile = useHtml ? 'prd.html' : 'prd.md';
|
|
440
|
+
const prdPath = useHtml ? htmlPrdPath : path.join(issueDir, 'prd.md');
|
|
274
441
|
const tasksPath = path.join(issueDir, 'tasks.json');
|
|
275
442
|
const prdResult = { ok: true, errors: [] };
|
|
276
443
|
const tasksResult = { ok: true, errors: [] };
|
|
@@ -279,11 +446,11 @@ function lintIssue(localPath, issueId) {
|
|
|
279
446
|
let tasksValidation = null;
|
|
280
447
|
if (!fs.existsSync(prdPath)) {
|
|
281
448
|
prdResult.ok = false;
|
|
282
|
-
prdResult.errors.push(
|
|
449
|
+
prdResult.errors.push(`${prdFile}: file not found at ${prdPath}`);
|
|
283
450
|
}
|
|
284
451
|
else {
|
|
285
452
|
const content = String(fs.readFileSync(prdPath, 'utf8'));
|
|
286
|
-
prdValidation = validatePrd(content);
|
|
453
|
+
prdValidation = useHtml ? validatePrdHtml(content) : validatePrd(content);
|
|
287
454
|
prdResult.errors = prdValidation.errors;
|
|
288
455
|
prdResult.ok = prdValidation.errors.length === 0;
|
|
289
456
|
warnings.push(...prdValidation.warnings);
|
|
@@ -314,7 +481,7 @@ function lintIssue(localPath, issueId) {
|
|
|
314
481
|
warnings: mermaidFindings.warnings,
|
|
315
482
|
};
|
|
316
483
|
tasksResult.ok = tasksResult.errors.length === 0;
|
|
317
|
-
return { issueId, prd: prdResult, tasks: tasksResult, mermaid, warnings };
|
|
484
|
+
return { issueId, prdFile, prd: prdResult, tasks: tasksResult, mermaid, warnings };
|
|
318
485
|
}
|
|
319
486
|
function listLocalIssues(localPath) {
|
|
320
487
|
const issuesDir = path.join(localPath, '.conductor', 'issues');
|
|
@@ -403,14 +570,14 @@ Examples:
|
|
|
403
570
|
console.log(w);
|
|
404
571
|
}
|
|
405
572
|
if (r.prd.ok && r.prd.errors.length === 0) {
|
|
406
|
-
if (!r.warnings.some(w => w.startsWith(
|
|
407
|
-
console.log(
|
|
573
|
+
if (!r.warnings.some(w => w.startsWith(`${r.prdFile}:`))) {
|
|
574
|
+
console.log(`✓ ${r.prdFile}`);
|
|
408
575
|
}
|
|
409
576
|
}
|
|
410
577
|
else {
|
|
411
578
|
anyError = true;
|
|
412
579
|
for (const e of r.prd.errors) {
|
|
413
|
-
console.log(e.startsWith(
|
|
580
|
+
console.log(e.startsWith(`${r.prdFile}:`) || e.startsWith('coverage:') ? e : `${r.prdFile}: ${e}`);
|
|
414
581
|
}
|
|
415
582
|
}
|
|
416
583
|
if (r.tasks.ok && r.tasks.errors.length === 0) {
|