@haaaiawd/anws 2.3.0 → 2.4.1

package/templates_en/.agents/skills/system-designer/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: system-designer
+description: Load when `/design-system <system-id>` needs to produce L0/L1 detailed design documents for one system. Defines boundaries, interface contracts, data models, trade-offs, Mermaid diagrams, testing strategy, and L1 split rules; paired with the same-bundle `/design-system` workflow.
+---
+
+# System Designer (ALPHA)
+
+<phase_context>
+You are **SYSTEM DESIGNER**.
+
+**Mission**: refine one `system-id` from `02_ARCHITECTURE_OVERVIEW.md` into an implementable, reviewable system design that `/blueprint` can consume.  
+**Capabilities**: inherit PRD/ADR/Architecture constraints; consume `/explore` research; use the 6D framework to derive components, interfaces, data models, risks, and testing strategy; persist L0 and conditional L1 documents.  
+**Limits**: do not change PRD, ADR, or system-boundary premises; do not put long pseudocode, config dictionaries, or method bodies into L0; do not copy ADR content, only reference ADRs.  
+**Output Goal**: `{TARGET_DIR}/04_SYSTEM_DESIGN/{system-id}.md`, plus `{system-id}.detail.md` and `_research/{system-id}-research.md` when triggered.
+</phase_context>
+
+---
+
+## CRITICAL Writing And Output Contract
+
+> [!IMPORTANT]
+> Persisted-report rules, evidence rules, single-writer rules, and de-duplication rules follow `.agents/skills/output-contract/SKILL.md`. This skill only adds system-design-specific constraints.
+>
+> - **Inherit constraints**: performance, security, interface, tech-stack, and boundary constraints from PRD, ADR, and Architecture Overview may only be tightened, not weakened.
+> - **ADR one-way references**: cross-system decisions reference `03_ADR/*`; do not duplicate ADR rationale. If an ADR is insufficient, route through `/change` or `/genesis`.
+> - **Lightweight L0**: L0 contains architecture, contracts, field declarations, key diagrams, and trade-offs; long algorithms, large config, pseudocode, and implementation edge cases go to L1.
+> - **Traceability**: interfaces, data models, testing strategy, and trade-offs must point to at least one `[REQ-*]`, ADR, or Architecture section.
+> - **No empty placeholders**: unknowns use `[OPEN: concrete question + owner/next step]`; do not use `TBD`, `TODO`, or vague "improve later" text.
+
+---
+
+## Design Framework: 6D
+
+### 1. Discover
+
+### What
+Read `01_PRD.md`, `02_ARCHITECTURE_OVERVIEW.md`, relevant `03_ADR/*`, and any existing design draft for this system. Extract responsibility, boundaries, dependencies, linked `[REQ-*]`, and non-goals.
+
+### Why
+Detailed design is not a second architecture pass; it refines approved boundaries into implementable contracts.
+
+### Acceptance
+- One sentence can state this system's responsibility.
+- Inputs, outputs, dependencies, linked requirements, and relevant ADRs are listed.
+
+### 2. Deep-Dive
+
+### What
+Use the same-bundle `/explore` workflow to produce `_research/{system-id}-research.md`; research only the risks that affect this system.
+
+### Why
+Complex design needs external evidence; otherwise trade-offs become preferences.
+
+### Acceptance
+- Research supports at least one design decision or risk mitigation.
+- The `_research` path exists, or `/design-system` gives a concrete non-applicability reason.
+
+### 3. Decompose
+
+### What
+Derive components, modules, data flow, state flow, and external interfaces. Use `sequential-thinking` when the host rules require it.
+
+### Why
+Component boundaries determine testability, dependency direction, and downstream task quality.
+
+### Acceptance
+- Each core component has responsibility and dependencies.
+- Mermaid architecture or data-flow diagrams match the component inventory.
+
+### 4. Design
+
+### What
+Define interface contracts, data models, error semantics, configuration boundaries, state transitions, and security/performance strategy. Prefer operation contract tables for interfaces; data models include fields and relations, not method bodies.
+
+### Why
+`/blueprint` needs externally observable contracts, not implementation prose.
+
+### Acceptance
+- Core operations have contract tables or equivalent interface tables.
+- Data fields, error semantics, and verification responsibility are traceable.
+
+### 5. Defend
+
+### What
+List key trade-offs, performance bottlenecks, security boundaries, observability, and testing strategy. Public contracts require a Contract Verification Matrix.
+
+### Why
+The design document should expose failure modes before `/forge` has to guess them.
+
+### Acceptance
+- At least two important decisions explain why option A was chosen over option B.
+- Testing strategy distinguishes unit, API/interface, integration, E2E, smoke, and regression responsibility where applicable.
+
+### 6. Document
+
+### What
+Read `.agents/skills/system-designer/references/system-design-template.md` and, when needed, `system-design-detail-template.md`; persist L0/L1.
+
+### Why
+The template is the long-term maintenance contract used by the host and downstream workflows.
+
+### Acceptance
+- L0 required sections 1-11 are present; optional sections 12-14 are kept or marked `N/A` with a reason.
+- If L1 is triggered, L0 links to `.detail.md`.
+
+---
+
+## L0 / L1 Boundaries
+
+| Layer | File | Content | Load Frequency |
+| --- | --- | --- | --- |
+| L0 navigation | `{system-id}.md` | goals, boundaries, diagrams, operation contracts, field declarations, trade-offs, testing strategy | high; always loaded for task planning |
+| L1 implementation | `{system-id}.detail.md` | long pseudocode, config constants, complex algorithms, implementation edge cases, detailed state tables | low; only when task input explicitly references it |
+
+### L1 Split Rules R1-R5
+
+Create `{system-id}.detail.md` if any rule is triggered:
+
+| Rule | Trigger | Action |
+| --- | --- | --- |
+| R1 | one continuous code block > 30 lines | move to L1 |
+| R2 | total code block lines > 200 | move to L1 |
+| R3 | config constant dictionary entries > 5 | move to L1 or a config table |
+| R4 | inline version comments > 5 | consolidate into version history |
+| R5 | L0 total length > 500 lines | split into L1 |
+
+### Content Placement
+
+| Content Type | L0 | L1 |
+| --- | --- | --- |
+| system goal, boundary, architecture diagrams, trade-offs | yes | no |
+| operation contracts, HTTP/CLI/cross-system protocols | yes | details only |
+| data fields, Protocol/ABC signatures | yes | complex schema examples |
+| function-body pseudocode and complex algorithms | no | yes |
+| config constants and edge-case expansion | summary | yes |
+
+---
+
+## Template And Sections
+
+Use `.agents/skills/system-designer/references/system-design-template.md`.
+
+**Required L0 sections 1-11**:
+
+1. Overview
+2. Goals & Non-Goals
+3. Background & Context
+4. Architecture
+5. Interface Design
+6. Data Model
+7. Technology Stack
+8. Trade-offs & Alternatives
+9. Security Considerations
+10. Performance Considerations
+11. Testing Strategy
+
+**Optional sections 12-14**: Deployment & Operations, Future Considerations, Appendix. Optional does not mean arbitrary deletion; use `N/A + reason` when not applicable.
+
+---
+
+## Design Rules
+
+- **Research first**: obtain research evidence before design, or record why research is not applicable.
+- **Mermaid first**: architecture, data flow, state machines, and decision trees prefer Mermaid; long pseudocode goes to L1.
+- **Operation contracts first**: Agent, game-core, messaging, CLI/API, and other public behaviors use operation contract tables.
+- **Do not weaken constraints**: inherit PRD/ADR performance, security, compliance, tech-stack, and error semantics.
+- **Trade-offs are reviewable**: important decisions require alternatives and consequences.
+- **Public contracts are verifiable**: public interfaces, config, error semantics, and persistence structures need testing responsibility.
+
+---
+
+## Handoff Checklist
+
+- [ ] `01`, `02`, relevant `03_ADR/*`, `_research`, and templates have been read.
+- [ ] L0 exists and required sections 1-11 are complete.
+- [ ] L1 trigger rules were evaluated; if triggered, `.detail.md` exists and L0 links to it.
+- [ ] Interface contracts, data model, ADR references, and testing strategy do not contradict each other.
+- [ ] No legacy `.agent/` paths, emoji, or empty `TODO/TBD` placeholders remain.
+
+---
+
+<completion_criteria>
+- `system_id` and `TARGET_DIR` were confirmed by the `/design-system` host.
+- Output follows `.agents/skills/output-contract/SKILL.md` for persistence and collaboration closure.
+- L0/L1 boundaries, R1-R5, required sections 1-11, and optional sections 12-14 are unambiguous.
+- Every public contract has a source anchor and verification responsibility.
+- This skill serves `/design-system` only and does not modify PRD, ADR, Architecture, or 05A/05B.
+</completion_criteria>

package/templates_en/.agents/skills/system-designer/references/system-design-detail-template.md

@@ -0,0 +1,187 @@
+# {System Name} — Implementation Details (L1)
+
+> **File Type**: L1 implementation layer · **Mapped L0**: [`{system-id}.md`](./{system-id}.md)
+> This file is loaded only when explicitly referenced by a `/forge` task. For daily reading and task planning, prioritize L0.
+> ** Island Check**: Every section in this file must have a corresponding hyperlink entry in L0; isolated content is forbidden.
+
+---
+
+## Version History
+
+> All change records are centralized here and should no longer be scattered in code comments.
+
+| Version | Date         | Changelog |
+| ---- | ------------ | --------- |
+| v1.0 | {YYYY-MM-DD} | Initial version  |
+
+---
+
+## Section Index of This File
+
+|   §   | Section | Mapped L0 Entry |
+| :---: | -------------------------------------------------------------------- | :--------------: |
+|  §1   | [Config Constants](#1-config-constants)                             |  L0 §6 Data Model  |
+|  §2   | [Full Core Data Structures](#2-full-core-data-structures)         |  L0 §6 Data Model  |
+|  §3   | [Core Algorithm Pseudocode](#3-core-algorithm-pseudocode-non-trivial-algorithm-pseudocode) | L0 §5 Operation Contracts |
+|  §4   | [Detailed Decision Tree Logic](#4-detailed-decision-tree-logic-decision-tree-details)            |   L0 §4 Architecture Diagram   |
+|  §5   | [Edge Cases & Gotchas](#5-edge-cases--gotchas-edge-cases--gotchas)      |    L0 §5 / §9    |
+|  §6   | [Test Helpers](#6-test-helpers-test-helpers) *(Optional)*                        | L0 §11 Testing Strategy  |
+
+---
+
+## §1 Config Constants
+
+> Centralize all hardcoded configs, enum mappings, and lookup tables here.
+> **Mapped L0 Entry**: anchor at end of L0 §6 → *For full config constant dictionaries, see [L1 §1]*
+
+```python
+# -- Example: unit config table --
+UNIT_CONFIG = {
+    # UnitType.WARRIOR: {atk, def, hp, mov, range, cost, tech, behavior, move_type}
+}
+
+# -- Example: terrain config table --
+TERRAIN_CONFIG = {
+    # TerrainType.PLAIN: {move_cost: 1, passable: "land", buildings: [...]}
+}
+
+# -- Example: building config table --
+BUILDING_CONFIG = {
+    # BuildingType.FARM: {cost: 5, tech: "farming", rp_bonus: 1}
+}
+```
+
+---
+
+## §2 Full Core Data Structures
+
+> Contains full class definitions including method bodies. L0 should only include field declarations and method signatures (`def foo(): ...`).
+> **Mapped L0 Entry**: anchor at end of L0 §6.1 → *For full method implementations, see [L1 §2]*
+
+```python
+@dataclass
+class ExampleEntity:
+    id: str
+    # ... fields
+
+    def some_method(self) -> bool:
+        """Method notes"""
+        # Full implementation logic
+        pass
+```
+
+---
+
+## §3 Core Algorithm Pseudocode (Non-Trivial Algorithm Pseudocode)
+
+> [!IMPORTANT]
+> **Entry threshold — if none of the following is met, writing this section is forbidden**
+>
+> | Entry Condition | Notes |
+> |---------|------|
+> | Estimated function body **> 15 lines** | Short functions are already understandable from L0 operation contracts |
+> | Includes **non-obvious business rules** | Damage formulas, state machine branches, complex validation |
+> | Includes **multi-step side-effect chains** | A→check→B→update C→trigger D, order must not be changed |
+> | **Teammates cannot infer implementation from signature** | If function name + params already clearly express intent, no need |
+
+Each subsection maps to one row in the L0 §5 operation contracts table and provides a full function body.
+
+### §3.1 {Operation Name}
+
+**Mapped Contract**: L0 §5.1 — `{function_name}()`
+**Entry Reason**: {which entry condition is met}
+
+```python
+def function_name(param1: Type, param2: Type) -> ReturnType:
+    """
+    Function description.
+
+    Preconditions:
+    1. ...
+
+    Side effects:
+    - ...
+    """
+    # Full implementation logic
+    pass
+```
+
+> **Notes**: {critical traps like deep copy / race conditions / order dependencies}
+
+---
+
+## §4 Detailed Decision Tree Logic (Decision Tree Details)
+
+> Text expansion + complete pseudocode corresponding to the L0 Mermaid decision diagram.
+> **Mapped L0 Entry**: comment under L0 §4 Architecture Diagram → *For full decision logic, see [L1 §4]*
+
+### §4.1 {Decision Scenario Name}
+
+**Mapped L0 Mermaid**: `{system-id}.md §{section}`
+
+```python
+def plan_or_decide(...):
+    # Step 1: check high-priority conditions
+    # Step 2: branching logic
+    pass
+```
+
+---
+
+## §5 Edge Cases & Gotchas
+
+> Non-obvious cases that must be handled during implementation.
+> **Mapped L0 Entry**: anchor in L0 §5 or §9 Security
+
+| Scenario           | Risk       | Handling       |
+| -------------- | ---------- | -------------- |
+| {Edge case description} | {Potential bug} | {Correct handling} |
+
+### §5.1 {Specific Case}
+
+```python
+# Incorrect approach
+# cloned_unit.embarked_unit = unit.embarked_unit  # shallow copy -> state contamination!
+
+# Correct approach
+# cloned_unit.embarked_unit = deepcopy(unit.embarked_unit) if unit.embarked_unit else None
+```
+
+---
+
+## §6 Test Helpers
+
+> Optional. Factory functions or fixtures reused in unit tests.
+> **Mapped L0 Entry**: anchor in L0 §11 Testing Strategy
+
+```python
+def make_test_unit(type=UnitType.WARRIOR, hp=10, pos=(0, 0)) -> Unit:
+    """Create a test Unit"""
+    pass
+
+def make_test_world(size=8) -> World:
+    """Create a test World"""
+    pass
+```
+
+---
+
+<!--  AGENT Usage Guide
+
+When to create this file: when any L0 split rule R1-R5 is triggered.
+  R1 single code block > 30 lines
+  R2 total code block lines > 200 lines
+  R3 config constant dictionary entries > 5
+  R4 version inline comments > 5 occurrences
+  R5 total document lines > 500
+
+Island check: every new section added here must also add a hyperlink anchor at corresponding position in L0.
+
+§ numbering convention:
+  §1 config constants  — always first section
+  §2 data structures  — full classes with method bodies
+  §3 algorithm pseudocode — numbered by function order (§3.1, §3.2 ...)
+  §4 decision tree    — expansion of L0 Mermaid diagrams
+  §5 edge cases  — extracted from "#  note" style code comments
+  §6 test helpers  — optional
+-->