@stcrft/statecraft 1.1.3 → 1.3.0

package/renderer-dist/assets/index-d6soJrAs.css

@@ -0,0 +1 @@
+*,*:before,*:after{box-sizing:border-box}html{font-size:16px}body{margin:0;font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-size:1rem;line-height:1.5;color:#1a1a1a;-webkit-font-smoothing:antialiased}html[data-theme=dark] body{background:#111827;color:#f9fafb}#root{min-height:100vh}:root{--color-primary: #3366ff;--color-secondary: #33cccc;--color-tertiary: #ff6633;--color-structure: #404040;--color-background: #f5f5f5;--color-surface: #ffffff;--color-text: #1a1a1a;--color-text-muted: #666666;--space-1: .25rem;--space-2: .5rem;--space-3: .75rem;--space-4: 1rem;--space-5: 1.25rem;--space-6: 1.5rem;--radius-sm: 4px;--radius-md: 6px;--radius-lg: 8px;--font-heading: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;--text-xs: .75rem;--text-sm: .875rem;--text-base: 1rem;--text-lg: 1.125rem;--text-xl: 1.5rem}[data-theme=dark]{--color-structure: #6b7280;--color-background: #111827;--color-surface: #1f2937;--color-text: #f9fafb;--color-text-muted: #9ca3af}[data-theme=dark] .errors{background:#450a0a;border-color:#7f1d1d;color:#fecaca}.app{display:flex;flex-direction:column;min-height:100vh;background:var(--color-background);color:var(--color-text)}.header{flex-shrink:0;display:flex;align-items:center;gap:var(--space-3);padding:var(--space-3) var(--space-4);background:var(--color-surface);border-bottom:2px solid var(--color-structure)}.header__logo{height:2rem;width:auto;display:block}[data-theme=dark] .header__logo{filter:invert(1)}.header__title{margin:0;font-family:var(--font-heading);font-size:var(--text-lg);font-weight:600;color:var(--color-structure);line-height:1.3}.header__theme-toggle{margin-left:auto;padding:var(--space-2) var(--space-3);font-size:1.25rem;line-height:1;background:var(--color-background);border:1px solid var(--color-structure);border-radius:var(--radius-md);cursor:pointer;transition:background .15s ease,border-color .15s ease}.header__theme-toggle:hover{background:var(--color-structure);border-color:var(--color-text-muted)}.header__theme-icon{display:block;color:var(--color-text)}.main{flex:1;padding:var(--space-4);overflow:auto}.theme-sample{max-width:40rem;margin:0 auto;padding:1rem;background:var(--color-surface);border:1px solid var(--color-structure);border-radius:8px}.theme-sample__title{margin:0 0 .75rem;font-size:1rem;color:var(--color-text-muted)}.theme-sample__strip{display:flex;flex-wrap:wrap;gap:.5rem}.theme-sample__swatch{width:4rem;height:2.5rem;border-radius:4px;border:1px solid var(--color-structure)}.theme-sample__swatch--primary{background:var(--color-primary)}.theme-sample__swatch--secondary{background:var(--color-secondary)}.theme-sample__swatch--tertiary{background:var(--color-tertiary)}.theme-sample__swatch--structure{background:var(--color-structure)}.theme-sample__hint{margin:1rem 0 0;font-size:.875rem;color:var(--color-text-muted)}.errors{margin-bottom:var(--space-4);padding:var(--space-4);background:#fef2f2;border:1px solid #fecaca;border-radius:var(--radius-lg);color:#991b1b}.errors__title{margin:0 0 var(--space-2);font-size:var(--text-sm);font-weight:600}.errors__list{margin:0;padding-left:1.25rem;font-size:var(--text-sm)}.errors__item{margin-bottom:var(--space-1)}.load-board{max-width:40rem;margin:0 auto;padding:var(--space-4);background:var(--color-surface);border:1px solid var(--color-structure);border-radius:var(--radius-lg)}.load-board__title{margin:0 0 var(--space-3);font-size:var(--text-lg);font-weight:600;color:var(--color-text)}.load-board__hint{margin:0 0 var(--space-4);font-size:var(--text-sm);color:var(--color-text-muted);line-height:1.5}.load-board__hint code{background:var(--color-background);padding:var(--space-1) var(--space-2);border-radius:var(--radius-sm);font-size:var(--text-xs)}.load-board__actions{display:flex;flex-wrap:wrap;gap:var(--space-3);margin-bottom:var(--space-4)}.load-board__btn,.load-board__file-text{display:inline-block;padding:var(--space-2) var(--space-4);font-size:var(--text-sm);font-weight:500;color:var(--color-surface);background:var(--color-primary);border:none;border-radius:var(--radius-md);cursor:pointer;min-height:44px;line-height:1.25;touch-action:manipulation}.load-board__btn:hover:not(:disabled){filter:brightness(1.1)}.load-board__btn:disabled{opacity:.7;cursor:not-allowed}.load-board__file-label{cursor:pointer}.load-board__file-input{position:absolute;width:0;height:0;opacity:0}.load-board__file-text{background:var(--color-secondary)}.load-board__paste-label{display:block}.load-board__paste-caption{display:block;margin-bottom:var(--space-2);font-size:var(--text-sm);color:var(--color-text-muted)}.load-board__paste-input{width:100%;padding:var(--space-3);font-family:ui-monospace,monospace;font-size:var(--text-xs);line-height:1.5;border:1px solid var(--color-structure);border-radius:var(--radius-md);background:var(--color-surface);color:var(--color-text);resize:vertical;min-height:44px}.board{width:100%}.board__name{margin:0 0 var(--space-4);font-family:var(--font-heading);font-size:var(--text-xl);font-weight:600;color:var(--color-structure);line-height:1.3}.board__lanes{display:flex;gap:var(--space-4);overflow-x:auto;padding-bottom:var(--space-2);min-height:12.5rem;-webkit-overflow-scrolling:touch}.lane{flex:0 0 min(20rem,100%);display:flex;flex-direction:column;background:var(--color-surface);border:1px solid var(--color-structure);border-radius:var(--radius-lg);border-top:3px solid var(--lane-accent, var(--color-primary));min-width:0;box-shadow:0 1px 3px #0000000f}.lane__header{display:flex;align-items:center;justify-content:space-between;gap:var(--space-2);padding:var(--space-3) var(--space-4);border-bottom:1px solid var(--color-structure);flex-shrink:0}.lane__name{font-family:var(--font-heading);font-weight:600;font-size:var(--text-base);color:var(--color-text)}.lane__count{font-size:var(--text-sm);color:var(--color-text-muted)}.lane__count--at-limit{color:var(--color-tertiary);font-weight:500}.lane__cards{flex:1;padding:var(--space-2);overflow-y:auto;display:flex;flex-direction:column;gap:var(--space-2)}.card{padding:var(--space-3) var(--space-4);background:var(--color-surface);border:1px solid var(--color-structure);border-radius:var(--radius-md);border-left:4px solid var(--lane-accent, var(--color-structure));border-top:3px solid var(--lane-accent, var(--color-structure));opacity:1;transform:scale(1);transition:opacity .25s ease,transform .25s ease,box-shadow .25s ease;box-shadow:0 1px 2px #0000000a}.card--moving{opacity:0;transform:scale(.96);box-shadow:0 4px 12px #0000001f}.card--clickable{cursor:pointer}.card--clickable:hover{box-shadow:0 2px 8px #00000014}.card__id{font-size:var(--text-xs);color:var(--color-text-muted);margin-bottom:var(--space-1)}.card__title{margin:0 0 var(--space-1);font-size:var(--text-sm);font-weight:600;line-height:1.3;color:var(--color-text)}.card__description{margin:var(--space-2) 0 0;font-size:var(--text-xs);color:var(--color-text-muted);line-height:1.4}.card__meta{margin-top:var(--space-2);font-size:var(--text-xs);color:var(--color-text-muted);display:flex;gap:var(--space-3);flex-wrap:wrap}.card__deps{margin-top:var(--space-2);font-size:var(--text-xs);color:var(--color-text-muted)}@media(max-width:768px){.main{padding:var(--space-3)}.board__name{font-size:var(--text-lg);margin-bottom:var(--space-3)}.board__lanes{gap:var(--space-3);min-height:10rem}.lane{flex:0 0 min(18rem,100%)}.lane__header{padding:var(--space-3)}.card{padding:var(--space-3);min-height:44px}}.modal-overlay{position:fixed;top:0;right:0;bottom:0;left:0;background:#00000080;display:flex;align-items:center;justify-content:center;z-index:1000;padding:var(--space-4)}.modal{background:var(--color-surface);border:1px solid var(--color-structure);border-radius:var(--radius-lg);box-shadow:0 8px 32px #0003;max-width:min(72rem,92vw);max-height:90vh;width:min(72rem,92vw);display:flex;flex-direction:column;min-width:0}.modal__header{display:flex;align-items:flex-start;justify-content:space-between;gap:var(--space-3);padding:var(--space-4);border-bottom:1px solid var(--color-structure);border-top:3px solid var(--color-structure);flex-shrink:0}.modal__header-inner{display:flex;align-items:flex-start;gap:var(--space-3);flex-wrap:wrap;min-width:0}.modal__title{margin:0;font-size:var(--text-lg);font-weight:600;line-height:1.3;color:var(--color-text)}.modal__id{display:block;font-size:var(--text-xs);font-weight:500;color:var(--color-text-muted);margin-bottom:var(--space-1)}.modal__status{flex-shrink:0;padding:var(--space-1) var(--space-2);font-size:var(--text-xs);font-weight:500;color:var(--color-surface);border-radius:var(--radius-sm);white-space:nowrap}.modal__close{flex-shrink:0;width:2rem;height:2rem;padding:0;font-size:1.5rem;line-height:1;border:none;background:transparent;color:var(--color-text-muted);cursor:pointer;border-radius:var(--radius-sm)}.modal__close:hover{color:var(--color-text);background:var(--color-background)}.modal__body{padding:var(--space-4);overflow-y:auto;overflow-x:hidden;flex:1;min-height:0;min-width:0}.modal__section-title{margin:0 0 var(--space-2);font-size:var(--text-sm);font-weight:600;color:var(--color-text)}.modal__description-section{margin-bottom:var(--space-4)}.modal__description-section:last-child{margin-bottom:0}.modal__description{margin:0 0 var(--space-3);font-size:var(--text-sm);line-height:1.5;color:var(--color-text)}.modal__meta{margin-bottom:var(--space-3);font-size:var(--text-sm);color:var(--color-text-muted);display:flex;gap:var(--space-3)}.modal__deps{margin:0 0 var(--space-3);font-size:var(--text-sm);color:var(--color-text-muted)}.modal__spec{margin-top:var(--space-4);padding-top:0}.modal__spec--with-separator{padding-top:var(--space-3);border-top:1px solid var(--color-structure)}.modal__spec-title{margin:0 0 var(--space-2);font-size:var(--text-sm);font-weight:600;color:var(--color-text)}.modal__spec-loading,.modal__spec-error{margin:0;font-size:var(--text-sm);color:var(--color-text-muted)}.modal__spec-error{color:var(--color-tertiary)}.modal__spec-content{margin:0;padding:var(--space-3);font-size:var(--text-sm);line-height:1.6;background:var(--color-background);border:1px solid var(--color-structure);border-radius:var(--radius-md);max-height:24rem;overflow-y:auto;overflow-wrap:break-word;word-break:break-word;min-width:0}.modal__spec-content h1,.modal__spec-content h2,.modal__spec-content h3{margin:var(--space-3) 0 var(--space-2);font-weight:600;color:var(--color-text);line-height:1.3}.modal__spec-content h1{font-size:var(--text-lg)}.modal__spec-content h2{font-size:var(--text-base)}.modal__spec-content h3{font-size:var(--text-sm)}.modal__spec-content h1:first-child,.modal__spec-content h2:first-child,.modal__spec-content h3:first-child{margin-top:0}.modal__spec-content p{margin:0 0 var(--space-2);color:var(--color-text)}.modal__spec-content ul,.modal__spec-content ol{margin:0 0 var(--space-2);padding-left:1.25rem}.modal__spec-content li{margin-bottom:var(--space-1)}.modal__spec-content code{font-family:ui-monospace,monospace;font-size:.9em;padding:.1em .3em;background:var(--color-surface);border:1px solid var(--color-structure);border-radius:var(--radius-sm);white-space:normal;word-break:break-word;overflow-wrap:break-word}.modal__spec-content pre{margin:0 0 var(--space-2);padding:var(--space-3);overflow-x:auto;background:var(--color-surface);border:1px solid var(--color-structure);border-radius:var(--radius-md);font-size:var(--text-xs);min-width:0}.modal__spec-content pre code{padding:0;background:none;border:none}.modal__spec-content blockquote{margin:0 0 var(--space-2);padding-left:var(--space-3);border-left:3px solid var(--color-structure);color:var(--color-text-muted)}.modal__spec-content table{width:100%;border-collapse:collapse;margin-bottom:var(--space-2);font-size:var(--text-xs)}.modal__spec-content th,.modal__spec-content td{padding:var(--space-2) var(--space-3);border:1px solid var(--color-structure);text-align:left}.modal__spec-content th{font-weight:600;background:var(--color-surface)}.modal__spec-content a{color:var(--color-primary);text-decoration:none}.modal__spec-content a:hover{text-decoration:underline}

package/renderer-dist/index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="/logo.png" type="image/png" />
+    <title>Statecraft — Board</title>
+    <script>
+      (function () {
+        var s = localStorage.getItem("statecraft-theme");
+        if (s === "light" || s === "dark") {
+          document.documentElement.setAttribute("data-theme", s);
+        } else if (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) {
+          document.documentElement.setAttribute("data-theme", "dark");
+        }
+      })();
+    </script>
+    <script type="module" crossorigin src="/assets/index-BlQ7Y9tG.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-d6soJrAs.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/spec.md

@@ -32,9 +32,9 @@ This document defines the Statecraft board format. A single file describes one K
 
 | Column         | Meaning for AI |
 |----------------|----------------|
-| **Backlog**    | Not yet selected for immediate work. New tasks are created here. May be unrefined or unprioritized. |
-| **Ready**      | Prepared and selected to be worked on next. Definition is clear (e.g. in spec file), dependencies met or N/A; safe to move to In Progress when capacity is free. |
-| **In Progress** | Currently being worked on. Move a task here when starting work; at most one (or a configurable WIP limit) at a time per column if enforced. |
+| **Backlog**    | Initial or vague task. New tasks are created here. May be unrefined—title and minimal spec are enough. After discovery/planning, the agent updates the task spec (description, acceptance criteria) and moves the task to Ready. |
+| **Ready**      | Task is refined: definition is clear, spec file has description and acceptance criteria, and the agent (or human) knows how to solve it. Ready to be worked on. Move here **after** discovery; move to In Progress **only when** starting the actual work. |
+| **In Progress** | Currently being worked on (e.g. code, fix, implementation). Move a task here only when actively doing the work—not when still planning. At most one (or a configurable WIP limit) at a time per column if enforced. |
 | **Done**       | Completed and accepted. Move here when the task’s acceptance criteria (in its spec file) are satisfied. |
 
 - **Order:** `Backlog` → `Ready` → `In Progress` → `Done` (left to right).
@@ -72,7 +72,7 @@ Statecraft is built around **CRUS** (Create, Read, Update, Summarize). AI agents
 
 - **Where:** New tasks are created with `status: Backlog`.
 - **What:** Add an entry under `tasks` with at least `title` and `status`. Use a stable, kebab-case **task id** (e.g. `fix-auth-timeout`). Optionally set `description`, `spec` (path to a `.md` file relative to the board directory), `owner`, `priority`, `depends_on`.
-- **Spec file:** If the task has acceptance criteria or context, create a markdown file (e.g. `tasks/<task-id>.md`) and set `spec: tasks/<task-id>.md`. Path is relative to the board file’s directory.
+- **Spec file:** If the task has acceptance criteria or context, create a markdown file (e.g. `tasks/<task-id>.md`) and set `spec: tasks/<task-id>.md`. Path is relative to the board file’s directory. See **Task spec file format** below for recommended structure.
 
 ### Read
 
@@ -82,9 +82,11 @@ Statecraft is built around **CRUS** (Create, Read, Update, Summarize). AI agents
 
 ### Update
 
-- **How:** Edit the board YAML file (and, if needed, task spec files) directly. There are no separate “move” APIs; changing `status` is the update.
-- **Prepare for work:** When a task has a clear definition and dependencies are satisfied (or N/A), set `status` to `Ready`. Do not move to In Progress until the task is Ready (or skip Ready if the workflow is minimal).
-- **Start work:** Set the task’s `status` to `In Progress`. Optionally read the task’s `spec` file first.
+- **How:** Edit the board YAML file (and, if needed, task spec files) directly. There are no separate "move" APIs; changing `status` is the update.
+- **Flow:** Backlog → Ready → In Progress → Done. Do not skip Ready.
+- **Create (Backlog):** New tasks start in Backlog. They may be vague; add at least `title` and `status`, and create the spec file if required.
+- **Refine and move to Ready:** After discovery or planning, update the task’s spec file (description, acceptance criteria). When the definition is clear and you know how to solve it, set `status` to **Ready**. Ready means "ready to be worked on."
+- **Start work:** Only when you are about to do the actual work (code, fix, implementation), set the task’s `status` to **In Progress**. Do not move to In Progress while still in discovery or planning. Read the task’s `spec` file if needed.
 - **Finish work:** Set the task’s `status` to `Done` only when the task’s acceptance criteria (in its spec file, if present) are satisfied. Do not move to Done without meeting the definition of done.
 - **Create / change fields:** Add or edit `title`, `status`, `description`, `spec`, `owner`, `priority`, `depends_on` in the board file; create or edit the spec file when the task has one.
 
@@ -92,6 +94,25 @@ Statecraft is built around **CRUS** (Create, Read, Update, Summarize). AI agents
 
 - Completion is represented by moving tasks to **Done**, not by deleting them. Use `statecraft summarize` (or equivalent) to produce a short summary of the board (counts, task list, WIP, blocked). Summarize replaces “delete”: tasks are completed and reasoned about, not removed.
 
+
+## Task spec file format (best practices)
+
+Task spec files (e.g. `tasks/<task-id>.md`) are markdown files referenced by a task's `spec` field. Following a consistent structure keeps specs machine-friendly and clear for both AI and humans.
+
+**Recommended structure:**
+
+| Section | Purpose |
+|--------|---------|
+| **Title** | First line or `# <Task title>` — match or expand the board `title`. |
+| **Description** | Optional `## Description` with short context or problem statement. |
+| **Acceptance criteria / Definition of Done** | `## Acceptance criteria` or `## Definition of Done` with a checklist (e.g. `- [ ] item`). All items must be checked before moving the task to Done. |
+| **Notes / Dependencies** | Optional `## Notes`, `## Dependencies` for human context; `depends_on` in the board is the source of truth for ordering. |
+
+- Use one file per task; put the task id in the filename (e.g. `fix-auth-timeout.md`).
+- Path is relative to the board file's directory.
+
+Init can optionally add these guidelines to generated AI rules (Cursor, Claude Code, Codex) so agents follow the same format.
+
 ---
 
 ## Example
@@ -153,7 +174,7 @@ These constraints are the basis for parser/validator implementations; this spec
 
 ## Setup and AI workflow
 
-**Creating a board:** Use **`statecraft init`** to create a board file and optionally connect Statecraft to your AI workflow. Init creates a board with the **canonical columns** (Backlog, Ready, In Progress, Done) and prompts for: board name, optional WIP limit for In Progress, board file path, directory for task `.md` files (relative to the board), and whether to generate rules for **Cursor**, **Claude Code**, and/or **Codex**. It writes valid board YAML and, if you choose, tool-specific rule files so your AI assistant knows where the board is and how to follow CRUS.
+**Creating a board:** Use **`statecraft init`** to create a board file and optionally connect Statecraft to your AI workflow. Init creates a board with the **canonical columns** (Backlog, Ready, In Progress, Done) and prompts for: board name, optional WIP limit for In Progress, board file path, directory for task `.md` files (relative to the board), **workflow options** (enforce “create task before any work”, require each task to have a spec `.md` file, include task spec format guidelines in rules — all default to yes), and whether to generate rules for **Cursor**, **Claude Code**, and/or **Codex**. It writes valid board YAML and, if you choose, tool-specific rule files so your AI assistant knows where the board is and how to follow CRUS.
 
 **Generated rule files:**