@captain_z/zsk 1.0.1 → 1.1.0

package/templates/project-init/.zsk/schemas/module.schema.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zsk.dev/schemas/module.schema.json",
+  "title": "ZSK Module Config",
+  "description": "Module-level resource, runtime, test, and output mapping for ZSK workflows.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["module", "sources", "tests", "outputs"],
+  "properties": {
+    "module": {
+      "description": "Module identity.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name"],
+      "properties": {
+        "id": {
+          "description": "Stable module slug.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z0-9][a-z0-9-]*$"
+        },
+        "name": {
+          "description": "Human-readable module name.",
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "sources": {
+      "description": "Raw and derived resource inputs consumed by this module.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["testing"],
+      "properties": {
+        "srs": {
+          "$ref": "#/$defs/srsSource"
+        },
+        "api_contracts": {
+          "$ref": "#/$defs/pathList"
+        },
+        "testing": {
+          "$ref": "#/$defs/pathList"
+        },
+        "design_assets": {
+          "$ref": "#/$defs/pathList"
+        },
+        "figma": {
+          "$ref": "#/$defs/pathList"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "runtime": {
+      "description": "Optional runtime verification target.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["url"],
+      "properties": {
+        "url": {
+          "description": "Local or deployed URL used for runtime verification.",
+          "type": "string",
+          "minLength": 1
+        },
+        "tools": {
+          "description": "Preferred runtime verification tools.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/toolName"
+          },
+          "uniqueItems": true
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "tests": {
+      "description": "Test asset mapping and TDD policy for this module.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["raw_cases", "derived_cases", "automated", "tdd_required"],
+      "properties": {
+        "raw_cases": {
+          "$ref": "#/$defs/pathList"
+        },
+        "derived_cases": {
+          "$ref": "#/$defs/pathList"
+        },
+        "automated": {
+          "description": "Executable test locations grouped by test level.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["unit", "integration", "e2e"],
+          "properties": {
+            "unit": {
+              "$ref": "#/$defs/pathList"
+            },
+            "integration": {
+              "$ref": "#/$defs/pathList"
+            },
+            "e2e": {
+              "$ref": "#/$defs/pathList"
+            },
+            "metadata": {
+              "$ref": "#/$defs/metadata"
+            }
+          }
+        },
+        "tdd_required": {
+          "description": "Whether AI coding must create/update failing tests before implementation.",
+          "type": "boolean"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "outputs": {
+      "description": "Module output locations for docs and issues.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["docs", "issues"],
+      "properties": {
+        "docs": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "issues": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "metadata": {
+      "$ref": "#/$defs/metadata"
+    }
+  },
+  "$defs": {
+    "pathRef": {
+      "description": "Project-relative path unless the value is intentionally absolute.",
+      "type": "string",
+      "minLength": 1
+    },
+    "pathList": {
+      "description": "List of project-relative paths or glob-like path patterns.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/pathRef"
+      },
+      "uniqueItems": true
+    },
+    "srsSource": {
+      "description": "SRS source path with optional section anchors.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": {
+        "path": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "sections": {
+          "description": "Relevant SRS sections for this module.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "anchors": {
+          "description": "Stable raw-source anchors such as FR/AC IDs.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "toolName": {
+      "description": "Known runtime/design verification tool.",
+      "type": "string",
+      "enum": ["computer_use", "browser_use", "figma_mcp", "script", "manual", "skill"]
+    },
+    "metadata": {
+      "description": "Explicit extension point for project-specific metadata.",
+      "type": "object",
+      "additionalProperties": {
+        "type": ["string", "number", "integer", "boolean", "null"]
+      }
+    }
+  }
+}

package/templates/project-init/.zsk/schemas/zsk-config.schema.json

@@ -0,0 +1,246 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zsk.dev/schemas/zsk-config.schema.json",
+  "title": "ZSK Project Config",
+  "description": "Project-level configuration for ZSK resource discovery, workspace paths, tools, and module index locations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["project", "paths", "sources", "tools", "modules"],
+  "properties": {
+    "project": {
+      "description": "Project identity used in generated docs and resource manifests.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "description": "Stable project identifier.",
+          "type": "string",
+          "minLength": 1
+        },
+        "display_name": {
+          "description": "Human-readable project name.",
+          "type": "string",
+          "minLength": 1
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "paths": {
+      "description": "Top-level project knowledge workspace paths.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["raws", "docs", "issues"],
+      "properties": {
+        "raws": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "docs": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "issues": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "sources": {
+      "description": "Project-level raw resource entry points.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["srs", "figma_index", "api_contracts", "testing", "design_assets"],
+      "properties": {
+        "srs": {
+          "$ref": "#/$defs/sourceRef"
+        },
+        "figma_index": {
+          "$ref": "#/$defs/sourceRef"
+        },
+        "api_contracts": {
+          "$ref": "#/$defs/sourceRef"
+        },
+        "testing": {
+          "$ref": "#/$defs/sourceRef"
+        },
+        "design_assets": {
+          "$ref": "#/$defs/sourceRef"
+        },
+        "vendor_docs": {
+          "$ref": "#/$defs/sourceRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "tools": {
+      "description": "Preferred AI/tool capabilities for project-level workflows.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runtime_ui", "design"],
+      "properties": {
+        "runtime_ui": {
+          "description": "Preferred tools for runtime UI verification.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/toolName"
+          },
+          "uniqueItems": true
+        },
+        "design": {
+          "description": "Preferred tools for design and Figma resource capture.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/toolName"
+          },
+          "uniqueItems": true
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "modules": {
+      "description": "Module discovery and module config locations.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["index", "root"],
+      "properties": {
+        "index": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "root": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "sync": {
+      "description": "Optional deterministic or AI-assisted raw resource sync configuration.",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/syncRef"
+      }
+    },
+    "metadata": {
+      "$ref": "#/$defs/metadata"
+    }
+  },
+  "$defs": {
+    "pathRef": {
+      "description": "Project-relative path unless the value is intentionally absolute.",
+      "type": "string",
+      "minLength": 1
+    },
+    "toolName": {
+      "description": "Known tool or capability name.",
+      "type": "string",
+      "enum": ["computer_use", "browser_use", "figma_mcp", "script", "manual", "skill"]
+    },
+    "sourceRef": {
+      "description": "Resource source reference.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/localSource"
+        },
+        {
+          "$ref": "#/$defs/scriptSource"
+        },
+        {
+          "$ref": "#/$defs/skillSource"
+        }
+      ]
+    },
+    "localSource": {
+      "description": "Resource that already exists in the project workspace.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "kind": {
+          "description": "Local source kind.",
+          "type": "string",
+          "const": "local"
+        },
+        "path": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "scriptSource": {
+      "description": "Resource produced by a deterministic script command.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "command", "output"],
+      "properties": {
+        "kind": {
+          "description": "Script source kind.",
+          "type": "string",
+          "const": "script"
+        },
+        "command": {
+          "description": "Command that syncs this resource.",
+          "type": "string",
+          "minLength": 1
+        },
+        "output": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "skillSource": {
+      "description": "Resource produced by an AI skill or tool-assisted workflow.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "skill", "output"],
+      "properties": {
+        "kind": {
+          "description": "Skill source kind.",
+          "type": "string",
+          "const": "skill"
+        },
+        "skill": {
+          "description": "Skill used to obtain the resource.",
+          "type": "string",
+          "minLength": 1
+        },
+        "output": {
+          "$ref": "#/$defs/pathRef"
+        },
+        "metadata": {
+          "$ref": "#/$defs/metadata"
+        }
+      }
+    },
+    "syncRef": {
+      "description": "Optional sync entry for a resource provider.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/scriptSource"
+        },
+        {
+          "$ref": "#/$defs/skillSource"
+        }
+      ]
+    },
+    "metadata": {
+      "description": "Explicit extension point for project-specific metadata.",
+      "type": "object",
+      "additionalProperties": {
+        "type": ["string", "number", "integer", "boolean", "null"]
+      }
+    }
+  }
+}

package/templates/project-init/SYSTEM-SPEC.md

@@ -0,0 +1,55 @@
+# System Spec
+
+This file defines project-level behavior rules for humans and AI agents. Keep stable constraints here, and keep machine-readable paths in `zsk.config.yaml`.
+
+## Source Priority
+
+When sources conflict, use this priority order until the project overrides it:
+
+1. `SYSTEM-SPEC.md`
+2. `zsk.config.yaml`
+3. `.raws/SRS.md`
+4. `.raws/api-contracts/`
+5. `.raws/testing/`
+6. `.raws/design-assets/`
+7. `docs/{module}/spec.md`
+8. `docs/{module}/design.md`
+
+If two upstream raw sources conflict, do not silently choose one. Record the conflict in `.issues/{module}/BUG-xxxx-short-slug/issue.md`, then ask for confirmation before changing accepted specs or designs.
+
+## Directory Policy
+
+- `.raws/` stores upstream facts and source snapshots only.
+- `docs/` stores digested module knowledge, decisions, tasks, and verification.
+- `.issues/` stores defects, local verification evidence, screenshots, logs, and retest records.
+- Runtime screenshots, debug logs, HAR files, and failed verification artifacts must not be stored under `docs/`.
+
+## Testing Policy
+
+Test cases are first-class project assets.
+
+- Original QA, acceptance, release, and manually supplied test cases belong under `.raws/testing/`.
+- Module-derived test cases belong under `docs/{module}/`.
+- AI coding must be TDD-driven from `.raws/testing` and module-derived test cases.
+- A task is not done until the relevant test case is covered by automated tests or recorded as runtime/manual verification evidence.
+
+## Documentation Feedback Policy
+
+Every project stage must feed confirmed conversation outcomes back into durable files.
+
+Required stage record:
+
+```md
+## Documentation Feedback
+
+- Conversation decisions captured:
+  - {decision or "None"}
+- Durable files updated:
+  - `{path}`: {what changed and why}
+- Source links:
+  - `{path or issue}`: {source role}
+- No-update rationale:
+  - {required when no file changed}
+```
+
+A stage is not complete until its documentation feedback check is complete.

package/templates/project-init/docs/_module-index.md

@@ -0,0 +1,7 @@
+# Module Index
+
+This file is maintained by `zsk prep` and AI-assisted module discovery.
+
+| Module | Name | Config | Status |
+| --- | --- | --- | --- |
+| `<module-id>` | `<module-name>` | `docs/<module-id>/module.yaml` | pending |

package/templates/project-init/docs/_module-template/module.yaml

@@ -0,0 +1,32 @@
+# yaml-language-server: $schema=../../.zsk/schemas/module.schema.json
+
+module:
+  id: example-module
+  name: Example Module
+
+sources:
+  srs:
+    path: .raws/SRS.md
+    sections: []
+  api_contracts: []
+  testing: []
+  design_assets: []
+
+runtime:
+  url: http://localhost:3000
+  tools:
+    - computer_use
+    - browser_use
+
+tests:
+  raw_cases: []
+  derived_cases: []
+  automated:
+    unit: []
+    integration: []
+    e2e: []
+  tdd_required: true
+
+outputs:
+  docs: docs/example-module
+  issues: .issues/example-module

package/templates/project-init/docs/system/README.md

@@ -0,0 +1,12 @@
+# System Docs
+
+Use this directory for project-wide architecture, ADRs, glossary, and non-functional requirements.
+
+Recommended files:
+
+- `architecture.md`
+- `glossary.md`
+- `nfr-baseline.md`
+- `adrs/ADR-0001-title.md`
+
+Keep project-wide rules in `SYSTEM-SPEC.md`; keep module-specific behavior under `docs/{module}/`.

package/templates/project-init/zsk.config.yaml

@@ -0,0 +1,50 @@
+# yaml-language-server: $schema=.zsk/schemas/zsk-config.schema.json
+
+project:
+  name: "<project-name>"
+
+paths:
+  raws: .raws
+  docs: docs
+  issues: .issues
+
+sources:
+  srs:
+    kind: local
+    path: .raws/SRS.md
+  figma_index:
+    kind: local
+    path: .raws/FIGMA-INDEX.md
+  api_contracts:
+    kind: local
+    path: .raws/api-contracts
+  testing:
+    kind: local
+    path: .raws/testing
+  design_assets:
+    kind: local
+    path: .raws/design-assets
+
+# Optional resource sync definitions.
+# Use kind: script for deterministic fetch/generate commands, or kind: skill
+# when an AI skill/tool must collect the resource (for example Figma MCP).
+# sync:
+#   figma_snapshot:
+#     kind: skill
+#     skill: zsk:ue-mcp
+#     output: .raws/design-assets/<module>/<snapshot>
+#   api_contracts:
+#     kind: script
+#     command: pnpm sync:api-contracts
+#     output: .raws/api-contracts
+
+tools:
+  runtime_ui:
+    - computer_use
+    - browser_use
+  design:
+    - figma_mcp
+
+modules:
+  index: docs/_module-index.md
+  root: docs