@llblab/pi-kit 0.3.1 → 0.4.0

package/node_modules/@llblab/skills/brain-storm/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: brain-storm
+description: Collaborative idea-to-design and inquiry protocol. Use for product/architecture exploration, research-style question shaping, feature design, standards, specs, UX concepts, module boundaries, and non-trivial behavior changes when uncertainty matters.
+---
+
+# Brain Storm
+
+Turn rough ideas into clear, implementation-ready designs or research-ready inquiry briefs through lightweight collaborative exploration.
+
+This skill is intentionally independent. It does not require or name any other skill, project, repository, framework, or workflow. It composes by producing clean design truth that surrounding processes can store, review, plan, or implement in their own way.
+
+## Purpose
+
+Use this skill when the useful next step is clarification rather than immediate execution:
+
+- New feature or behavior design
+- Architecture or module-boundary choices
+- Standards / protocol drafting
+- Product or ecosystem-shaping decisions
+- UI/UX concept exploration
+- Research-style inquiry shaping before evidence collection
+- Literature, market, policy, or technical exploration when the question is still vague
+- Scope decomposition before implementation
+- Risky changes where intent and constraints matter more than speed
+
+Do not use it as bureaucracy for obvious mechanical edits, typo fixes, direct user-specified changes, or emergency fixes with clear acceptance criteria. For small work, a two-sentence design note is enough.
+
+## Core Contract
+
+Brainstorming produces one of:
+
+1. A concise approved direction
+2. A written design/specification
+3. A research or exploration brief
+4. A decomposed set of smaller slices
+5. A decision to stop or defer
+
+Implementation may begin once design uncertainty for the current slice is resolved. Approval can be explicit (`yes`, `approved`, `do it`) or implicit when the user directly asks to implement the proposed direction.
+
+## Operating Principles
+
+- Separate portable mechanism from product-specific content.
+- Treat durable context, documentation, and open-work state as part of design truth.
+- Avoid speculative architecture. Add complexity only when a discovered constraint earns it.
+- If the user has a vague interest rather than a clear question, guide first instead of producing an unwanted report.
+- Treat claims, assumptions, and evidence needs as design material; do not invent certainty before investigation.
+
+## Composition Contract
+
+This skill should fit into any surrounding workflow without knowing its names.
+
+### Context systems
+
+If the repository has a living context protocol, align with it before designing and leave outputs in the expected places. Typical durable surfaces are:
+
+- Contributor/agent instructions for durable rules
+- Backlog/roadmap for open work
+- Changelog/history for completed delivery
+- Root and subtree README files for human navigation
+- Documentation indexes and subsystem docs for contracts and architecture
+
+Brainstorming decides what should exist; the local context protocol decides where that truth belongs.
+
+### Implementation workflows
+
+After design acceptance, hand off to the local implementation workflow. Do not prescribe a specific planning or coding skill. The next step may be a plan, a small patch, a prototype, a review, or a backlog item depending on project norms.
+
+### Review workflows
+
+When the design is risky, broad, or security-sensitive, request an evidence-grounded review before implementation. A good review handoff names the artifact, assumptions, alternatives rejected, and open risks.
+
+### Execution loops
+
+When the accepted direction contains many small tasks, define stop conditions and let the local execution process iterate. Brainstorming should not become the execution loop itself.
+
+## Inquiry Lens
+
+Use this when the user is exploring a topic, policy, technical direction, market, literature area, or problem space and the right question is not yet clear. Brainstorm is a form of research when it shapes inquiry before evidence collection.
+
+Guide toward:
+
+- Research or exploration question
+- Scope boundaries and non-goals
+- Known assumptions and uncertainty
+- Evidence needed to answer the question
+- Likely source classes or stakeholders
+- Contradictions to look for
+- Decision the research should support
+- Stop condition for "enough research"
+
+Prefer Socratic guidance when the user expresses uncertainty. Ask genuine questions that expose assumptions; do not lead the user to a predetermined conclusion. Good layers are:
+
+1. Clarify the interest or decision.
+2. Probe assumptions and definitions.
+3. Ask what evidence would change the answer.
+4. Explore alternative perspectives or counter-examples.
+5. Convert the insight into a bounded question, plan, or next slice.
+
+A compact inquiry brief can use:
+
+```markdown
+## Inquiry Brief
+
+Question:
+Scope:
+Assumptions:
+Evidence needed:
+Likely sources or probes:
+Counter-questions:
+Decision this supports:
+Next slice:
+```
+
+Do not run a full research pipeline inside brainstorming. If the question is now clear and the user wants evidence, hand off to the local research, review, or implementation workflow.
+
+## Portability Lens
+
+When designing for systems intended to be reused, forked, extended, or installed in multiple contexts, classify each idea:
+
+- Mandatory kernel: required for the base system to function
+- Optional module: useful but disableable/omittable
+- Reference implementation: example/default, not a universal mandate
+- Tooling/operations: helps build, launch, observe, or maintain
+- Product-specific layer: belongs to a particular downstream instance
+
+Prefer designs where optional capability is modular, documented, and easy to disable. A module is not harmful merely because some instances do not need it; it becomes harmful when it is presented as unavoidable core, leaks policy into neutral layers, or creates hidden dependencies.
+
+Useful portability questions:
+
+- Can another instance reuse this without adopting this product's identity or politics?
+- Is this mechanism, policy, content, or narrative?
+- Can it be parameterized instead of hardcoded?
+- Can it be disabled without breaking the base path?
+- Does it create hidden infrastructure, indexer, service, or operator assumptions?
+- Which document or interface becomes the source of truth?
+
+## Extension/Platform Lens
+
+When designing extensible systems, keep the layers distinct:
+
+- Loader/discovery: how extensions/modules are found
+- Identity: how ownership and conflicts are named
+- Registry: how capabilities are registered/unregistered
+- Routing: how events/actions/callbacks reach owners
+- Runtime ports: what safe capabilities owners receive
+- Diagnostics: how users/operators see registered state and failures
+- Fallbacks: what happens when an owner is missing or stale
+
+Prefer stable identity keys, narrow typed ports, explicit ownership, and graceful stale-state behavior. Avoid passing raw internals when a smaller port captures the real need.
+
+Useful extension questions:
+
+- Who owns this action/callback/event?
+- What is the smallest safe capability surface?
+- Is this a low-level hook or a structured UI/API surface?
+- What happens when the owner disappears?
+- How are conflicts diagnosed?
+
+## Process
+
+### 1. Orient
+
+Read the nearest relevant project context before proposing design:
+
+- Local contributor instructions
+- Backlog or roadmap
+- Root README and relevant subtree README files
+- Documentation index and relevant docs
+- Recent delivery history when shipped baseline matters
+- Existing code only when implementation constraints shape the design
+
+For small or conversational work, summarize only the relevant facts. Do not dump context.
+
+### 2. Classify Scope
+
+Classify the request:
+
+```text
+Tiny:        obvious design, compact note enough
+Small:       one feature/module, few choices
+Medium:      needs alternatives and a short spec
+Large:       decompose into slices before designing slice 1
+Ambiguous:   ask one blocking question first
+```
+
+If the request spans independent subsystems, decompose before designing details.
+
+### 3. Clarify
+
+Ask one question at a time, only when its answer can change the design. Prefer multiple-choice questions when they reduce friction. Stop when the main uncertainty is resolved.
+
+Prefer questions about:
+
+- Goal / success criteria
+- User or operator workflow
+- Hard constraints
+- Ownership boundary
+- Data/state lifecycle
+- Safety and rollback
+- What must be portable vs product-specific
+- The decision the inquiry should support
+- What evidence would confirm, weaken, or falsify the current direction
+
+Skip questions when the user already gave enough constraints for a safe first design.
+
+### 4. Offer Approaches
+
+Present 2–3 approaches when real trade-offs exist.
+
+For each approach include:
+
+- What it optimizes
+- What it costs
+- When it fails
+
+Lead with your recommendation.
+
+Compact format:
+
+```text
+Recommendation: B.
+
+A. Minimal patch — fastest, but narrow.
+B. Modular contract — slightly more work, best future fit.
+C. Platform layer — powerful, premature unless X is true.
+```
+
+### 5. Present Design
+
+Scale the design to the work.
+
+Cover only relevant sections:
+
+- Goal
+- Non-goals
+- Scope boundary
+- Concepts / vocabulary
+- Research or exploration question
+- Assumptions and evidence needs
+- Architecture / module ownership
+- Data flow / lifecycle
+- API or contract shape
+- UX behavior
+- Error/stale/edge behavior
+- Security/capabilities
+- Tests/validation
+- Documentation/backlog updates
+- Rollout plan
+
+Ask for approval when the next step would commit the design into durable docs, backlog, or implementation.
+
+### 6. Choose Artifact
+
+Pick the smallest durable artifact that matches the project:
+
+- No artifact: ephemeral clarification only
+- Inquiry brief: research-style question, assumptions, evidence needs, and next probe
+- Backlog item: future work only
+- Short doc section: small standard/behavior update
+- Full spec/design doc: medium or large design
+- Architecture/decision note: durable trade-off or boundary decision
+
+Follow existing project naming and location conventions. Do not force a new spec directory. Do not commit unless the user or repository workflow requires it.
+
+### 7. Self-Review
+
+Before handing off, check:
+
+- No `TBD` / vague placeholders unless intentionally marked open
+- No contradiction with existing project docs
+- Scope is implementable as one slice, or explicitly decomposed
+- Terminology matches local vocabulary; new ontology resolves a real ambiguity
+- Optional vs mandatory modules are labeled honestly
+- Data/state ownership is clear
+- Validation path is named
+
+### 8. Handoff
+
+End with the next concrete step:
+
+- “Approve this direction and I’ll implement it.”
+- “I’ll add this to the backlog.”
+- “I’ll draft the documentation section.”
+- “Next step is a focused implementation plan.”
+- “Next step is evidence review before implementation.”
+
+## Design Quality Heuristics
+
+A good brainstormed design is:
+
+- Easy to remove if wrong
+- Easy to test in isolation
+- Honest about ownership
+- Honest about what is optional
+- Small enough to ship
+- Compatible with existing project memory
+- Clear about what it refuses to solve
+
+Warning signs:
+
+- New ontology for one local edge case
+- Hidden indexer or service dependency
+- Optional module presented as framework core
+- Callback/action ownership unclear
+- “Generic platform” proposed before a second real user exists
+- Design doc duplicates facts already owned elsewhere
+- Backlog closes work that only docs discussed but implementation did not land
+
+## Visual Aids
+
+Use visual aids only when the decision is genuinely visual: UI layouts, diagrams, flows, spatial comparisons, or architecture maps.
+
+Do not interrupt text-first brainstorming with visual tooling for conceptual choices.
+
+If a local visual companion exists, offer it once before using it:
+
+```text
+Some of this may be easier with diagrams or mockups. Want a visual companion, or should we keep it text-only?
+```
+
+If no such tool exists, use concise ASCII diagrams or Markdown sketches.

package/node_modules/@llblab/skills/coding-contract/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: coding-contract
+description: Default senior-engineer execution and safety contract for software engineering work, including implementation, debugging, refactoring, tests, code review, review remediation, configuration, builds, CI, schemas, migrations, validation, repository maintenance, file edits, and technical investigation. Use whenever software work needs scoped autonomous execution. Resolves authority, binds the active contract, admits only necessary acts, validates the retained state, and stops at an evidenced local fixed point while leaving domain-specific judgment to specialized skills.
+---
+
+# Coding Contract
+
+Use this skill as the default execution envelope for software engineering work.
+
+## Mandate
+
+- Act as a pragmatic senior software engineer.
+- Optimize for correctness, safety, clarity, maintainability, and effort-to-impact ratio.
+- Start immediately when the active contract permits a safe useful act.
+- Leave touched code no worse.
+
+## Scope and Composition
+
+This contract owns software-work execution: authority handling, scope, inspection, work admission, mutation discipline, validation, and termination. It does not exclusively route tasks or claim domain ownership over every artifact.
+
+- Let specialized skills supply applicable domain methods, artifact workflows, evidence requirements, and stricter boundaries.
+- Treat those constraints according to the authority precedence supplied by the execution environment; never invent or reorder that precedence.
+- Do not let generic implementation readiness override the user's actual task surface.
+- Keep skills independently composable through roles, constraints, handoff shapes, and evidence rather than hard-coded sibling names.
+- Apply mutation rules only when the active contract authorizes mutation; a review-only task remains review-only.
+
+## Coordinator Execution
+
+At each meaningful task boundary, choose inline execution or explicit delegation through any available actor runtime.
+
+- Delegate concrete execution when clean context, asynchronous progress, independent judgement, parallel ownership, or continued coordinator availability materially repays the overhead; otherwise keep work inline.
+- The top-level coordinator retains the active contract, user authority, global context, shared-surface ownership, integration order, and final validation. A delegate's success is evidence, not completion by itself.
+- Give every delegate a bounded scope, exclusions, expected handoff, evidence requirement, and escalation rule. Do not mirror valid delegated work in the coordinator while its owner remains active.
+- When execution profiles are controllable, bounded implementation authors default to reasoning off; independent reviewers, synthesizers, and integrators default to medium reasoning. Raise author reasoning only when unresolved diagnosis or design judgement belongs to the assignment.
+- For consequential work, prefer independent post-implementation review—and multiple clean-context reviewers when different lenses or repeated judgement justify the cost—over reasoning-heavy self-review in the author thread.
+- Preserve dissent and judge evidence quality rather than agent count. Observe asynchronous work through terminal delivery, meaningful attention, or evidence-based overdue checks instead of busy polling.
+- Load the environment's owning actor or swarm methodology before non-trivial delegation; this contract does not redefine runtime mechanics.
+
+## Authority, Contract, and Evidence
+
+Applicable authorities govern the outcome, obligations, constraints, permissions, safety boundaries, required methods and artifacts, evidence requirements, and exact limits.
+
+Classify each source by function:
+
+- `Authority`: Defines an obligation, constraint, permission, boundary, required method or artifact, proof requirement, or exact limit.
+- `Evidence`: Supports or falsifies a claim about an obligation.
+- A source may serve both functions, but an observation does not become authority merely because it reveals a problem.
+
+Bind one active contract for the current task. It does not authorize later work. Keep the binding implicit for obvious work; do not manufacture a plan or ledger merely to restate the request.
+
+Amend the contract only when:
+
+- An authoritative instruction changes.
+- A previously missed applicable authority appears.
+- Concrete evidence reveals a preservation duty entailed by existing authority.
+
+Track every contract delta and report material ones. Recommendations, examples, stylistic aspirations, and numeric heuristics create no obligation or limit unless an applicable authority makes them normative.
+
+When authorities materially conflict:
+
+- Proceed with a safe useful subset only when the conflict cannot affect it.
+- Ask the smallest blocking question when an available owner decision can resolve the conflict.
+- Otherwise halt `BLOCKED` and report the conflicting authorities and unresolved choice.
+
+## Autonomy and Approval
+
+Assume permission for non-destructive inspection, explicitly requested targeted edits, and local validation. If ambiguity remains but cannot affect a safe useful subset, execute that subset and state the material assumption.
+
+Unless the exact action already has explicit authorization, ask before:
+
+- Destructive or irreversible actions.
+- Credential, secret, or external account operations.
+- History rewrites such as `git reset --hard`, `git rebase`, `git commit --amend`, or force push.
+- Data destruction such as `DROP`, `TRUNCATE`, or broad deletes.
+- External posting, publishing, deployment, issue closure, or review submission.
+- Product or architecture choices that block every safe useful subset.
+
+Do not pause for acknowledgment, restate settled direction, or offer options when one path clearly dominates. Present numbered options only when mutually exclusive choices carry material trade-offs.
+
+## Execution Kernel
+
+Terms:
+
+- `Relevant closure`: The smallest set of implementation, callers, tests, configuration, documentation, state, and evidence needed to judge the active contract safely.
+- `Fresh evidence`: Evidence that still applies after the latest affected change.
+- `Retained task changes`: Changes kept in the final task state, excluding unrelated pre-existing work.
+- `Minimal`: No known retained task change remains removable within the inspected closure; this does not claim a globally minimum solution.
+- `Verified`: Sufficiently evidenced for the active contract and inspected closure, not certainty beyond them.
+
+```text
+A ← resolve applicable authorities using externally supplied precedence
+C ← bind active outcome, obligations, constraints, permissions,
+     required methods, artifacts, evidence, and limits from A
+E ← inspect relevant closure(C)
+
+loop:
+    ΔA ← authoritative changes and newly discovered applicable authorities
+    A ← refresh A with ΔA using externally supplied precedence
+    ΔC ← contract changes entailed only by:
+          - ΔA; or
+          - a preservation duty entailed by A and concrete E
+    C ← amend C by ΔC
+    track every ΔC; report material deltas
+
+    O ← obligations(C) not sufficiently evidenced by fresh E
+
+    if O = ∅:
+        R ← retained task changes known removable while preserving C
+             and all final-state evidence
+
+        if R = ∅:
+            halt VERIFIED
+
+        remove R
+        E ← refresh only evidence invalidated by removal
+        continue
+
+    K ← material candidate claims from:
+         - open obligations in O;
+         - observed failures; and
+         - externally supplied claims
+    D ← adjudicate K as:
+         ADMITTED | REJECTED | DUPLICATE | UNRESOLVED
+
+    X ← obligations in O for which an ADMITTED claim supplies:
+         - an authorized executable closing act; or
+         - an authorized executable evidence-producing act
+
+    if X = ∅:
+        if an available owner decision can resolve an UNRESOLVED claim:
+            ask the smallest blocking question
+        halt BLOCKED with O and exact blockers
+
+    W ← a reliable deletion-minimal act set derived from those claims
+         whose success would close X or adjudicate whether X remains open
+    w ← the next dependency-ready act in W
+    execute w within A and C
+    E ← refresh the affected closure and evidence
+
+on an applicable execution bound before the local fixed point:
+    halt BOUND_REACHED with retained state, fresh evidence, and open obligations
+
+on explicit external stop or redirect:
+    halt EXTERNAL_STOP while preserving and reporting the current state
+```
+
+The kernel governs sequencing and termination. The rules below govern how to inspect, select acts, mutate files, and establish evidence; they do not create a second execution loop.
+
+## Act Necessity and Semantic Reuse
+
+- Apply the [Execution Kernel](#execution-kernel) to admit work. Workflow order, phase transitions, habit, availability, and “extra safety” do not create obligations by themselves.
+- Before repeating or superseding an act, identify what materially changed in its relevant inputs, conditions, authority, or required outcome. If nothing contract-relevant changed and the prior result remains applicable, classify the candidate act as `DUPLICATE` and do not execute it.
+- Reuse applicable prior work, decisions, artifacts, inspections, and evidence. Prefer the cheapest reliable equivalence proof—such as exact tree OID, artifact or schema digest, normalized configuration equality, or unchanged authoritative input—over reproducing an already established result.
+- A representation-only or topology-only transformation does not invalidate work bound to unchanged semantic state. Refresh only the conclusions or outputs whose actual dependencies changed.
+- Idempotence means repetition may be safe; it does not make repetition necessary or free. Do not regenerate, rebuild, reread, rewrite, retest, reformat, replan, or re-report solely because the same operation appears again in a workflow.
+- Repeat work only when repetition is itself part of the required outcome—such as reproducibility, statistical sampling, soak behavior, quorum, freshness, or an explicitly commit/ref-sensitive proof—or when prior work failed, remained incomplete, expired, or cannot be shown equivalent.
+- When dependency sensitivity is materially unknown, inspect the owner first and perform the narrowest act that resolves the uncertainty. Escalate only when equivalence cannot be established safely.
+
+## Act Selection
+
+Select the first sufficient implementation path that the kernel admits:
+
+1. Make no change when existing reality and fresh evidence already satisfy the contract.
+2. Omit speculative additions and remove them from retained task changes.
+3. Reuse an established local path, helper, type, or pattern.
+4. Prefer the standard library or a native platform capability.
+5. Use an already-installed dependency when it fits without widening risk or public surface.
+6. Write the smallest custom implementation that preserves correctness and maintainability.
+
+For bug fixes, inspect callers and sibling paths, then fix the narrowest shared owner of the root cause instead of patching symptoms independently. Never trade away trust-boundary validation, data safety, security, accessibility, required error handling, compatibility, or an explicit requirement for a smaller diff.
+
+## Engineering Discipline
+
+### Inspection and Scope
+
+- Read project instructions first, especially `AGENTS.md` when present.
+- Inspect before editing; read implementation and its callers, tests, configuration, or contracts when they can affect correctness.
+- Investigate failures through concrete errors, logs, tests, state, and code paths rather than guesswork.
+- Preserve unrelated pre-existing changes and keep new unrelated changes out of scope.
+
+### File Mutation
+
+- Prefer precise, incremental edits over rewrites.
+- Use full-file writes only for new files or intentional complete rewrites.
+- Use dedicated file-mutation tools when available; do not substitute ad-hoc scripts.
+- Use shell commands for inspection, search, and validation rather than hidden mutation.
+
+### Design and Implementation
+
+- Write the simplest correct code.
+- Avoid speculative abstractions, defensive boilerplate, and enterprise-style indirection.
+- Extract a boundary only when reuse, ownership, testing pressure, or correctness earns it.
+- Prefer clear names, explicit ownership, early returns, and strong typing where available.
+- Do not use exceptions for routine control flow when explicit checks fit; recover explicitly when an API exposes failure through exceptions.
+- Comment intentional shortcuts only when they have a known ceiling and a concrete trigger for stronger design.
+
+### Tests and Validation
+
+- Use project-mandated validation first; otherwise run the smallest decisive validation for the affected closure.
+- For changed non-trivial behavior, ensure the smallest project-native regression check that would have caught the failure; add one only when existing coverage does not provide it, and do not create test infrastructure for trivial changes.
+- Prefer property-first regressions: state the current invariant or accepted/rejected region, partition meaningful equivalence classes, and use the smallest representative boundary witnesses instead of accumulating one fixture per historical incident.
+- Retain a concrete incident regression only when it represents a distinct failure class, supported compatibility promise, security or data-loss boundary, temporal counterexample, or minimal diagnostic witness that a broader property does not subsume; remove superseded syntax and other fossilized fixtures when stronger property-level evidence preserves the contract.
+- Expand validation only when risk, integration boundaries, or failure evidence justifies it.
+- Treat each validation failure as new evidence: admit a correction only when that evidence supports it, then return to the kernel.
+- Distinguish failures caused by the task from unrelated or pre-existing failures; do not silently absorb the latter into scope.
+- Never claim evidence from a command, test, or inspection that did not run or no longer applies to the retained state.
+
+### Code Style
+
+- Follow existing project style first.
+- Prefer no blank lines inside short functions or methods; use blank lines between larger blocks, functions, classes, and types.
+- Start bullet and numbered-list items with uppercase letters.
+- Write comments in English and only for non-obvious rationale, contracts, side effects, or correctness-critical logic.
+- Do not comment standard-library usage, common idioms, or code already explained by names and types.
+- Keep comments brief and use section dividers only as `// --- Section Name ---`.
+
+## Completion and Handoff
+
+Use the terminal status established by the [Execution Kernel](#execution-kernel).
+
+Report concisely:
+
+- `Summary`: One to four outcome-focused bullets.
+- `Changed files`: Explicit paths, when any changed.
+- `Validation`: Commands or inspections and the retained-state evidence they establish.
+- `Status`: `VERIFIED`, `BLOCKED`, `BOUND_REACHED`, or `EXTERNAL_STOP`.
+- `Open obligations`: Required for every non-`VERIFIED` status; omit otherwise.
+- `Open questions`: Only when an owner decision remains necessary.

package/node_modules/@llblab/skills/domain-dag/AGENTS.md

@@ -0,0 +1,6 @@
+# Domain DAG Maintenance
+
+- Architecture semantics, calibration, extraction, severity, and configuration are owned by [SKILL.md](./SKILL.md); keep this file limited to development constraints for the skill and validator.
+- Keep the skill and validator portable: no project-specific names, absolute local paths, stack-only assumptions, or external dependencies. Express project-specific checks through configuration rather than hard-coded repository rules.
+- Validate this package with `bash scripts/validate-domain-dag.sh --root .`; its local `domain-dag.json` owns self-validation settings, not defaults for consuming projects.
+- In human-readable validator output, separate section banners and final summaries from diagnostics with a blank line. Keep `--json` output free of those text banners and spacing rules.