@xenonbyte/xsk 0.1.0 → 0.1.1

package/templates/fragments/point.output.md

@@ -0,0 +1 @@
+The path of the point document and its current `status`: active points (`researching`, `ready`) are at `.xsk/points/<slug>.md`; dropped points are at `.xsk/points/archive/<slug>.md`.

package/templates/fragments/point.purpose.md

@@ -0,0 +1,3 @@
+Research one aspect of the current project to a decision-complete landed plan and persist it as a point document in `.xsk/points/`. The result is a concrete, slug-named file an implementer can consume without re-doing the research.
+
+It is research-and-persist only. It writes no code, no scaffolding, and no requirement document.

package/templates/fragments/point.triggers.md

@@ -0,0 +1,6 @@
+Match the intent, not the exact words. Common cues:
+
+- "研究一下", "调研一下", "先搞清楚", "这块需要研究"
+- "spike this", "research this", "figure out the approach for", "investigate"
+- any request to explore and nail down one aspect before writing a requirement or starting implementation
+- a slug argument that names an existing point (triggers a refinement of that point, not a new one)

package/templates/fragments/skill-scaffold.behavior.md

@@ -13,11 +13,14 @@
 - Unknown options fail loud.
 - `status` validates manifest **shape**, not just parse success.
 - Removed or renamed commands leave no stale references (grep-clean across CLI, help, README, generated text, `AGENTS.md`, `CLAUDE.md`).
-- Four platforms, all full: Claude Code, Codex, opencode, Gemini.
-- Manifest-backed install safety: owned-only removal, ownership markers, atomic writes, symlink refusal.
+- Four platforms covered: Claude Code, Codex, opencode, Gemini.
+- User-invocable on every platform, not merely present. Installing a skill must make it invocable on each target platform. Platforms that do not auto-expose skill files as slash commands need a verified platform-specific invocation artifact carrying the skill body and the platform's argument placeholder so invocation arguments are not dropped. This project currently implements that artifact for opencode as a command file; do not claim it for another platform until adapter, install, uninstall, status, docs, and tests all cover that platform. Claude exposes skill files directly. Verify per platform rather than assuming.
+- Manifest-backed install safety: owned-only removal, ownership markers, atomic writes, symlink refusal, and content-hash modification detection. The manifest records a hash per owned file; a previously generated install is recognized by that hash even without the marker (markerless detection), so a user-edited owned file is detected and refused or rolled back rather than silently overwritten.
 - `install` is uninstall-first: a reinstall resets the previously-owned files (pruning skills no longer installed) before regenerating, so no manual `uninstall` is needed. It still refuses to overwrite a user-edited owned file and rolls back instead of destroying it.
+- Built from source: skills are generated from a single per-skill source, not hand-maintained per platform or per file. The reference composes each skill from per-section fragments (`purpose`, `triggers`, `behavior`, `output`) plus a shared common body and a template, with one registry listing the skills. The build is deterministic, and the committed packed skill output stays byte-for-byte in sync with the generator, enforced by a test. The golden snapshot below is the masked form of that output.
 - A golden snapshot of the generated skill shell, masking embedded `shared/` body.
 - A bilingual README (`README.md` plus `README.zh-CN.md`) with identical headings, English literals preserved, and content-pinning tests.
+- Test coverage spans the install surface, not only generation and docs: install, uninstall, uninstall-first reset, transactional rollback, and the safety refusals (a user-edited owned file, symlinked paths) are exercised by executable tests, alongside the golden snapshot, README parity, and self-conformance tests.
 
 ### Self-conformance
 

package/templates/fragments/write-req.behavior.md

@@ -1,15 +1,16 @@
 **1. Read the project first.** `grep` and `read` the current project structure, config files (`package.json` and the like), and relevant code to ground the requirement in reality. Never quote defaults from memory.
 
-**2. Locate or create the active requirement doc.** Scan `requirements/*.md` for frontmatter `status: active`. There is **at most one** active doc at a time. If more than one exists, stop, list the offending paths, and report the broken invariant for the user to resolve. If one exists, lock onto it and append or refine. If none exists, create `requirements/<slug>.md` with `status: active` and a slug generated from the need.
+**2. Locate or create the active requirement doc.** Scan `.xsk/requirements/*.md` for frontmatter `status: active`. There is **at most one** active doc at a time. If more than one exists, stop, list the offending paths, and report the broken invariant for the user to resolve. If one exists, lock onto it and append or refine. If none exists, create `.xsk/requirements/<slug>.md` with `status: active` and a slug generated from the need.
 
-**3. Ensure the directory convention.** Auto-create `requirements/.gitignore` containing `archive/` if it is absent (creating `requirements/` and `requirements/archive/` as needed). Never overwrite an existing `.gitignore`; append `archive/` only if the line is missing.
+**3. Ensure the directory convention.** Ensure `.xsk/.gitignore` contains the line `requirements/archive/` (create `.xsk/` and `.xsk/.gitignore` if absent; append only if the line is missing; never overwrite an existing `.xsk/.gitignore`).
 
 **4. Convert fuzzy into concrete.** Match the document structure to the input richness:
 
 - A minimal one-liner becomes a concise requirement: Goal, Scope, Acceptance. Do not force a Background section that would be filler.
 - Richer input becomes Background, Goal, Scope (in and out), Requirements, Open Questions, Checkpoints.
+- Open Questions holds only non-blocking items, and each one names its disposition: escalate it to the user to decide (step 5), or defer it to a named owner at a named checkpoint. A choice that would fork the implementation is never parked here. Resolve it inline, or raise it as a decision point.
 
-**5. Decision points go to the user.** When a genuine technical or scoping choice would change the implementation, stop and ask the user to decide. Surface the options and the tradeoffs; let them pick. Do not pick silently.
+**5. Decision points go to the user, resolved one at a time.** When a genuine technical or scoping choice would change the implementation, stop and ask the user to decide: surface the options and the tradeoffs, let them pick, do not pick silently. When several genuine decisions exist, take them in dependency order rather than all at once. Surface the most upstream open one first, fold the answer in, then re-derive what remains before surfacing the next. A resolved decision often removes or reshapes the forks beneath it, so never surface a fork whose options still depend on an open decision.
 
 **6. Brainstorm the genuinely open-ended.** Where the need is open-ended, run a short exploration with the user before writing.
 
@@ -19,8 +20,9 @@
 
 - **Conflict check:** verify no internal contradictions (Goal versus Scope, in-scope versus out-of-scope, Requirements versus Open Questions, any two statements that cannot both hold). Resolve every conflict, or surface it to the user. A finalized doc contains zero conflicts.
 - **Ambiguity check:** verify no undefined terms, unstated assumptions, or vague qualifiers ("fast", "supported", "as needed") that would force the implementer to guess. Tighten each to a concrete, testable statement. A finalized doc leaves no ambiguity that blocks implementation.
+- **Open-questions check:** verify every Open Question is non-blocking and names a disposition (escalated to the user, or deferred to a named owner at a named checkpoint). Resolve or raise anything that would block or fork implementation before finalizing. A finalized doc parks no blocking or unowned question.
 - **Checkpoint gates:** ensure the requirement defines the verification points where downstream implementation must pause and confirm against the requirement (acceptance criteria, integration gates, review gates). If it lacks them, add them before finalizing.
-- If the audit surfaces issues only the user can resolve, stop, list them, and ask. Do not write a contradictory or under-specified doc.
+The audit is a loop, not a single pass. If it surfaces issues only the user can resolve, take them one at a time in dependency order (as in step 5), then re-run the checks before finalizing. Repeat until one full pass finds zero conflicts, zero blocking ambiguity, and nothing left for the user to resolve. Do not write a contradictory or under-specified doc.
 
 The document frontmatter:
 

package/templates/fragments/write-req.purpose.md

@@ -1 +1 @@
-Convert plain-language ("白话") needs into a compliant requirement document in `requirements/`, grounded in the current project's actual code. The output is a doc an implementer can act on without guessing, not a transcript of the request.
+Convert plain-language ("白话") needs into a compliant requirement document in `.xsk/requirements/`, grounded in the current project's actual code. The output is a doc an implementer can act on without guessing, not a transcript of the request.