@magic-spells/constellation 0.2.2 → 0.4.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 +13 -6
- package/constellation/agent/AGENT-GUIDANCE.md +22 -0
- package/constellation/component/COMPONENT-EDITABLE.md +9 -0
- package/constellation/component/COMPONENT-STATUS-PILL.md +9 -0
- package/constellation/component/COMPONENT-SYNC-PILL.md +9 -0
- package/constellation/decision/DECISION-FEATURE-RELEASE-TYPES.md +50 -0
- package/constellation/decision/DECISION-NATIVE-DECISION-TYPE.md +58 -0
- package/constellation/diagram/DIAGRAM-ARCHITECTURE.md +28 -0
- package/constellation/doc/DOC-CARD-TYPES.md +39 -0
- package/constellation/doc/DOC-CHANGE-TRACKING.md +26 -0
- package/constellation/doc/DOC-CONNECTED-REPOS.md +25 -0
- package/constellation/doc/DOC-DIAGRAMS.md +22 -0
- package/constellation/doc/DOC-FILE-FORMAT.md +54 -0
- package/constellation/doc/DOC-LINT-CODES.md +35 -0
- package/constellation/doc/DOC-MCP-SERVER.md +59 -0
- package/constellation/doc/DOC-MCP-UPGRADES.md +57 -0
- package/constellation/external/EXTERNAL-AJV.md +7 -0
- package/constellation/external/EXTERNAL-GIT.md +7 -0
- package/constellation/external/EXTERNAL-GRAY-MATTER.md +7 -0
- package/constellation/external/EXTERNAL-MCP-SDK.md +7 -0
- package/constellation/external/EXTERNAL-ZOD.md +7 -0
- package/constellation/file/FILE-CLI.md +9 -0
- package/constellation/file/FILE-CODE.md +9 -0
- package/constellation/file/FILE-EXTRACT.md +9 -0
- package/constellation/file/FILE-GIT.md +9 -0
- package/constellation/file/FILE-HANDLES.md +9 -0
- package/constellation/file/FILE-INDEXER.md +11 -0
- package/constellation/file/FILE-LINT.md +9 -0
- package/constellation/file/FILE-MCP-SEARCH.md +12 -0
- package/constellation/file/FILE-MCP-SERVER.md +9 -0
- package/constellation/file/FILE-PARSE.md +9 -0
- package/constellation/file/FILE-RENAME.md +18 -0
- package/constellation/file/FILE-REPOS.md +9 -0
- package/constellation/file/FILE-RESOLVE.md +9 -0
- package/constellation/file/FILE-SCAFFOLD.md +12 -0
- package/constellation/file/FILE-SERVE.md +9 -0
- package/constellation/file/FILE-SYNC.md +9 -0
- package/constellation/file/FILE-TYPES.md +9 -0
- package/constellation/file/FILE-VALIDATE.md +11 -0
- package/constellation/file/FILE-WRITER.md +11 -0
- package/constellation/flow/FLOW-DRIFT-DETECT.md +11 -0
- package/constellation/flow/FLOW-LINT-PIPELINE.md +14 -0
- package/constellation/flow/FLOW-SYNC-PLAN.md +13 -0
- package/constellation/page/PAGE-VIEWER-CARD.md +9 -0
- package/constellation/page/PAGE-VIEWER-HOME.md +9 -0
- package/constellation/plan.md +59 -0
- package/constellation/test/TEST-SUITE.md +9 -0
- package/dist/cli/index.js +37 -0
- package/dist/cli/index.js.map +1 -1
- package/dist/core/code.d.ts +4 -2
- package/dist/core/code.js +22 -7
- package/dist/core/code.js.map +1 -1
- package/dist/core/git.d.ts +2 -0
- package/dist/core/git.js +6 -0
- package/dist/core/git.js.map +1 -1
- package/dist/core/handles.d.ts +1 -1
- package/dist/core/handles.js +4 -1
- package/dist/core/handles.js.map +1 -1
- package/dist/core/indexer.js +1 -1
- package/dist/core/rename.d.ts +24 -0
- package/dist/core/rename.js +72 -0
- package/dist/core/rename.js.map +1 -0
- package/dist/core/repos.d.ts +2 -0
- package/dist/core/repos.js +5 -1
- package/dist/core/repos.js.map +1 -1
- package/dist/core/sync.d.ts +2 -0
- package/dist/core/sync.js +3 -1
- package/dist/core/sync.js.map +1 -1
- package/dist/core/types.d.ts +1 -1
- package/dist/core/types.js +3 -2
- package/dist/core/types.js.map +1 -1
- package/dist/core/validate.js +14 -1
- package/dist/core/validate.js.map +1 -1
- package/dist/core/writer.d.ts +29 -0
- package/dist/core/writer.js +98 -3
- package/dist/core/writer.js.map +1 -1
- package/dist/mcp/search.d.ts +2 -2
- package/dist/mcp/search.js +27 -5
- package/dist/mcp/search.js.map +1 -1
- package/dist/mcp/server.js +311 -101
- package/dist/mcp/server.js.map +1 -1
- package/dist/serve/server.js +6 -7
- package/dist/serve/server.js.map +1 -1
- package/examples/constellation/decision/DECISION-NO-HARD-DELETE.md +31 -0
- package/examples/constellation/feature/FEATURE-AUTO-ASSIGNMENT.md +24 -0
- package/examples/constellation/release/RELEASE-V1-1-0.md +14 -0
- package/package.json +2 -2
- package/schemas/decision.json +14 -0
- package/schemas/doc.json +1 -1
- package/schemas/feature.json +19 -0
- package/schemas/plan.json +1 -1
- package/schemas/release.json +14 -0
- package/skill/SKILL.md +39 -7
- package/skill/methodology.md +10 -3
- package/skill/types/decision.md +59 -0
- package/skill/types/doc.md +2 -2
- package/skill/types/feature.md +53 -0
- package/skill/types/plan.md +1 -1
- package/skill/types/release.md +37 -0
- package/viewer/dist/assets/{arc-YuzGWkw8.js → arc-DcXsmPgw.js} +1 -1
- package/viewer/dist/assets/architecture-7EHR7CIX-CXZxmtF5.js +1 -0
- package/viewer/dist/assets/{architectureDiagram-3BPJPVTR-BgksqMlF.js → architectureDiagram-3BPJPVTR-Cfq3OC2M.js} +1 -1
- package/viewer/dist/assets/{blockDiagram-GPEHLZMM-Bc6JILFK.js → blockDiagram-GPEHLZMM-CPuRJqEW.js} +1 -1
- package/viewer/dist/assets/{c4Diagram-AAUBKEIU-CRVt42df.js → c4Diagram-AAUBKEIU-CcVcItWo.js} +1 -1
- package/viewer/dist/assets/channel-DjvAjJNc.js +1 -0
- package/viewer/dist/assets/{chunk-2J33WTMH-CpuwKeX6.js → chunk-2J33WTMH-C_N821rH.js} +1 -1
- package/viewer/dist/assets/{chunk-3OPIFGDE-BG_ijJhE.js → chunk-3OPIFGDE-C5c2MY1i.js} +1 -1
- package/viewer/dist/assets/{chunk-4BX2VUAB-Bgz1tnDP.js → chunk-4BX2VUAB-BjYatXZ-.js} +1 -1
- package/viewer/dist/assets/{chunk-55IACEB6-NdWURd2K.js → chunk-55IACEB6-A3JXj2W_.js} +1 -1
- package/viewer/dist/assets/{chunk-5ZQYHXKU-wzW5x_7z.js → chunk-5ZQYHXKU-zDiW1Z3e.js} +1 -1
- package/viewer/dist/assets/{chunk-727SXJPM-BxKeJXYf.js → chunk-727SXJPM-CI3VBaXr.js} +1 -1
- package/viewer/dist/assets/{chunk-AQP2D5EJ-gPm6xhPX.js → chunk-AQP2D5EJ-DHpkJ1wF.js} +1 -1
- package/viewer/dist/assets/{chunk-BSJP7CBP-C30ZXEUD.js → chunk-BSJP7CBP-DXx1-_Zs.js} +1 -1
- package/viewer/dist/assets/{chunk-CSCIHK7Q-C9h7yfl1.js → chunk-CSCIHK7Q-DQOe6SQo.js} +6 -6
- package/viewer/dist/assets/{chunk-FMBD7UC4-BcSnkYc3.js → chunk-FMBD7UC4-DSvwBCfP.js} +1 -1
- package/viewer/dist/assets/{chunk-KSCS5N6A-rxSD5-MD.js → chunk-KSCS5N6A-C3haQOao.js} +1 -1
- package/viewer/dist/assets/{chunk-L5ZTLDWV-DGwFsVWy.js → chunk-L5ZTLDWV-DyHfVaRK.js} +1 -1
- package/viewer/dist/assets/{chunk-LZXEDZCA-BY3sTuvt.js → chunk-LZXEDZCA-CtMQqok_.js} +2 -2
- package/viewer/dist/assets/{chunk-ND2GUHAM-PqmKwdzq.js → chunk-ND2GUHAM-Cfp2zN_i.js} +1 -1
- package/viewer/dist/assets/{chunk-NZK2D7GU-BAZbzxhl.js → chunk-NZK2D7GU-Cn753oIP.js} +1 -1
- package/viewer/dist/assets/{chunk-O5CBEL6O-SvZfZ-0j.js → chunk-O5CBEL6O-BO32_B2k.js} +1 -1
- package/viewer/dist/assets/chunk-QZHKN3VN-uc4X3bta.js +1 -0
- package/viewer/dist/assets/chunk-WU5MYG2G-D-wARmLR.js +1 -0
- package/viewer/dist/assets/{chunk-XPW4576I-1OXPbRQX.js → chunk-XPW4576I-DQFQAfwD.js} +1 -1
- package/viewer/dist/assets/classDiagram-4FO5ZUOK-CosoTts2.js +1 -0
- package/viewer/dist/assets/classDiagram-v2-Q7XG4LA2-CosoTts2.js +1 -0
- package/viewer/dist/assets/{cose-bilkent-S5V4N54A-DtCvLpah.js → cose-bilkent-S5V4N54A-Ibe8V5Cm.js} +1 -1
- package/viewer/dist/assets/{dagre-BM42HDAG-B55Ilz10.js → dagre-BM42HDAG-BlOzR9WP.js} +1 -1
- package/viewer/dist/assets/{diagram-2AECGRRQ-ClqSMarp.js → diagram-2AECGRRQ-l8omQVTU.js} +1 -1
- package/viewer/dist/assets/{diagram-5GNKFQAL-Dx74UdxY.js → diagram-5GNKFQAL-_rHQzAtO.js} +1 -1
- package/viewer/dist/assets/{diagram-KO2AKTUF-Vj0buH8e.js → diagram-KO2AKTUF-DCLRVRMY.js} +1 -1
- package/viewer/dist/assets/{diagram-LMA3HP47-DpEm8RZd.js → diagram-LMA3HP47-14HnEIqk.js} +1 -1
- package/viewer/dist/assets/{diagram-OG6HWLK6-Crl3BdwC.js → diagram-OG6HWLK6-CVKNCbkR.js} +1 -1
- package/viewer/dist/assets/{dist-C2uHOEFB.js → dist-BcVVfWxM.js} +1 -1
- package/viewer/dist/assets/{erDiagram-TEJ5UH35-B-Mf-EHP.js → erDiagram-TEJ5UH35-CNjpEfJD.js} +1 -1
- package/viewer/dist/assets/eventmodeling-FCH6USID-Dv27utnc.js +1 -0
- package/viewer/dist/assets/{flowDiagram-I6XJVG4X-B9stChWN.js → flowDiagram-I6XJVG4X-Bvekb5gu.js} +1 -1
- package/viewer/dist/assets/{ganttDiagram-6RSMTGT7-DzWlclwM.js → ganttDiagram-6RSMTGT7-2TpeWF0N.js} +1 -1
- package/viewer/dist/assets/{gitGraph-WXDBUCRP-CdVI3GTp.js → gitGraph-WXDBUCRP-CPfybYvf.js} +1 -1
- package/viewer/dist/assets/{gitGraphDiagram-PVQCEYII-Dn9yRc1N.js → gitGraphDiagram-PVQCEYII-BWZNJ9lY.js} +1 -1
- package/viewer/dist/assets/index-BEJYsfzU.css +2 -0
- package/viewer/dist/assets/{index-BsGRgBOD.js → index-Cqx2pndu.js} +3 -3
- package/viewer/dist/assets/{info-J43DQDTF-CXV3Mm9T.js → info-J43DQDTF-CxgngY4X.js} +1 -1
- package/viewer/dist/assets/{infoDiagram-5YYISTIA-zIUka_J2.js → infoDiagram-5YYISTIA-CARF_viY.js} +1 -1
- package/viewer/dist/assets/{ishikawaDiagram-YF4QCWOH-DsZwNuE3.js → ishikawaDiagram-YF4QCWOH-DcxZvtur.js} +1 -1
- package/viewer/dist/assets/{journeyDiagram-JHISSGLW-BhSTSB2s.js → journeyDiagram-JHISSGLW-Wu7zolY5.js} +1 -1
- package/viewer/dist/assets/{kanban-definition-UN3LZRKU-sCAldj86.js → kanban-definition-UN3LZRKU--LMKLf5s.js} +1 -1
- package/viewer/dist/assets/{line-D7b3fopb.js → line-DH7DV7uw.js} +1 -1
- package/viewer/dist/assets/{linear-BWlvVc_d.js → linear-C6xJ2LrZ.js} +1 -1
- package/viewer/dist/assets/{mermaid-parser.core-BdEYBvaj.js → mermaid-parser.core-DkqLwTDu.js} +2 -2
- package/viewer/dist/assets/{mermaid.core-C9bGWeJU.js → mermaid.core-H-eI9axh.js} +3 -3
- package/viewer/dist/assets/{mindmap-definition-RKZ34NQL-DbTvvku-.js → mindmap-definition-RKZ34NQL-xjt8VE8m.js} +1 -1
- package/viewer/dist/assets/{packet-YPE3B663-DRfLruyq.js → packet-YPE3B663-BX0W_wIa.js} +1 -1
- package/viewer/dist/assets/{pie-LRSECV5Y-47xXMkK-.js → pie-LRSECV5Y-B8cD_uBh.js} +1 -1
- package/viewer/dist/assets/{pieDiagram-4H26LBE5-Ckno9E1M.js → pieDiagram-4H26LBE5-DpM-20zS.js} +1 -1
- package/viewer/dist/assets/{quadrantDiagram-W4KKPZXB-XB5kJ_2c.js → quadrantDiagram-W4KKPZXB-CLS4_FQ4.js} +1 -1
- package/viewer/dist/assets/{radar-GUYGQ44K-CLwIH5Zr.js → radar-GUYGQ44K-CQKcm4b5.js} +1 -1
- package/viewer/dist/assets/{requirementDiagram-4Y6WPE33-D3fApL0X.js → requirementDiagram-4Y6WPE33-ESLvOyQ5.js} +1 -1
- package/viewer/dist/assets/{sankeyDiagram-5OEKKPKP-6UdaRhuZ.js → sankeyDiagram-5OEKKPKP-BT6w9JdP.js} +1 -1
- package/viewer/dist/assets/{sequenceDiagram-3UESZ5HK-ClIrrs0w.js → sequenceDiagram-3UESZ5HK-DJNAaEbv.js} +1 -1
- package/viewer/dist/assets/{src-BPb55SrS.js → src-ituc2uBy.js} +1 -1
- package/viewer/dist/assets/{stateDiagram-AJRCARHV-CCsrcv5R.js → stateDiagram-AJRCARHV-Bw7VoMlA.js} +1 -1
- package/viewer/dist/assets/stateDiagram-v2-BHNVJYJU-DZdCGd2U.js +1 -0
- package/viewer/dist/assets/{timeline-definition-PNZ67QCA-BkiWQlVI.js → timeline-definition-PNZ67QCA-Ddr17PAT.js} +1 -1
- package/viewer/dist/assets/{treeView-BLDUP644-m1mGpAE8.js → treeView-BLDUP644-mqjp8QBZ.js} +1 -1
- package/viewer/dist/assets/{treemap-LRROVOQU-Bapvwi0Q.js → treemap-LRROVOQU-BeaxV5lr.js} +1 -1
- package/viewer/dist/assets/{vennDiagram-CIIHVFJN-BlH71Nmx.js → vennDiagram-CIIHVFJN-ySQYfWol.js} +1 -1
- package/viewer/dist/assets/{wardley-L42UT6IY-CPRSoKgV.js → wardley-L42UT6IY-BvtBpxdo.js} +1 -1
- package/viewer/dist/assets/{wardleyDiagram-YWT4CUSO-C-ptFJ9t.js → wardleyDiagram-YWT4CUSO-DRZFQiXX.js} +1 -1
- package/viewer/dist/assets/{xychartDiagram-2RQKCTM6-C4rfeH4W.js → xychartDiagram-2RQKCTM6-kXPrRy2n.js} +1 -1
- package/viewer/dist/index.html +2 -2
- package/docs/001-file-format.md +0 -265
- package/docs/002-mcp.md +0 -186
- package/docs/003-mcp-upgrade-plan.md +0 -138
- package/viewer/dist/assets/architecture-7EHR7CIX-BAboPvK1.js +0 -1
- package/viewer/dist/assets/channel-D8YnBgqu.js +0 -1
- package/viewer/dist/assets/chunk-QZHKN3VN-ClYnv9g5.js +0 -1
- package/viewer/dist/assets/chunk-WU5MYG2G-CvL2Yleq.js +0 -1
- package/viewer/dist/assets/classDiagram-4FO5ZUOK-B8YUd1jx.js +0 -1
- package/viewer/dist/assets/classDiagram-v2-Q7XG4LA2-B8YUd1jx.js +0 -1
- package/viewer/dist/assets/eventmodeling-FCH6USID-CZ5gxAxG.js +0 -1
- package/viewer/dist/assets/index-Bqs39Itl.css +0 -2
- package/viewer/dist/assets/stateDiagram-v2-BHNVJYJU-C1phrPNi.js +0 -1
package/skill/SKILL.md
CHANGED
|
@@ -41,7 +41,8 @@ dashes only. No underscores, no lowercase.
|
|
|
41
41
|
| `DB-` | `db/` | Tables / collections | `types/db.md` |
|
|
42
42
|
| `DATATYPE-` | `datatype/` | Type schemas | `types/datatype.md` |
|
|
43
43
|
| `ROLE-` | `role/` | Roles / permissions | `types/role.md` |
|
|
44
|
-
| `DOC-` | `doc/` | Documentation,
|
|
44
|
+
| `DOC-` | `doc/` | Documentation, guides, rules | `types/doc.md` |
|
|
45
|
+
| `DECISION-` | `decision/` | Architecture decisions (ADRs) | `types/decision.md` |
|
|
45
46
|
| `FILE-` | `file/` | Source file references | `types/file.md` |
|
|
46
47
|
| `TEST-` | `test/` | Test specs | `types/test.md` |
|
|
47
48
|
| `EXTERNAL-` | `external/` | External services | `types/external.md` |
|
|
@@ -54,6 +55,8 @@ dashes only. No underscores, no lowercase.
|
|
|
54
55
|
| `DIAGRAM-` | `diagram/` | Architecture diagrams | `types/diagram.md` |
|
|
55
56
|
| `AGENT-` | `agent/` | AI agent instructions | `types/agent.md` |
|
|
56
57
|
| `PLAN-` | `plan/` | Plan docs (`plan.md` at root = `PLAN-PROJECT`) | `types/plan.md` |
|
|
58
|
+
| `FEATURE-` | `feature/` | Future work units (iteration) | `types/feature.md` |
|
|
59
|
+
| `RELEASE-` | `release/` | Version milestones | `types/release.md` |
|
|
57
60
|
|
|
58
61
|
Read the matching `types/<type>.md` before writing a card of a type you haven't
|
|
59
62
|
authored in this session — it has the field table and a golden example.
|
|
@@ -76,7 +79,11 @@ Beyond the four reserved keys, a few **cross-type metadata fields** are valid on
|
|
|
76
79
|
(defined in `schemas/card.json`) but are tool-managed, not hand-authored: `code_refs` (extra
|
|
77
80
|
code this card is bound to — `path` or `path:symbol`), `verified_sha` / `verified_at` (set by
|
|
78
81
|
`set_verified` — the drift baseline), and `notes` (append-only typed memory, via
|
|
79
|
-
`append_note`). Reach for the tools rather than writing these by hand.
|
|
82
|
+
`append_note`). Reach for the tools rather than writing these by hand. Notes are
|
|
83
|
+
retrievable: `search` matches note text, `list_notes` lists them across cards by kind
|
|
84
|
+
(every gotcha / every decision in one call), and `get_card` filters them per card.
|
|
85
|
+
A `decision` note is for a choice local to that one card; a decision that shaped
|
|
86
|
+
*several* cards gets its own `DECISION` card, connected to each of them.
|
|
80
87
|
|
|
81
88
|
## Connections — how the graph gets wired
|
|
82
89
|
|
|
@@ -104,6 +111,8 @@ that's how you mark future work.
|
|
|
104
111
|
- STATE: a ```mermaid stateDiagram-v2 block.
|
|
105
112
|
- DIAGRAM: a ```mermaid flowchart with **handles as node IDs** so the diagram joins
|
|
106
113
|
the graph.
|
|
114
|
+
- DECISION: `## Context` / `## Decision` / `## Alternatives` / `## Consequences`
|
|
115
|
+
sections (suggested, not enforced).
|
|
107
116
|
- Everything else: prose with `[[links]]`. Put relationship nuance in prose, not
|
|
108
117
|
in structure.
|
|
109
118
|
|
|
@@ -171,6 +180,24 @@ plan mode pulling the relevant plan into context — `traverse` from the entry p
|
|
|
171
180
|
you intend into the plan you present. Execute those Constellation writes first, before any
|
|
172
181
|
code, once the user approves.
|
|
173
182
|
|
|
183
|
+
## Iterating: features & releases
|
|
184
|
+
|
|
185
|
+
PLAN cards and phases carry the *initial* build. Once a project is live, work
|
|
186
|
+
arrives as feature branches and ships as versions — model that with FEATURE and
|
|
187
|
+
RELEASE cards:
|
|
188
|
+
|
|
189
|
+
- A coherent slice of future work is a **FEATURE** card: connect it to every card
|
|
190
|
+
it adds or touches (new work as `status: planned`), record intent / scope /
|
|
191
|
+
acceptance in the body, and set `branch:` while it's in flight. Its status is
|
|
192
|
+
the arc: `planned` → `building` (on its branch) → `built` (merged) →
|
|
193
|
+
`verified`. A shipped FEATURE stays — it's the record of why the system grew.
|
|
194
|
+
- A version milestone is a **RELEASE** card; features target it via their
|
|
195
|
+
`release:` field. The body is theme + upgrade/migration notes — **never a
|
|
196
|
+
changelog** (what shipped is git's job).
|
|
197
|
+
- Not a ticket tracker: work that's one card's status flip needs no FEATURE
|
|
198
|
+
card. The backlog stays `list_cards status: ["planned", "building", "none"]`;
|
|
199
|
+
a FEATURE's neighborhood (`traverse` from its handle) is the feature's spec.
|
|
200
|
+
|
|
174
201
|
## Syncing the plan to code
|
|
175
202
|
|
|
176
203
|
The plan is the source of truth: you change behavior by editing the **plan first**, then
|
|
@@ -246,14 +273,19 @@ Cards never connect across repos; the relationship between repos lives in the
|
|
|
246
273
|
2. Write or edit the card — prefer small, byte-cheap writes over rewriting a whole card:
|
|
247
274
|
`append_note` for a typed note (decision / gotcha / state / deviation / verified),
|
|
248
275
|
`edit_section` to replace a single `##` section in place.
|
|
249
|
-
3.
|
|
276
|
+
3. Renaming a handle is a plan-wide operation: use the MCP `rename_card`, which moves the
|
|
277
|
+
file and rewrites every reference (connections, frontmatter values, `[[links]]`, mermaid
|
|
278
|
+
node IDs) as whole tokens. Never hand-rename the file and chase references yourself.
|
|
279
|
+
4. Verify: `npx constellation lint` (errors break the graph and must be fixed;
|
|
250
280
|
warnings are quality signals).
|
|
251
|
-
|
|
281
|
+
5. Update `status` when reality changes: `planned → building → built`, and mark
|
|
252
282
|
`verified` only after checking the card against the actual code — use `set_verified`,
|
|
253
283
|
which records the git sha you checked against so later drift is detectable
|
|
254
|
-
(`stale_report` / `check_sync`).
|
|
255
|
-
|
|
256
|
-
|
|
284
|
+
(`stale_report` / `check_sync`). The backlog view — everything not yet built — is
|
|
285
|
+
`list_cards status: ["planned", "building", "none"]` (`"none"` = no status set).
|
|
286
|
+
6. Never bulk-rewrite `constellation/plan.md` — edit the relevant section.
|
|
287
|
+
Decisions go in DECISION cards, one file each, not in the plan — connected to
|
|
288
|
+
the cards they shaped (card-local choices: `append_note(kind: decision)`).
|
|
257
289
|
|
|
258
290
|
"What changed in the plan" is never tracked in cards — that's
|
|
259
291
|
`git diff -- constellation/`. Don't add dirty flags or changelogs to frontmatter. The one
|
package/skill/methodology.md
CHANGED
|
@@ -155,9 +155,13 @@ the plan the way a seasoned engineer reviews a design doc: assume something impo
|
|
|
155
155
|
missing, and go find it. This matters more than any single card you write.
|
|
156
156
|
|
|
157
157
|
**First, a quick hygiene sweep** (mechanical, cheap, not the point): `check_integrity` for
|
|
158
|
-
orphans, `list_cards connected:false` for islands,
|
|
158
|
+
orphans, `list_cards connected:false` for islands, `list_cards status: ["planned",
|
|
159
|
+
"building", "none"]` for the open backlog, lint for dangling `[[links]]`/refs (W004)
|
|
159
160
|
and unresolved structured refs (E005), plus code with no card and `built` cards with no
|
|
160
|
-
code.
|
|
161
|
+
code. Skim the recorded memory too — `list_notes kind:gotcha` / `kind:deviation` surfaces
|
|
162
|
+
earlier agents' traps and intentional divergences as review input. If a handle no longer
|
|
163
|
+
says what its card is, `rename_card` moves the file and rewrites every reference plan-wide.
|
|
164
|
+
Fix or note these and move on — they're table stakes.
|
|
161
165
|
|
|
162
166
|
**Then the real review.** Run these lenses across each area *and* the whole — but calibrate
|
|
163
167
|
to the project's stage and scope; a weekend prototype and a production system have very
|
|
@@ -200,7 +204,10 @@ the two kinds of finding:
|
|
|
200
204
|
|
|
201
205
|
Keep it to the few highest-value items, each with a one-line *why* and the card(s) it
|
|
202
206
|
implies. Capture confirmed gaps as `status: planned` cards — visible as intent, honest
|
|
203
|
-
about not existing yet.
|
|
207
|
+
about not existing yet. When several planned cards form one coherent slice of work,
|
|
208
|
+
group them under a `FEATURE` card (connected to each, intent/scope/acceptance in the
|
|
209
|
+
body), optionally targeting a `RELEASE` milestone via its `release:` field — that is
|
|
210
|
+
how iteration stays modeled once the initial build ships. Suggest structural cleanups (split an overloaded card, add a
|
|
204
211
|
missing `STATE`, connect two islands) but leave the call to the user. Taste means proposing
|
|
205
212
|
the smallest set of changes that most improves the plan — not the most cards.
|
|
206
213
|
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# DECISION cards (`DECISION-`, `decision/`)
|
|
2
|
+
|
|
3
|
+
One card per architecture decision (ADR): the choice, the *why*, and the
|
|
4
|
+
alternatives rejected. Docs explain how the system is set up; a DECISION explains
|
|
5
|
+
why it came to be that way. Connect the card to **every card the decision
|
|
6
|
+
shaped** — that's the point of making decisions graph nodes: reading any affected
|
|
7
|
+
card surfaces the reasoning behind it.
|
|
8
|
+
|
|
9
|
+
Scope rule: a choice local to a single card is an `append_note(kind: decision)`
|
|
10
|
+
on that card, not a DECISION card. Promote it to a DECISION card when it touches
|
|
11
|
+
more than one card or was genuinely debated (alternatives worth recording).
|
|
12
|
+
|
|
13
|
+
| Field | Type | Notes |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| `supersedes` | handle | earlier `DECISION-` card this one replaces; must resolve, and connects the two |
|
|
16
|
+
|
|
17
|
+
`status` reads naturally: `planned` = proposed, `built` = adopted/in effect,
|
|
18
|
+
`verified` = re-checked against the code. Never delete a superseded decision —
|
|
19
|
+
the successor points at it via `supersedes`; history is the point.
|
|
20
|
+
|
|
21
|
+
Body sections (suggested, not enforced): **Context** (the forces), **Decision**
|
|
22
|
+
(what was chosen), **Alternatives** (what was rejected and why), **Consequences**
|
|
23
|
+
(what follows).
|
|
24
|
+
|
|
25
|
+
Example — `constellation/decision/DECISION-NO-HARD-DELETE.md`:
|
|
26
|
+
|
|
27
|
+
```markdown
|
|
28
|
+
---
|
|
29
|
+
name: Tickets are never hard-deleted
|
|
30
|
+
status: built
|
|
31
|
+
connections:
|
|
32
|
+
- DB-TICKETS
|
|
33
|
+
- STATE-TICKET
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
# Tickets are never hard-deleted
|
|
37
|
+
|
|
38
|
+
## Context
|
|
39
|
+
|
|
40
|
+
Support history is evidence: agents cite past tickets in disputes, and
|
|
41
|
+
[[JOB-AUTO-ASSIGN]] scores assignees on historical volume.
|
|
42
|
+
|
|
43
|
+
## Decision
|
|
44
|
+
|
|
45
|
+
Rows in [[DB-TICKETS]] are never deleted. "Deleting" a ticket moves it to
|
|
46
|
+
`closed` in [[STATE-TICKET]]; the API exposes no DELETE.
|
|
47
|
+
|
|
48
|
+
## Alternatives
|
|
49
|
+
|
|
50
|
+
- **Hard delete with an audit table** — rejected: two sources of truth, and the
|
|
51
|
+
audit copy drifts from the live schema.
|
|
52
|
+
- **Soft-delete flag (`deleted_at`)** — rejected: every query must remember to
|
|
53
|
+
filter it; `closed` already expresses "out of the working set."
|
|
54
|
+
|
|
55
|
+
## Consequences
|
|
56
|
+
|
|
57
|
+
- Table growth is unbounded; revisit archiving if it becomes a problem.
|
|
58
|
+
- Requester PII lives in closed tickets — retention policy must handle it.
|
|
59
|
+
```
|
package/skill/types/doc.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# DOC cards (`DOC-`, `doc/`)
|
|
2
2
|
|
|
3
3
|
No structured fields — DOC cards are prose. Suggested `kind`: `guide`, `rule`,
|
|
4
|
-
`
|
|
5
|
-
|
|
4
|
+
`meta`. DOCs explain *how* the system is set up; the *why* behind a choice is a
|
|
5
|
+
[DECISION card](./decision.md), not a DOC.
|
|
6
6
|
|
|
7
7
|
Example — `constellation/doc/DOC-TICKET-LIFECYCLE.md`:
|
|
8
8
|
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# FEATURE cards (`FEATURE-`, `feature/`)
|
|
2
|
+
|
|
3
|
+
One card per coherent unit of *future* work — the iteration primitive once a
|
|
4
|
+
project is past its initial build. PLAN cards and phases carry the first build;
|
|
5
|
+
after that, work arrives as features on branches. A FEATURE card groups that
|
|
6
|
+
slice: connect it to **every card the feature adds or touches**, so the graph
|
|
7
|
+
answers "what does shipping this involve" in one hop.
|
|
8
|
+
|
|
9
|
+
Scope rule: this is not a ticket tracker. Work small enough to be one card's
|
|
10
|
+
status flip needs no FEATURE card — just flip the status. Reach for a FEATURE
|
|
11
|
+
when the work spans several cards or needs intent/acceptance recorded.
|
|
12
|
+
|
|
13
|
+
| Field | Type | Notes |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| `release` | handle | `RELEASE-` card this feature targets or shipped in; must resolve, and connects the two |
|
|
16
|
+
| `branch` | string | git branch it's developed on (informational — the card outlives the branch) |
|
|
17
|
+
|
|
18
|
+
`status` is the feature's arc: `planned` = specced, not started; `building` = in
|
|
19
|
+
progress on its branch; `built` = merged; `verified` = confirmed in a release.
|
|
20
|
+
A shipped FEATURE card stays — it's the record of why the system grew, alongside
|
|
21
|
+
any [DECISION cards](./decision.md) it produced.
|
|
22
|
+
|
|
23
|
+
Body: intent (the problem), scope (in/out), acceptance (how you know it's done),
|
|
24
|
+
with `[[links]]` to the cards involved.
|
|
25
|
+
|
|
26
|
+
Example — `constellation/feature/FEATURE-AUTO-ASSIGNMENT.md`:
|
|
27
|
+
|
|
28
|
+
```markdown
|
|
29
|
+
---
|
|
30
|
+
name: Auto-assignment of new tickets
|
|
31
|
+
status: planned
|
|
32
|
+
release: RELEASE-V1-1-0
|
|
33
|
+
branch: feature/auto-assign
|
|
34
|
+
connections:
|
|
35
|
+
- JOB-AUTO-ASSIGN
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
# Auto-assignment of new tickets
|
|
39
|
+
|
|
40
|
+
New tickets sit unassigned until a human triages them; median first-response
|
|
41
|
+
time suffers. Ship [[JOB-AUTO-ASSIGN]] so every ticket created via
|
|
42
|
+
[[API-TICKETS]] gets an assignee within a minute.
|
|
43
|
+
|
|
44
|
+
## Scope
|
|
45
|
+
|
|
46
|
+
- In: assignment job, round-robin scoring over open ticket counts in [[DB-TICKETS]].
|
|
47
|
+
- Out: skill-based routing; reassignment of already-open tickets.
|
|
48
|
+
|
|
49
|
+
## Acceptance
|
|
50
|
+
|
|
51
|
+
- A ticket created while at least one agent is active is assigned in < 60s.
|
|
52
|
+
- Assignment respects [[STATE-TICKET]] — only `open` tickets are eligible.
|
|
53
|
+
```
|
package/skill/types/plan.md
CHANGED
|
@@ -5,7 +5,7 @@ where the project stands. Scoped plans (`PLAN-FRONTEND`) live in `plan/`.
|
|
|
5
5
|
|
|
6
6
|
Keep it **short**. Three rules:
|
|
7
7
|
|
|
8
|
-
- Decisions go in
|
|
8
|
+
- Decisions go in DECISION cards, one file each — not in the plan.
|
|
9
9
|
- Per-card status lives on the cards (`status:`), not in plan checklists.
|
|
10
10
|
- Edit the relevant section; never bulk-rewrite the file (it's shared state).
|
|
11
11
|
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# RELEASE cards (`RELEASE-`, `release/`)
|
|
2
|
+
|
|
3
|
+
One card per version milestone: the **theme and intent** of a release, what's
|
|
4
|
+
targeted at it, and the migration/upgrade notes users need. FEATURE cards point
|
|
5
|
+
here via their `release:` field — the release is the milestone, features are the
|
|
6
|
+
work.
|
|
7
|
+
|
|
8
|
+
**A RELEASE card is not a changelog.** What actually shipped is git's job (tags,
|
|
9
|
+
`diff_plan`, `plan_log`) — never enumerate commits or card-by-card changes in
|
|
10
|
+
the body. Card what git *can't* say: why this release exists, what it's named
|
|
11
|
+
for, what a consumer must do to upgrade.
|
|
12
|
+
|
|
13
|
+
| Field | Type | Notes |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| `version` | string | exact version string, e.g. `1.1.0` (the handle is the identity: `RELEASE-V1-1-0`) |
|
|
16
|
+
|
|
17
|
+
`status` is the milestone's arc: `planned` = targeted/next; `building` = in
|
|
18
|
+
flight; `built` = shipped/tagged; `verified` = validated in production.
|
|
19
|
+
|
|
20
|
+
Example — `constellation/release/RELEASE-V1-1-0.md`:
|
|
21
|
+
|
|
22
|
+
```markdown
|
|
23
|
+
---
|
|
24
|
+
name: v1.1.0 — assignment automation
|
|
25
|
+
status: planned
|
|
26
|
+
version: 1.1.0
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
# v1.1.0 — assignment automation
|
|
30
|
+
|
|
31
|
+
Theme: stop tickets from sitting unassigned. Everything in this release serves
|
|
32
|
+
median first-response time.
|
|
33
|
+
|
|
34
|
+
## Upgrade notes
|
|
35
|
+
|
|
36
|
+
- New env var `ASSIGN_INTERVAL_SECONDS` (default 30); no schema migration.
|
|
37
|
+
```
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{n as e,t}from"./path-BWPyau1x.js";import{a as n,c as r,d as i,f as a,i as o,l as s,m as c,n as l,o as u,p as d,r as f,u as p}from"./dist-
|
|
1
|
+
import{n as e,t}from"./path-BWPyau1x.js";import{a as n,c as r,d as i,f as a,i as o,l as s,m as c,n as l,o as u,p as d,r as f,u as p}from"./dist-BcVVfWxM.js";function m(e){return e.innerRadius}function h(e){return e.outerRadius}function g(e){return e.startAngle}function _(e){return e.endAngle}function v(e){return e&&e.padAngle}function y(e,t,n,r,i,a,o,s){var c=n-e,l=r-t,u=o-i,d=s-a,f=d*c-u*l;if(!(f*f<1e-12))return f=(u*(t-a)-d*(e-i))/f,[e+f*c,t+f*l]}function b(e,t,n,r,i,a,o){var c=e-n,l=t-r,u=(o?a:-a)/d(c*c+l*l),f=u*l,p=-u*c,m=e+f,h=t+p,g=n+f,_=r+p,v=(m+g)/2,y=(h+_)/2,b=g-m,x=_-h,S=b*b+x*x,C=i-a,w=m*_-g*h,T=(x<0?-1:1)*d(s(0,C*C*S-w*w)),E=(w*x-b*T)/S,D=(-w*b-x*T)/S,O=(w*x+b*T)/S,k=(-w*b+x*T)/S,A=E-v,j=D-y,M=O-v,N=k-y;return A*A+j*j>M*M+N*N&&(E=O,D=k),{cx:E,cy:D,x01:-f,y01:-p,x11:E*(i/C-1),y11:D*(i/C-1)}}function x(){var s=m,x=h,S=e(0),C=null,w=g,T=_,E=v,D=null,O=t(k);function k(){var e,t,m=+s.apply(this,arguments),h=+x.apply(this,arguments),g=w.apply(this,arguments)-r,_=T.apply(this,arguments)-r,v=l(_-g),k=_>g;if(D||=e=O(),h<m&&(t=h,h=m,m=t),!(h>1e-12))D.moveTo(0,0);else if(v>c-1e-12)D.moveTo(h*u(g),h*a(g)),D.arc(0,0,h,g,_,!k),m>1e-12&&(D.moveTo(m*u(_),m*a(_)),D.arc(0,0,m,_,g,k));else{var A=g,j=_,M=g,N=_,P=v,F=v,I=E.apply(this,arguments)/2,L=I>1e-12&&(C?+C.apply(this,arguments):d(m*m+h*h)),R=p(l(h-m)/2,+S.apply(this,arguments)),z=R,B=R,V,H;if(L>1e-12){var U=o(L/m*a(I)),W=o(L/h*a(I));(P-=U*2)>1e-12?(U*=k?1:-1,M+=U,N-=U):(P=0,M=N=(g+_)/2),(F-=W*2)>1e-12?(W*=k?1:-1,A+=W,j-=W):(F=0,A=j=(g+_)/2)}var G=h*u(A),K=h*a(A),q=m*u(N),J=m*a(N);if(R>1e-12){var Y=h*u(j),X=h*a(j),Z=m*u(M),Q=m*a(M),$;if(v<i)if($=y(G,K,Z,Q,Y,X,q,J)){var ee=G-$[0],te=K-$[1],ne=Y-$[0],re=X-$[1],ie=1/a(f((ee*ne+te*re)/(d(ee*ee+te*te)*d(ne*ne+re*re)))/2),ae=d($[0]*$[0]+$[1]*$[1]);z=p(R,(m-ae)/(ie-1)),B=p(R,(h-ae)/(ie+1))}else z=B=0}F>1e-12?B>1e-12?(V=b(Z,Q,G,K,h,B,k),H=b(Y,X,q,J,h,B,k),D.moveTo(V.cx+V.x01,V.cy+V.y01),B<R?D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,B,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,h,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),!k),D.arc(H.cx,H.cy,B,n(H.y11,H.x11),n(H.y01,H.x01),!k))):(D.moveTo(G,K),D.arc(0,0,h,A,j,!k)):D.moveTo(G,K),!(m>1e-12)||!(P>1e-12)?D.lineTo(q,J):z>1e-12?(V=b(q,J,Y,X,m,-z,k),H=b(G,K,Z,Q,m,-z,k),D.lineTo(V.cx+V.x01,V.cy+V.y01),z<R?D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(H.y01,H.x01),!k):(D.arc(V.cx,V.cy,z,n(V.y01,V.x01),n(V.y11,V.x11),!k),D.arc(0,0,m,n(V.cy+V.y11,V.cx+V.x11),n(H.cy+H.y11,H.cx+H.x11),k),D.arc(H.cx,H.cy,z,n(H.y11,H.x11),n(H.y01,H.x01),!k))):D.arc(0,0,m,N,M,k)}if(D.closePath(),e)return D=null,e+``||null}return k.centroid=function(){var e=(+s.apply(this,arguments)+ +x.apply(this,arguments))/2,t=(+w.apply(this,arguments)+ +T.apply(this,arguments))/2-i/2;return[u(t)*e,a(t)*e]},k.innerRadius=function(t){return arguments.length?(s=typeof t==`function`?t:e(+t),k):s},k.outerRadius=function(t){return arguments.length?(x=typeof t==`function`?t:e(+t),k):x},k.cornerRadius=function(t){return arguments.length?(S=typeof t==`function`?t:e(+t),k):S},k.padRadius=function(t){return arguments.length?(C=t==null?null:typeof t==`function`?t:e(+t),k):C},k.startAngle=function(t){return arguments.length?(w=typeof t==`function`?t:e(+t),k):w},k.endAngle=function(t){return arguments.length?(T=typeof t==`function`?t:e(+t),k):T},k.padAngle=function(t){return arguments.length?(E=typeof t==`function`?t:e(+t),k):E},k.context=function(e){return arguments.length?(D=e??null,k):D},k}export{x as t};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import"./chunk-NNHCCRGN-DlpIbxXb.js";import{x as e}from"./mermaid-parser.core-DkqLwTDu.js";export{e as createArchitectureServices};
|