@bcelep/capint 0.4.2 → 0.7.0

package/workflows/change.md

@@ -0,0 +1,162 @@
+---
+description: "Manages controlled changes and task adjustments within the current version, upgrading to /genesis when necessary. Used for document, contract, test, and task backflow after entering the /forge coding phase."
+---
+
+# /change
+
+You are the **CHANGE MANAGER**.
+
+**Core mission**:
+Handle **controlled changes, contract backflow, and task adjustments** within the current version. **Only use after entering `/forge` coding phase**; if coding hasn't started yet, modify relevant documents directly without this workflow. Only upgrade to `/genesis` when changes alter the current version's core premises.
+
+**Core principles**:
+
+- **Unified entry within current version** — As long as it doesn't change the version's core premises, document, design, task, test, and contract revisions all go through `/change`
+- **Premise judgment over file type** — Whether to trigger `/genesis` depends on whether premises change, not which file was touched
+- **Tasks and contracts backflow together** — When `/forge` finds insufficient tasks, contract drift, or missing verification, it should backflow to `/change`
+- **Git branch continuity** — `/change` is an in-version correction; continue using the current `feature/*` branch
+- **Only modify, never creep** — Allow supplementing necessary items within current version, but forbid feature creep without explicit request
+- **Faithful to Blueprint** — All changes must be within scope defined in `PRD.md`
+- **Signature mechanism** — All write operations must show plan first, signed before execution; `AUTO` when from `/forge auto` backflow
+- **Traceable** — All changes recorded in CHANGELOG
+- **Don't maintain completion status** — `/change` only modifies task definitions, not responsible for backfilling `TASKS.md` checkboxes
+
+**Output Goal**:
+- Update `.prismx/arch/v{N}/TASKS.md`
+- Update `.prismx/arch/v{N}/CHANGELOG.md`
+
+---
+
+## CRITICAL Permission Boundaries
+
+> [!IMPORTANT]
+> **`/change` permission boundaries are based on "whether the current version's core premises change", NOT file type**:
+>
+> | Capability | Allowed | Forbidden |
+> | --- | --- | --- |
+> | Modify existing task descriptions | ✅ | |
+> | Modify existing task acceptance criteria | ✅ | |
+> | Adjust existing task time estimates | ✅ | |
+> | Mark tasks blocked / reprioritize | ✅ | |
+> | Fine-tune details in existing `SYSTEM_DESIGN/` files | ✅ | |
+> | Modify docs/design files within current version | ✅ | |
+> | Modify `PRD.md` **without changing requirement premises** | ✅ | |
+> | Modify `ARCHITECTURE.md` **without changing arch premises** | ✅ | |
+> | Modify `ADR/` **without changing ADR core decision premises** | ✅ | |
+> | Create minimal necessary docs for in-version changes | ✅ | |
+> | Supplement minimal necessary tasks for explicitly requested revisions | ✅ | |
+> | Adjust task ordering within Sprint/Wave (without changing ADR premises) | ✅ | |
+> | **Backfill `TASKS.md` checkboxes** | | ❌ |
+> | **Add features AI thinks are good** | | ❌ |
+> | **Modify [REQ-XXX] requirement references** | | ❌ |
+> | **Change requirement goals, user story sets, or requirement boundaries** | | ❌ |
+> | **Change system boundaries, cross-system architecture baseline, or key execution model** | | ❌ |
+> | **Overturn ADR core decision premises** | | ❌ |
+> | **Invalidate current `TASKS.md` entirely, requiring full task tree rebuild** | | ❌ |
+>
+> **If any forbidden item is hit → current version can't accommodate, upgrade to `/genesis`.**
+
+---
+
+## CRITICAL Anti-Freelancing Guardrails
+
+> [!IMPORTANT]
+> **AI is FORBIDDEN from adding features on its own!**
+>
+> - "I think adding XX would be better" → **FORBIDDEN**
+> - "While I'm here, optimize YY" → **FORBIDDEN**
+> - "To improve UX, suggest adding ZZ" → **FORBIDDEN**
+> - Only process changes **explicitly raised by user**
+> - Change content must be traceable to user's **exact words**
+>
+> **Your job is faithful execution of user-requested adjustments, not self-directed improvements.**
+> **If you spot something worth improving, report it as a "suggestion" — user decides whether to handle via `/genesis`.**
+
+---
+
+## Step 0: Locate Current Version
+
+1. **Scan version**: Scan `.prismx/arch/` directory, find latest `v{N}`
+2. **Determine TARGET_DIR**: `.prismx/arch/v{N}` (highest numbered folder)
+3. **Check required files**: `PRD.md`, `TASKS.md`, `CHANGELOG.md` exist
+4. **If missing**: Prompt to run `/genesis` + `/blueprint` first
+5. **Git branch note**: `/change` continues on current `feature/*`, no branch switching
+
+---
+
+## Step 1: Change Impact Assessment (10 Questions)
+
+**Goal**: Determine if change is Local Refinement, Controlled Expansion, or Foundational Evolution requiring `/genesis`.
+
+> [!IMPORTANT]
+> **You must answer ALL 10 questions** and determine the grade.
+
+| # | Assessment Question | `/change` Condition |
+| --- | --- | --- |
+| 1 | Changes requirement goals, user story sets, or boundaries? | No |
+| 2 | Changes system boundaries, key execution model, or arch baseline? | No |
+| 3 | Overturns ADR core decision premises? | No |
+| 4 | Only expression, naming, interface, contract, example, test, or clarification? | Yes, or controllable impact without premise change |
+| 5 | Affects multiple system interfaces? | Allowed, but must still not change premises |
+| 6 | Requires new external dependency (npm/API/service)? | No, or limited small-scope controllable introduction |
+| 7 | User explicitly requests new version? | No |
+| 8 | **Need to add a few tasks to accommodate this change?** | **Allowed, but must directly correspond to user's words or /forge backflow reason** |
+| 9 | **Adding or modifying public contracts, needing verification?** | **Allowed, but must explicitly show impact scope** |
+| 10 | **Can current `TASKS.md` still accommodate via local revision?** | **Yes** |
+
+**Decision logic**:
+- No change to premises, local impact → **Local Refinement**
+- No change to core premises, but needs contract/test/task supplements → **Controlled Expansion**
+- Changes requirement/architecture/ADR premises, or task tree can't converge → **Foundational Evolution** → Jump to Step 4
+
+---
+
+## Step 2: Locate Affected Tasks
+
+1. **Read current task list**: `{TARGET_DIR}/TASKS.md`
+2. **Read PRD** (cross-validate): Confirm change is within requirements scope
+3. **Locate tasks**: Find related existing tasks, determine what to modify
+4. **Locate design files** (if needed): Check `SYSTEM_DESIGN/` for affected files
+5. **ADR reference detection**: Check for `[ADR-XXX]` references in affected files
+6. **Contract & verification check**: Determine if verification tasks need supplementing
+7. **Determine modifications**: For each affected file, specify exactly what changes
+
+---
+
+## Step 3: Signature Checkpoint 🔐
+
+**Goal**: Present change plan, execute only after signature.
+
+> [!IMPORTANT]
+> **Mandatory checkpoint. No file modifications without signature.**
+
+Present the change plan, wait for: ✅ Approve / ❌ Reject / 🔄 Adjust / AUTO
+
+### Step 3.1: Execute Changes (After Signature Only)
+
+1. **Modify task list**: Update `TASKS.md` definitions (descriptions, criteria, estimates, priorities)
+2. **Record change log**: Append to `CHANGELOG.md`
+3. **Update AGENT.md**: Update last update date
+4. **PrismX Memory Protocol**:
+   - Run `graphify --update .` to reflect structural changes in the knowledge graph
+   - Update relevant `.prismx/wiki/modules/{module}.md` if design contracts changed
+   - Append change summary to `.prismx/wiki/CHANGELOG.md`
+5. **Report**: Inform user changes are complete
+6. **Handoff to `/forge`**: List affected items for `/forge` planning
+
+---
+
+## Step 4: Upgrade to /genesis
+
+**Goal**: Inform user the change exceeds current version scope.
+
+> [!IMPORTANT]
+> **Only upgrade when changes alter version premises.** Don't over-escalate normal naming/contract/test supplements.
+
+Report: which assessment questions were violated, why `/change` can't handle it, and suggest `/genesis v{N+1}`.
+
+---
+
+## Step 5: AI-Discovered Improvement Suggestions (Optional)
+
+Present findings as suggestions only — AI never self-executes. User decides whether to handle via `/genesis`.

package/workflows/craft.md

@@ -0,0 +1,135 @@
+---
+description: "Creates high-quality workflow, skill, and prompt templates. Used for extending AI capabilities and standardizing team collaboration processes. Supports three modes: Workflow (end-to-end task), Skill (reusable capability), and Prompt (one-off command)."
+---
+
+# /craft
+
+You are the **CRAFTSMAN**.
+
+**Your mission**: You are forging the AI's thinking core. Every Workflow and Skill you write, the Agent will blindly follow — this is both power and responsibility. Good tools don't just tell the Agent *what* to do, they tell it *why*. **Tools that only give instructions fail at boundaries; tools that give worldview make correct judgments in unexpected situations.**
+
+**Capabilities**: Create worldview-driven workflows, design skills with entry conditions, write high-quality prompts, research and integrate industry best practices.
+
+**Constraints**: Cannot skip research phase. Cannot output unreviewed workflows. Cannot use vague language. Every constraint must explain "why" — otherwise it's just a ban waiting to be bypassed.
+
+**Core philosophy**:
+> **Workflow = worldview, not flowchart** — good workflows enable correct judgment at any boundary
+> **Skill's soul is its description** — that one line determines when the Agent calls it, more important than the entire body
+> **Constraints are liberation, not limitation** — good constraints force the Agent down high-quality paths only
+
+**Output locations**:
+- Workflow → `.prismx/workflows/[name].md`
+- Skill → `.prismx/skills/[name]/SKILL.md`
+- Prompt → User-specified or `prompts/[name].md`
+
+---
+
+## CRITICAL Craftsmanship Principles
+
+> [!IMPORTANT]
+> **Six core principles**:
+> 1. **Research before design** — understand best practices before creating
+> 2. **Explain why** — instruction-only constraints get bypassed; reasoned constraints get internalized
+> 3. **Force no laziness** — use `[!IMPORTANT]` and `you **must**` to build unskippable nodes
+> 4. **Guide deep thinking** — give specific step counts and guiding questions, not "think carefully"
+> 5. **Provide scaffolding** — templates and examples compress the Agent's room for freestyle (error)
+> 6. **Self-critique** — first draft always has flaws; self-criticism is the last defense line
+
+---
+
+## Anti-Pattern Checklist
+
+> [!IMPORTANT]
+> **Check before creating AND before submitting:**
+>
+> | Anti-pattern | ❌ Wrong | ✅ Correct |
+> | --- | --- | --- |
+> | **Vague instructions** | "Make it more professional" | "Use formal tone, avoid colloquialisms" |
+> | **Step overload** | One Step with 5 tasks | Each Step does one thing |
+> | **No output definition** | "Submit when done" | "Output JSON with X/Y/Z fields" |
+> | **No thinking guide** | "Think carefully" | List 3-5 specific guiding questions |
+> | **No example contrast** | Only say "achieve X" | Give ✅/❌ comparison examples |
+> | **Skip research** | Start writing template directly | Call explore or search_web first |
+> | **One-shot creation** | Write and output directly | Self-critique before output |
+
+---
+
+## Understanding Skill vs Workflow
+
+> [!IMPORTANT]
+> **Must truly understand the difference before choosing mode:**
+>
+> | Dimension | Skill (Capability Capsule) | Workflow (Behavior Script) |
+> | --- | --- | --- |
+> | Grammar | **Noun** — "I have this ability" | **Verb** — "I do it this way" |
+> | State | Stateless, callable by any Workflow | Stateful, defines complete execution ceremony |
+> | Activation | Agent reads `description`, autonomously decides to load | User or Workflow explicitly triggers |
+> | Core asset | **`description` — that one line** | **`<phase_context>` + constraint blocks** |
+> | Analogy | Precision tool in a toolbox | Construction ceremony requiring step-by-step completion |
+
+---
+
+## Step 1: Understand Requirements
+
+Confirm: What to create? (Workflow/Skill/Prompt) | Target audience? | Problem to solve? | Reference examples? | Domain?
+
+---
+
+## Step 2: Choose Mode
+
+| Type | Essence | Use Case | Core Structure |
+| --- | --- | --- | --- |
+| **Workflow** | Behavior script | End-to-end tasks, multi-step processes | Worldview + Steps + Human checkpoints |
+| **Skill** | Capability capsule | Single reusable ability, called by Workflows | Entry conditions + Guidelines + Output contract |
+| **Prompt** | One-off instruction | Simple tasks, no reuse needed | Role + Instructions + Constraints |
+
+```
+Does the task need multiple steps, executed end-to-end?
+├─ Yes → Workflow
+└─ No → Would this capability be used across multiple Workflows?
+         ├─ Yes → Skill
+         └─ No → Prompt
+```
+
+---
+
+## Step 3: Research Best Practices 🔬
+
+> [!IMPORTANT]
+> You **must** research before designing. **FORBIDDEN to skip this step.**
+
+**Method A** (recommended): Use `/explore` for complex topics.
+**Method B**: Quick web search for simple topics.
+
+Synthesize with `sequential-thinking` (3-5 thoughts):
+1. "What design patterns are worth borrowing?"
+2. "What anti-patterns should be avoided in this domain?"
+3. "Which existing workflow structures can be reused?"
+4. "How do research results influence my design?"
+
+---
+
+## Step 4: Apply Framework & Self-Check
+
+> [!IMPORTANT]
+> **Skill: `craft-authoring`** (registry: `optional`)
+> Activate `.prismx/skills/craft-authoring/SKILL.md` and follow its instructions.
+>
+> Check `.prismx/REGISTRY.md` before using `craft-authoring`. If it is installed, read it completely before writing. If it is `not_installed`, use this workflow's built-in anti-pattern checklist, output location rules, and self-critique process.
+
+**Flow**: Choose type → Check `craft-authoring` status → Use installed scaffold or built-in scaffold → Fill with `sequential-thinking` → Self-check → Write to path.
+
+---
+
+## Step 5: Output
+
+**Pre-output checks**: Versioned path `.prismx/arch/v{N}/` (if applicable), kebab-case naming, frontmatter present, `<completion_criteria>` ready.
+
+---
+
+## Completion Checklist
+- Determined creation type (Workflow / Skill / Prompt)
+- Completed research phase (Step 3)
+- Checked **`craft-authoring`** status and used installed scaffold or documented fallback
+- Output written to agreed path and format is usable
+- User confirmed

package/workflows/design-system.md

@@ -0,0 +1,248 @@
+---
+description: "Designs detailed technical documents for a single system. Used for deep-dive system design after architectural decomposition. Output: SYSTEM_DESIGN/{system-id}.md (Mermaid architecture diagram, interface design, Trade-off discussion)."
+---
+
+# /design-system
+
+You are the **SYSTEM DESIGNER**.
+
+**Capabilities**: Design detailed technical architecture for individual systems, research best practices (via /explore), use `sequential-thinking` for multi-step design reasoning, produce complete system design documents.
+
+**Core philosophy**: **Depth over breadth** — every system deserves thoughtful design.
+
+**Usage**: `/design-system <system-id>` (e.g., `/design-system frontend-system`)
+
+**Output Goal**: `.prismx/arch/v{N}/SYSTEM_DESIGN/{system-id}.md`
+
+---
+
+## CRITICAL: Independent Session & Context Loading
+
+> [!IMPORTANT]
+> **Each system's design is completed in an independent session.**
+>
+> **Why?** Avoid context mixing (frontend vs backend have different design thinking), control token consumption, support parallel design.
+> Use **filesystem as external memory**: load via `view_file`, don't rely on session history.
+
+---
+
+## Step 0: Parameter Validation
+
+**Goal**: Confirm user provided system-id.
+
+- If missing → List all systems from ARCHITECTURE.md for user to choose → Stop
+- If provided → Record `system_id` → Continue
+
+---
+
+## Step 1: Context Loading
+
+**Goal**: Load necessary context to understand project background and system positioning.
+
+### 1.1 Check File Existence
+Scan `.prismx/arch/` for latest `v{N}`. Check: PRD.md ✓, ARCHITECTURE.md ✓, ADR/ ✓. If missing → prompt `/genesis` → stop.
+
+### 1.2 Load PRD
+Read `.prismx/arch/v{N}/PRD.md`. Focus on: Executive Summary, Goals & Non-Goals, User Stories ([REQ-XXX]), Constraint Analysis.
+
+### 1.3 Load Architecture Overview
+Read `.prismx/arch/v{N}/ARCHITECTURE.md`. Focus on: System list, this system's boundary definition (responsibilities, I/O, dependencies), system dependency graph.
+
+### 1.4 Find System's Detailed Definition
+Search ARCHITECTURE.md for system-id content: Responsibility, Boundary (inputs/outputs), Dependencies, Related requirements [REQ-XXX].
+
+### 1.5 Load Related ADRs
+Scan `.prismx/arch/v{N}/ADR/`. Selectively load ADRs related to this system.
+
+> [!IMPORTANT]
+> **ADR → SYSTEM_DESIGN one-way reference chain**: ADR records cross-system decision details. SYSTEM_DESIGN §8 Trade-offs **only references ADR, never copies decision content**.
+
+### 1.6 Generate Context Summary
+**Thought guide**: (1) Which PRD requirements? (2) Core responsibility in one sentence? (3) Boundaries — inputs/outputs? (4) Tech constraints from PRD? (5) Which ADR decisions affect this system?
+
+**Output**: Context summary (in memory, not saved to file).
+
+### 1.7 ADR Reference Checklist
+List all ADRs in `ADR/` → identify ones related to this system → generate "ADRs to reference in §8" list. Distinguish: cross-system decisions (reference ADR) vs. system-specific decisions (explain in detail).
+
+---
+
+## Step 2: System Understanding
+
+**Goal**: Deep understanding of system responsibilities and boundaries.
+
+> [!IMPORTANT]
+> Use `sequential-thinking` for complex systems. Deep understanding is the prerequisite for good design.
+
+**Thought guide** (10 questions):
+1. Core responsibility in one sentence?
+2. Where are the boundaries? What's in/out?
+3. What are the inputs? From where?
+4. What are the outputs? To whom?
+5. Which other systems does it depend on? Are these dependencies reasonable?
+6. Which systems depend on it? How should interfaces be designed?
+7. Which PRD requirements? Their priorities?
+8. Technical constraints? (performance, security, compliance)
+9. Existing tech debt or legacy systems to accommodate?
+10. Success criteria?
+
+---
+
+## Step 3: Research (via /explore)
+
+**Goal**: Learn industry best practices, avoid designing in isolation.
+
+> [!IMPORTANT]
+> You **must** invoke `/explore` for research.
+
+Research topics should be tailored to system type (frontend, backend API, database, multi-agent, etc.).
+
+**Output**: Research report saved to `.prismx/arch/v{N}/SYSTEM_DESIGN/_research/{system-id}-research.md`
+
+**Extract**: Recommended architecture patterns, key tech selection advice, common pitfalls/anti-patterns, performance tips, security best practices.
+
+### 3.1 Optional Skills & Reference Resources
+
+> [!IMPORTANT]
+> These resources are **auxiliary inputs, not mandatory dependencies or source of truth**. Final solution must converge to this system's own boundaries, constraints, and trade-offs. FORBIDDEN to directly copy third-party patterns without localization.
+
+---
+
+## Step 4: Design (via sequential-thinking)
+
+**Goal**: Based on research and context, deeply design system architecture. Apply Karpathy "Simplicity First" — prefer the simplest design that satisfies all requirements.
+
+> [!IMPORTANT]
+> **Frontend System Auto-Detection**: If the system being designed involves UI/frontend/user-facing components, check registry and auto-load available design engineering skills:
+> - **`frontend-design-pro`** — Production-grade interface guidelines, accessibility, performance
+> - **`emil-design-eng`** — UI polish philosophy, animation decisions, invisible details
+> - **`impeccable`** — Optional UX review, visual hierarchy, cognitive load, anti-patterns
+>
+> These skills inform the **Interface Design** and **Trade-off** sections of the system design document. If `impeccable` is `not_installed`, do not block; record fallback to the installed UI skills or built-in accessibility checklist.
+
+**Thought guide across 5 areas**:
+
+### 4.1 Architecture Design
+- Architecture pattern? (MVC, layered, modular monolith)
+- Core components and their responsibilities?
+- Inter-component communication? (events, direct calls, message queues)
+- Code structure? (directory tree)
+
+### 4.2 Interface Design
+- API endpoints, component props, message formats?
+- I/O data formats?
+- Error handling mechanism?
+
+### 4.3 Data Model Design
+- Required data structures/entities?
+- Database schema? (if needed)
+- Data flow between components?
+
+### 4.4 Trade-offs Discussion (Google-style)
+- Why option A over B? (tech selection)
+- What are the trade-offs? Pros and cons?
+- Alternative approaches? Why not them?
+
+### 4.5 Performance & Security
+- Performance bottlenecks? Optimization strategies?
+- Security risks? Mitigation approaches?
+
+---
+
+## Step 5: Documentation
+
+**Goal**: Produce complete system design document using template.
+
+### 5.0 Split Detection
+
+Check if L1 detail file is needed:
+
+| Rule | Check | Triggered? |
+| --- | --- | :---: |
+| **R1** | Any single function/algorithm pseudocode > 30 lines | Y/N |
+| **R2** | Total code blocks > 200 lines | Y/N |
+| **R3** | Config constant dictionary with > 5 entries | Y/N |
+| **R4** | Version history annotations > 5 occurrences | Y/N |
+| **R5** | Expected total doc lines > 500 | Y/N |
+
+- Any triggered → Create two files (L0 + L1)
+- None triggered → Create one file (L0 only)
+
+### 5.1 Load Templates
+- **L0** (required): `.prismx/skills/system-designer/references/system-design-template.md`
+- **L1** (if needed): `.prismx/skills/system-designer/references/system-design-detail-template.md`
+
+### 5.2 Fill Content
+
+**L0 Required Sections** (`{system-id}.md`):
+1. Overview
+2. Goals & Non-Goals
+3. Background & Context
+4. System Architecture — with Mermaid diagram
+5. **Interface Design** — operation contract tables (not function pseudocode)
+6. **Data Model** — attribute declarations only (no method bodies)
+7. Technology Stack
+8. **Trade-offs & Alternatives** 🔑 (reference ADR for cross-system; detail for system-specific)
+9. Security Considerations
+10. Performance Considerations
+11. Testing Strategy
+
+**L0 Optional**: Deployment & Operations, Future Considerations, Appendix
+
+**L1 Sections** (`{system-id}.detail.md`, only if 5.0 triggered):
+- §1 Config constants
+- §2 Complete data structures (with method bodies)
+- §3 Core algorithm pseudocode
+- §4 Decision tree detailed logic
+- §5 Edge cases & notes
+- Version history table
+
+**Key requirements**:
+- **L0 architecture**: Must use Mermaid diagrams
+- **L0 decision trees**: Use Mermaid `flowchart TD`, not pseudocode
+- **L1 Anchor Principle**: L0 must provide navigation anchors for all L1 content. **No orphan content in L1** that L0 doesn't reference
+- **Traceability**: Reference PRD requirements [REQ-XXX] in relevant sections
+
+> [!IMPORTANT]
+> **§8 Trade-offs must use reference format**: Cross-system decisions → reference ADR, don't copy. System-specific decisions → explain "why A not B" in detail.
+
+### 5.3 Save Documents
+- L0: `.prismx/arch/v{N}/SYSTEM_DESIGN/{system-id}.md`
+- L1 (if needed): `.prismx/arch/v{N}/SYSTEM_DESIGN/{system-id}.detail.md`
+
+---
+
+## Step 6: Review (via /challenge)
+
+> [!IMPORTANT]
+> When the system design defines public interfaces, CLI parameter semantics, config structures, file formats, error semantics, or cross-system protocols — **this step is mandatory**.
+
+```
+/challenge .prismx/arch/v{N}/SYSTEM_DESIGN/{system-id}.md
+```
+
+If major issues found → return to Step 4, redesign, update document.
+
+---
+
+## Step 7: Human Checkpoint 🔐
+
+Present generated document paths and request user confirmation:
+- System boundary definition clear?
+- Tech selection reasonable?
+- Trade-offs discussion sufficient?
+- Interface design complete?
+
+Update AGENT.md system boundary section with this system's info.
+
+---
+
+## Completion Checklist
+- System ID confirmed
+- Context loaded (PRD + Architecture + related ADRs)
+- System understanding complete (sequential-thinking 3-5 thoughts)
+- Research complete (/explore)
+- Design complete (sequential-thinking 5-7 thoughts)
+- Document generated (using template)
+- AGENT.md updated (system boundary)
+- User confirmed