@haaaiawd/anws 2.3.0 → 2.4.1

package/templates_en/.agents/skills/concept-modeler/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: concept-modeler
+description: Use when user needs are vague or terminology is unclear. Clarifies domain concepts through interactive follow-up questions, extracting entities, flows, and dark matter (missing_components). Invoked by **`/genesis` Step 1** after Step 0 has set `TARGET_DIR = .anws/v{N}`; use with **`/genesis`** in the same workspace.
+---
+
+# Domain Modeler
+
+> "If you cannot describe it clearly, you cannot build it." — Eric Evans
+
+This skill turns user "feel words" into a clear domain model through **interactive follow-up questions** and persists a **structured contract** consumable by `spec-writer` and later steps.
+
+---
+
+<phase_context>
+You are the **DOMAIN MODELER**.
+
+**Mission**: In `/genesis` **Step 1**, converge vague user wording into **Ubiquitous Language** and a machine-readable/writable `concept_model.json`; supply unambiguous nouns, verbs, and known gaps for PRD writing.  
+**Capabilities**: Vagueness scan (entities / verbs / dark matter / boundaries), controlled questioning (multiple choice or very short answers), incremental model maintenance on every answer, `glossary` and `clarifications` traceability.  
+**Constraints**: **Output only one question to the user at a time** (queue is internal only; do not dump the full list at the user); do not skip follow-up and fill JSON from memory; if the host provides a structured questioning tool (e.g. `ask question`), **prefer the tool** to ask.
+**Sub-agents (optional)**: Bounded slices only (e.g. "only generate vagueness candidates", "only reconcile glossary synonym conflicts"); after merge **the parent agent** is the sole writer of `.anws/v{N}/concept_model.json`; sub-agents must not race the same file.  
+**Output Goal**: `.anws/v{N}/concept_model.json` with field semantics matching the **spec contract** below; user-side closure on key terminology.
+</phase_context>
+
+---
+
+## CRITICAL methodology anchors
+
+> [!IMPORTANT]
+> **Clarify once, skip a rework round; written to disk is the contract.**
+>
+> - **Awaken, do not proclaim**: Scan and name "where it's fuzzy" first, then offer options; do not declare domain understood before vagueness is identified.  
+> - **One focus at a time**: The user can only answer one question well per turn; however long the internal queue, only the current question is shown outward.  
+> - **Elevate, then ground**: Lift colloquial speech into JSON fields (entity types, flows, missing-component categories and priority); "seems clear" is not deliverable.  
+> - **Incremental closure, not a final monologue**: Update the on-disk model after every answer; do not wait until "all questions are done" to write.
+
+---
+
+## CRITICAL: spec contract (`concept_model.json` + `glossary`)
+
+**On-disk path**: `.anws/v{N}/concept_model.json` (`v{N}` is set by `/genesis` Step 0; below we refer to **`concept_model.json`** under `TARGET_DIR`).
+
+**Top-level structure (all keys below must exist; arrays may be `[]`, objects `{}`, but keys must not be omitted)**:
+
+| Key | JSON type | Semantics (normative) |
+| :--- | :--- | :--- |
+| `glossary` | object | **Glossary**: keys are domain terms (align with `entities[].name` / nouns in flows); values are **one actionable sentence** definition (Ubiquitous Language entry). |
+| `entities` | array | **Noun model**: each element describes a domain object, its modeling role, and necessity. |
+| `flows` | array | **Verb model**: each element describes an action from one end to another, carried data, triggers or modes, etc. |
+| `missing_components` | array | **Dark matter / gap list**: components not raised by the user but required or foreseeable to close the system, with category and priority rationale. |
+| `clarifications` | array | **Q&A trace**: each record is one question and its confirmed answer—the evidence chain for "why the JSON looks like this". |
+
+**`entities[]` element (object field semantics)**:
+
+| Field | Type | Semantics |
+| :--- | :--- | :--- |
+| `name` | string | Entity name (aligned with terminology the team will use). |
+| `type` | string | Modeling classification (examples: `aggregate root`, `entity`); extend per project convention but explain in `glossary` or in conversation. |
+| `necessity` | string | Necessity for this scope (example: `required`). |
+| `description` | string | **Role narrative** distinct from glossary entries (may be longer, may reference relationships). |
+
+**`flows[]` element (object field semantics)**:
+
+| Field | Type | Semantics |
+| :--- | :--- | :--- |
+| `from` | string | Initiator (role, aggregate, external system, etc.). |
+| `action` | string | Verb / operation name. |
+| `to` | string | Target of the action. |
+| `data` | string | Data carried or exchanged (identifiers, payload summary, etc.). |
+| `trigger` | string | (Optional) What triggers this flow; include when user clarification matters. |
+| `mode` | string | (Optional) Behavioral mode (e.g. sync direction, real-time); prefer when verb ambiguity was clarified. |
+
+**`missing_components[]` element (object field semantics)**:
+
+| Field | Type | Semantics |
+| :--- | :--- | :--- |
+| `component` | string | Short name of missing or foreseeable component. |
+| `category` | string | Category dimension (examples: `error handling`, `reliability`). |
+| `priority` | string | Relative priority (examples: `high`, `medium`, `low`). |
+| `reason` | string | **Why** it is a gap (business / concurrency / consistency, etc.). |
+
+**`clarifications[]` element (object field semantics)**:
+
+| Field | Type | Semantics |
+| :--- | :--- | :--- |
+| `question` | string | Question posed to the user (or equivalent paraphrase). |
+| `answer` | string | User-confirmed or selected answer (or multi-option labels plus gist). |
+
+**Example shape (values are illustrative; structure must satisfy the tables)**:
+
+```json
+{
+  "glossary": {
+    "Wishlist": "User wishlist: add items without immediate checkout",
+    "Sync": "Real-time bidirectional sync keeping multi-device data consistent"
+  },
+  "entities": [
+    { "name": "Wishlist", "type": "aggregate root", "necessity": "required", "description": "The user's wishlist" },
+    { "name": "WishlistItem", "type": "entity", "necessity": "required", "description": "A product line item in the wishlist" }
+  ],
+  "flows": [
+    { "from": "User", "action": "add", "to": "Wishlist", "data": "Product ID", "trigger": "user clicks" },
+    { "from": "Wishlist", "action": "sync", "to": "RemoteServer", "data": "full payload", "mode": "real-time bidirectional" }
+  ],
+  "missing_components": [
+    { "component": "sync conflict resolution", "category": "error handling", "priority": "high", "reason": "concurrent edits on multiple devices" },
+    { "component": "offline queue", "category": "reliability", "priority": "medium", "reason": "buffer operations when network is down" }
+  ],
+  "clarifications": [
+    { "question": "Is sync real-time or batch?", "answer": "real-time bidirectional sync" }
+  ]
+}
+```
+
+---
+
+## Triggering and host pairing
+
+- **Primary path**: **`/genesis` Step 1**: after Step 0 has set `TARGET_DIR`, load this skill, run requirement clarification, and write `concept_model.json`.  
+- **Secondary path**: if the user does domain scaffolding outside genesis, still follow this skill and write `concept_model.json` for the currently active version (path rules unchanged).
+
+---
+
+## Modeling flow (three main phases)
+
+### Phase A: scan fuzzy areas
+
+#### What
+
+Read the requirement text and check across four buckets: **entity fuzziness**, **verb fuzziness**, **dark matter** (beyond happy path), **boundary fuzziness** (permissions / scale / concurrency, etc.); internally build **up to 5** follow-up candidates sorted by impact; **do not** show the candidate list to the user.
+
+#### Why
+
+Without scanning, questioning is unordered or misses critical verbs/dark matter, and the PRD later freezes wrong assumptions.
+
+#### How to validate
+
+Ordered internal queue exists; at least one clarification area is identifiable, or you explicitly record "no fuzziness" with rationale in `clarifications` / `glossary`.
+
+---
+
+### Phase B: interactive follow-up loop
+
+#### What
+
+From the queue, **output only one question at a time**; format is **multiple choice** or **short answer (<= 5 words)**; at most **5** outward questions; append Q&A to `clarifications`.
+
+#### Why
+
+Many questions at once hurt answer quality; crisp formats map cleanly to JSON.
+
+#### How to validate
+
+The user sees at most **one** pending question at any time; every answer enters `clarifications`; stop when one of: critical fuzziness resolved, user says `done`/`ok`/`continue`, or 5 questions asked.
+
+**Multiple-choice template**:
+
+```markdown
+**Recommended:** Option B — Real-time bidirectional sync preserves consistency and suits multi-device use.
+
+| Option | Description |
+| :--- | :--- |
+| A | One-way sync (upload only) |
+| B | Real-time bidirectional sync |
+| C | Scheduled batch sync |
+| Custom | Short description (<= 5 words) |
+
+Reply with the option letter (e.g. "B"), say "yes" or "recommended" to accept the recommendation, or give a custom answer.
+```
+
+**Short-answer template**:
+
+```markdown
+**Suggestion:** User wishlist — the most common term in e-commerce flows.
+
+Format: short answer (<= 5 words). Say "yes" or "suggestion" to accept, or supply your answer.
+```
+
+---
+
+### Phase C: incremental model updates
+
+#### What
+
+After **each** answer, immediately update `concept_model.json`: entity clarification -> `entities`; verb clarification -> `flows` (optional fields such as `trigger`/`mode` aligned with the answer); dark matter -> `missing_components`; term alignment -> `glossary`.
+
+#### Why
+
+Deferring writes loses conversation context and field mapping; incremental disk writes are the lowest-cost traceable-contract approach.
+
+#### How to validate
+
+JSON on disk matches the latest conversation; no "answered everything then fabricated once" mismatch; clarified verb details appear in `data`/`trigger`/`mode` or equivalent on `flows` entries.
+
+---
+
+## Veteran rules (stacked with this SKILL contract)
+
+1. **Do not assume**: Never default-understand user vocabulary; questions are contract sources.  
+2. **One at a time**: Only one outward question.  
+3. **Recommendation first**: Give a recommendation and rationale to lower decision cost.  
+4. **Incremental updates**: Save the file after every answer.  
+5. **Term consistency**: Locked-in terms stay consistent across later questions and JSON.  
+6. **Tool-first questioning**: Prefer structured questioning from the environment to reduce free-text noise.
+
+---
+
+## Sub-agent orchestration (optional)
+
+**Parent agent**: Holds full user need, `TARGET_DIR`, final say on this skill and the **spec contract**; **sole writer** of `concept_model.json`.  
+**Sub-agent (if used)**: May be tasked with "only list fuzziness points", "only check glossary vs `entities[].name` mismatch", etc.—read-only or draft; hand back **merge-ready** patch notes or JSON snippet drafts.  
+**Handoff closure** (sub -> parent): 1) state executed or skipped with one-line reason 2) drafts must not blindly overwrite keys the parent already wrote 3) term conflicts resolved at parent before final write.
+
+---
+
+## Collaboration
+
+- **Before**: `/genesis` Step 0 finalized `TARGET_DIR`; user gives fuzzy requirement narrative.  
+- **After**: `spec-writer` produces `01_PRD.md` from clarified terms and structure.  
+- **Synergy**: This file supplies the **Ubiquitous Language** base for downstream architecture and task breakdown.
+
+---
+
+## `<completion_criteria>` (session close self-check)
+
+- [ ] **CRITICAL methodology anchors** and **`concept_model.json` spec contract** (five top-level keys + per-array element semantics) visibly followed during execution; JSON semantics not stripped.  
+- [ ] Critical fuzzy terms are in **`glossary`**; core **`entities`** / **`flows`** reflect current consensus; **`missing_components`** captures visible dark matter.  
+- [ ] **`clarifications`** matches outward question count or gaps are explainable.  
+- [ ] Model saved to **`TARGET_DIR/concept_model.json`** (equivalent **`.anws/v{N}/concept_model.json`**).  
+- [ ] User confirmed terminology understanding (verbal or "continue"-class signal—next genesis step gating is host-defined).  
+- [ ] Session uses only workspace **`.agents/skills/concept-modeler/SKILL.md`**; no alternate-path paraphrase of the same skill.

package/templates_en/.agents/skills/craft-authoring/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: craft-authoring
+description: Required when running /craft. Provides Workflow / Skill / Prompt scaffolds and quality guardrails using judgment-driven criteria.
+---
+
+# Craft Authoring - Scaffolds and Self-Check
+
+This skill carries the execution detail of `/craft`.  
+`/craft` defines direction; this file defines landing. Direction without landing becomes rhetoric. Landing without direction becomes mechanical output.
+
+## Global Authoring Protocol
+
+1. Keep language precise and intentional.
+2. Let narration add force, not noise.
+3. Prefer judgment signals over decorative phrasing.
+4. Ensure every major section answers: what / why / how to validate.
+5. Build meaning first, then rules, then verification.
+
+**Judgment bar**:
+- A good document makes execution clearer, steadier, and reproducible.
+- A weak document sounds energetic but depends on improvisation.
+
+> **Split from `output-contract`**: This file covers **scaffolds** for workflows/skills/prompts only. Shared on-disk spec, parent/child delegation, and single-writer rules live in **`.agents/skills/output-contract/SKILL.md`**.  
+> **CLI install manifest**: what copies on `anws init`, registry + **`BUNDLE_POLICY`** boundaries—read **`references/BUNDLE_POLICY.md`**.
+
+---
+
+## Workflow Skeleton (minimal)
+
+```markdown
+---
+description: [one-line purpose]
+---
+
+# /name
+
+<phase_context>
+You are **[role]**.
+**Mission**: …
+**Capabilities**: …
+**Constraints**: …
+**Relationship to user**: …
+**Output Goal**: `path`
+</phase_context>
+
+---
+
+## CRITICAL Writing Constraints
+
+> [!IMPORTANT]
+> Writing constraints are defined in `/craft` and should not be duplicated here.
+
+---
+
+## Step 1: [Title]
+
+### What
+...
+
+### Why
+...
+
+### How to Validate
+- ...
+- ...
+
+---
+
+<completion_criteria>
+- [observable done condition]
+</completion_criteria>
+```
+
+## Skill Skeleton (`description` is the trigger)
+
+```markdown
+---
+name: kebab-name
+description: When [concrete trigger scenario], load this skill. [Capability summary]
+---
+
+# Title
+
+## What
+...
+
+## Why
+...
+
+## How to Validate
+- Input contract: ...
+- Output contract: ...
+```
+
+**Bad description**: capability slogan.  
+**Good description**: precise trigger boundary.
+
+**Judgment bar**:  
+A strong description behaves like a gate, not a banner.  
+It defines both when to activate and when not to activate.
+
+## Prompt Skeleton
+
+```markdown
+# Title
+
+## What
+...
+
+## Why
+...
+
+## How to Validate
+- Constraints: ...
+- Output format: ...
+```
+
+## Guardrail Cheat Sheet
+
+| Mechanism | Use |
+| --- | --- |
+| `[!IMPORTANT]` | non-skippable node |
+| `## CRITICAL` | loud boundary |
+| `you **must**` | hard action |
+| `<completion_criteria>` | definition of done |
+
+Strong constraints explain at least: what, why, and drift signal.
+
+## Filling Pass (equivalent to old Step 5)
+
+Use `sequential-thinking` for 3-5 thoughts to cover goals, risks, I/O, and where research lands.
+
+Quick checks:
+- Is each section actionable?
+- Is each critical rule justified?
+- Is completion externally verifiable?
+
+**Judgment bar**:  
+If a paragraph cannot tell the executor what to do, it is noise.  
+If it cannot tell why, it is command theater.  
+If it cannot tell how to verify, it is wishful writing.
+
+## Validation (before ship)
+
+Structure:
+- frontmatter
+- `phase_context` (workflow use)
+- CRITICAL block
+- `<completion_criteria>`
+
+Content:
+- correct path and naming
+- clear trigger boundaries
+- complete input/output contracts
+- externally observable failure signals
+
+## Scoring Gate (before release)
+
+Before shipping, run static scoring:
+
+- read `references/PROMPT_QUALITY_RUBRIC.md`
+- produce a scorecard using `references/SCORECARD_TEMPLATE.md`
+- report Tier (T0/T1/T2/T3) and weighted seven-dimension score
+
+Hard rules:
+
+- if Hard Fail Gate is triggered, final verdict must be `Infeasible`
+- if no Hard Fail and weighted score < 4.0, run one repair iteration and re-score
+
+## Self-Critique (last gate)
+
+Use `sequential-thinking` for 3-5 thoughts:
+- where users might stall
+- where the model might skip
+- which section still mixes too many concerns
+- what to revise before shipping
+
+Final question:  
+If this document is executed repeatedly, are you willing to own its consequences?

package/templates_en/.agents/skills/craft-authoring/references/BUNDLE_POLICY.md

@@ -0,0 +1,42 @@
+# Template bundle contract (CLI · package templates)
+
+This document defines **install boundaries**: what the CLI copies. The product ships **one** `RESOURCE_REGISTRY`. **`zh` / `en`** only selects which on-disk tree supplies text for the **same relative paths**—not two competing product authorities.  
+Any change to **`lib/manifest.js`** `RESOURCE_REGISTRY` is an **explicit** change to what users receive—document it in **release notes**.
+
+---
+
+## 1. Single source for CLI copies
+
+| Mechanism | Role |
+|-----------|------|
+| **`RESOURCE_REGISTRY`** | Array in `lib/manifest.js`; **only** driver for paths written by `anws init` / `anws update` (per IDE projection). |
+| **`TEMPLATE_ROOT`** / **`TEMPLATE_ROOT_EN`** | `src/anws/templates/` and `src/anws/templates_en/` (see `lib/resources`). **`resolveCanonicalPath(rel, templateLocale)`** reads **`templates/`** for **`zh`**; for **`en`** it prefers the same **relative path** under **`templates_en/`**, falling back to **`templates/`** when missing. |
+| **Check** | `scripts/check-canonical-templates.js`: every registry **`source`** must exist under **`templates/`** as a regular file. |
+
+Relative paths that **do not** appear in **`RESOURCE_REGISTRY`**—even if present on disk under **`templates/`**—are **not** installed by default CLI. Example: a **`nexus-query/`** tree maintained in-repo but **not** registered is **not** CLI-delivered—use **registry + this doc** as authority.
+
+---
+
+## 2. `templateLocale`: `templates/` and `templates_en/`
+
+- **`templates/`**: default zh copy tree in the npm package; also the **registry existence check root**.
+- **`templates_en/`**: English mirror; when **`install-lock`** has **`templateLocale: en`**, init/update reads the same **relative paths** from **`templates_en/`**, with fallback to **`templates/`** for missing files.
+- Maintainer duty: keep **the same `source` relative paths** semantically aligned across zh/en—avoid EN-only drift.
+
+---
+
+## 3. Split vs `/craft` and `output-contract`
+
+| Artifact | Owns |
+|----------|------|
+| **`craft-authoring` SKILL** | Authoring scaffolds + scoring gate for `/craft`. |
+| **`output-contract`** | Runtime persisted-report spec + delegation + single-writer rules. |
+| **This `BUNDLE_POLICY`** | **What the CLI installs**, locale root selection, registry **decisions**. |
+
+---
+
+## 4. Slim-down roadmap (suggested order)
+
+1. **Registry gap**: if a path under **`templates/`** should ship but is missing from **`RESOURCE_REGISTRY`**, either **register** it or **delete** unused disk clutter.
+2. **Dedupe**: replace duplicated bullets in reviewers/workflows with **one-line pointers** to **`output-contract`** / this policy.
+3. **Heavy skills** (e.g. **`system-architect`**): shrink embedded templates; **link** one authoritative file instead of mirroring ADR tables—then revisit large merges.

package/templates_en/.agents/skills/craft-authoring/references/PROMPT_QUALITY_RUBRIC.md

@@ -0,0 +1,92 @@
+## Prompt Quality Rubric v1.0 (Static)
+
+Purpose: evaluate Workflow / Skill / Prompt quality through static review without runtime sampling.
+
+---
+
+## 0. Precondition: Static Ablation
+
+Before scoring, remove external attachments:
+
+- emotional imperative phrases
+- format-forcing clauses
+- anti-hallucination patch sentences
+
+Keep the core skeleton:
+
+- Role
+- Context / Worldview
+- Core Concepts
+- Reasoning Path
+
+If the skeleton collapses after ablation, prioritize T2 or T3.
+
+---
+
+## 1. Tier Classification
+
+- `T0` Native Resonance: stable style and control loop survive ablation
+- `T1` Structural Anchoring: reliability mainly comes from strong structure
+- `T2` External Attachment: behavior depends on imperative patches
+- `T3` Cognitive Collapse: factual or logical premise is invalid
+
+> Rule: if T3 is hit, mark infeasible regardless of high sub-scores.
+
+---
+
+## 2. Seven-Dimension Matrix (0-5)
+
+Each dimension must include: `score` + `evidence` + `fix` + `confidence`.
+
+### D1 Structure (weight 20%)
+- clarity of segmentation and structural control
+
+### D2 Alignment (weight 20%)
+- consistency among objective, steps, and validation
+
+### D3 Robustness (weight 15%)
+- resilience to adversarial, missing, or contradictory input
+
+### D4 Efficiency (weight 10%)
+- token cost versus control benefit
+
+### D5 Meta-Isomorphism (weight 15%)
+- whether demanded quality matches textual quality
+
+### D6 Groundability (weight 10%)
+- ability to convert abstraction into executable behavior
+
+### D7 Ablation Survivability (weight 10%)
+- whether the ablated skeleton still drives behavior
+
+---
+
+## 3. Hard Fail Gate
+
+Trigger hard fail if any is true:
+
+1. feasibility check finds fictional core premises (T3)
+2. critical steps have no verifiable completion signal
+3. critical dependency path is unresolved and has no blocker exit
+
+Hard fail output: `Infeasible` + evidence + minimum repair actions.
+
+---
+
+## 4. Consistency Protocol
+
+- Prefer two independent reviewers
+- Any single-dimension gap > 1.0 goes to arbitration
+- Arbitration must cite text evidence, never impression-only judgment
+
+---
+
+## 5. Final Score and Grade
+
+- Weighted final score: 0-5
+- `A`: >= 4.5
+- `B`: 4.0-4.49
+- `C`: 3.0-3.99
+- `D`: < 3.0
+
+If hard fail gate is triggered, final verdict is forced to `Infeasible`.

package/templates_en/.agents/skills/craft-authoring/references/SCORECARD_TEMPLATE.md

@@ -0,0 +1,52 @@
+# Prompt Scorecard
+
+## Target
+- Artifact:
+- Path:
+- Date:
+- Reviewer:
+
+## Ablation Result
+- Removed layers:
+- Remaining skeleton summary:
+- Ablation survivability note:
+
+## Tier
+- Tier: T0 / T1 / T2 / T3
+- Tier rationale:
+
+## Dimension Scores
+| Dimension | Weight | Score (0-5) | Confidence | Evidence | Fix |
+| --- | ---: | ---: | --- | --- | --- |
+| Structure | 20% |  | high/medium/low |  |  |
+| Alignment | 20% |  | high/medium/low |  |  |
+| Robustness | 15% |  | high/medium/low |  |  |
+| Efficiency | 10% |  | high/medium/low |  |  |
+| Meta-Isomorphism | 15% |  | high/medium/low |  |  |
+| Groundability | 10% |  | high/medium/low |  |  |
+| Ablation Survivability | 10% |  | high/medium/low |  |  |
+
+## Hard Fail Gate Check
+- Triggered: Yes / No
+- Condition:
+- Evidence:
+- Minimal repair actions:
+
+## Weighted Score
+- Score:
+- Grade: A / B / C / D
+- Final verdict: Pass / Needs Iteration / Infeasible
+
+## Top Risks
+1.
+2.
+3.
+
+## Top Fixes
+1.
+2.
+3.
+
+## Re-score Expectation
+- Expected tier after fixes:
+- Expected score delta: