@artale/pi-real-engineering 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# @artale/pi-real-engineering
+
+Minimal Pi skills for real engineering: align first, build in small feedback loops, keep domain language sharp, and improve the harness before blaming the model.
+
+## Install
+
+```bash
+pi install npm:@artale/pi-real-engineering
+```
+
+Local test:
+
+```bash
+pi install C:/Users/Artale/Projects/gh-repo/packages/pi-real-engineering
+/reload
+```
+
+## Skills
+
+| Skill | Invocation | Purpose |
+|---|---|---|
+| `setup-artale-skills` | user | Create repo conventions: `AGENTS.md`, `CONTEXT.md`, `docs/adr/`, `.pi/plans/` |
+| `grill-with-docs` | user | Interview the user against docs/context before implementation |
+| `tdd` | model | Red-green-refactor one vertical slice at a time |
+| `diagnosing-bugs` | model | Reproduce, minimize, hypothesize, instrument, fix |
+| `domain-modeling` | model | Maintain shared language in `CONTEXT.md` and ADRs |
+| `codebase-design` | model | Design deep modules with small interfaces and clean seams |
+
+## Conventions
+
+- `CONTEXT.md` = shared domain language, not implementation scratchpad.
+- `docs/adr/*.md` = durable architectural decisions.
+- `.pi/plans/*.md` = temporary plans/spikes before durable decisions.
+- `AGENTS.md` = Pi-facing repo rules; mention `CLAUDE.md` only for compatibility.
+
+No runtime dependencies. No command extension. Skills only.

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@artale/pi-real-engineering",
+  "version": "0.1.0",
+  "description": "Minimal Pi skills for real engineering loops: setup, docs grilling, TDD, debugging, domain modeling, and codebase design.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": ["pi-package", "pi", "pi-skill", "engineering", "tdd", "debugging", "domain-modeling"],
+  "files": ["README.md", "skills/**/*"],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "skills": ["./skills"]
+  }
+}

package/skills/codebase-design/DEEPENING.md

@@ -0,0 +1,10 @@
+# Deepening
+
+Move complexity behind a smaller interface. Replace pass-through layers with modules that earn their existence.
+
+Checklist:
+
+- name the callers
+- shrink the interface
+- hide more implementation detail
+- keep tests crossing the same seam callers use

package/skills/codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,13 @@
+# Design It Twice
+
+Before changing architecture, sketch two different interfaces.
+
+Compare:
+
+- depth
+- locality
+- testability
+- migration cost
+- how much domain language the interface exposes
+
+Pick the option that gives callers more leverage with less surface area.

package/skills/codebase-design/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: codebase-design
+description: Design deep modules with small interfaces and clean seams. Use for architecture, refactoring, testability, or module/interface decisions.
+---
+
+# Codebase Design
+
+Design deep modules: a lot of behavior behind a small interface at a clean seam.
+
+## Vocabulary
+
+- Module — anything with an interface and implementation
+- Interface — everything callers must know
+- Implementation — what sits behind the interface
+- Seam — where behavior can vary
+- Adapter — concrete thing at a seam
+- Depth — leverage per unit of interface
+
+## Process
+
+1. Read `CONTEXT.md` and relevant ADRs.
+2. Identify the module and its callers.
+3. Apply the deletion test: if removed, does complexity vanish or spread?
+4. Design two interface options.
+5. Pick the deeper interface.
+6. Verify through the interface, not internals.
+
+See `DEEPENING.md` and `DESIGN-IT-TWICE.md`.

package/skills/diagnosing-bugs/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: diagnosing-bugs
+description: Disciplined bug diagnosis. Use for broken, failing, slow, or flaky behavior.
+---
+
+# Diagnosing Bugs
+
+Do not jump to a theory before a red-capable loop exists.
+
+## Phases
+
+1. Build one command that can reproduce the bug.
+2. Confirm it fails for the user's exact symptom.
+3. Minimize the repro.
+4. List 3-5 falsifiable hypotheses.
+5. Instrument one hypothesis at a time.
+6. Fix and convert the repro into a regression check.
+7. Remove debug logs/prototypes.
+
+## Required final evidence
+
+- original repro command now passes or no longer reproduces
+- regression check passes, or no valid seam exists and is reported
+- debug instrumentation removed

package/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,15 @@
+# ADR format
+
+# YYYY-MM-DD: Decision title
+
+## Status
+Accepted | Proposed | Superseded
+
+## Context
+What forced the decision?
+
+## Decision
+What did we choose?
+
+## Consequences
+What gets easier/harder?

package/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,13 @@
+# CONTEXT.md format
+
+## Glossary
+- Term — precise meaning
+
+## Entities
+- Entity — relationships and invariants
+
+## Workflows
+- Workflow — domain steps, not implementation details
+
+## Open questions
+- Question — owner/status

package/skills/domain-modeling/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: domain-modeling
+description: Maintain shared domain language in CONTEXT.md and ADRs. Use when terminology, invariants, or architectural decisions need sharpening.
+---
+
+# Domain Modeling
+
+`CONTEXT.md` is a glossary and domain map, not a spec or scratchpad.
+
+## Use this skill to
+
+- challenge vague or overloaded terms
+- define canonical domain language
+- record invariants and edge-case scenarios
+- create ADRs only for hard-to-reverse, surprising, real trade-off decisions
+
+## Files
+
+- `CONTEXT.md` for terms, entities, invariants, workflows, open questions
+- `docs/adr/YYYY-MM-DD-short-title.md` for durable decisions
+
+See `CONTEXT-FORMAT.md` and `ADR-FORMAT.md`.

package/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: grill-with-docs
+description: User-invoked interview before implementation. Reads docs/context, asks hard questions, and resolves ambiguity before work starts.
+disable-model-invocation: true
+---
+
+# Grill With Docs
+
+Do not implement. Interview until the task is sharp enough to hand to an agent.
+
+## Process
+
+1. Read `CONTEXT.md`, relevant ADRs, `.pi/plans/`, and nearby docs.
+2. Restate the goal in one paragraph.
+3. Ask 3-7 hard questions, one group at a time:
+   - desired behavior
+   - non-goals
+   - affected modules/interfaces
+   - data/state changes
+   - verification command
+   - rollback/risk
+4. Call out contradictions between user language, docs, and code.
+5. End with a concise plan or “not ready yet”.
+
+## Output
+
+- Shared understanding
+- Open decisions
+- Verification command
+- Files likely touched
+- Whether to use `tdd`, `diagnosing-bugs`, `domain-modeling`, or `codebase-design` next

package/skills/setup-artale-skills/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: setup-artale-skills
+description: Configure a repo for Artale real-engineering skills: AGENTS.md rules, issue workflow, CONTEXT.md, ADRs, and .pi/plans. User-invoked setup procedure.
+disable-model-invocation: true
+---
+
+# Setup Artale Skills
+
+Prompt-driven setup. Explore first, ask before writing, then make the smallest durable conventions.
+
+## Explore
+
+Check:
+
+- `git remote -v` / `.git/config`
+- `AGENTS.md`, `CLAUDE.md`
+- `CONTEXT.md`, `CONTEXT-MAP.md`
+- `docs/adr/`
+- `docs/agents/`
+- `.pi/plans/`
+
+## Ask one decision at a time
+
+1. **Issue workflow**: GitHub (`gh`), GitLab (`glab`), local markdown, or other.
+2. **Docs layout**: single-context `CONTEXT.md` or multi-context `CONTEXT-MAP.md`.
+3. **Verifier strictness**: strict by default; PASS requires real checks.
+
+## Write
+
+Prefer `AGENTS.md`. If only `CLAUDE.md` exists, update it for compatibility. Do not create both unless the user asks.
+
+Create lazily:
+
+- `CONTEXT.md`
+- `docs/adr/`
+- `.pi/plans/`
+- `docs/agents/issue-tracker.md`
+- `docs/agents/domain.md`
+
+## Agent skills block
+
+```md
+## Agent skills
+
+- Use `CONTEXT.md` for domain language before planning.
+- Use `docs/adr/` for durable architectural decisions.
+- Use `.pi/plans/` for temporary plans/spikes.
+- Use `tdd` for behavior changes, `diagnosing-bugs` for bugs, `codebase-design` for module/interface work.
+- Do not return PASS unless checks actually ran.
+```

package/skills/setup-artale-skills/issue-tracker-github.md

@@ -0,0 +1,11 @@
+# GitHub issue workflow
+
+Use `gh issue` for issue creation, listing, and updates.
+
+Default labels:
+
+- `needs-triage`
+- `needs-info`
+- `ready-for-agent`
+- `ready-for-human`
+- `wontfix`

package/skills/setup-artale-skills/issue-tracker-gitlab.md

@@ -0,0 +1,11 @@
+# GitLab issue workflow
+
+Use `glab issue` for issue creation, listing, and updates.
+
+Default labels:
+
+- `needs-triage`
+- `needs-info`
+- `ready-for-agent`
+- `ready-for-human`
+- `wontfix`

package/skills/setup-artale-skills/issue-tracker-local.md

@@ -0,0 +1,11 @@
+# Local issue workflow
+
+Store issues as markdown under `.scratch/issues/`.
+
+Each issue should include:
+
+- title
+- status
+- owner
+- acceptance criteria
+- verification command

package/skills/setup-artale-skills/triage-labels.md

@@ -0,0 +1,7 @@
+# Triage labels
+
+- `needs-triage` — maintainer must evaluate
+- `needs-info` — waiting on reporter/user
+- `ready-for-agent` — fully specified and AFK-ready
+- `ready-for-human` — needs human judgment/implementation
+- `wontfix` — will not be actioned

package/skills/tdd/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: tdd
+description: Red-green-refactor for features and fixes. Use when behavior changes need a tight feedback loop.
+---
+
+# TDD
+
+One vertical slice at a time. Tests verify behavior through public interfaces, not implementation details.
+
+## Loop
+
+1. Read `CONTEXT.md` and relevant ADRs.
+2. Name the public behavior.
+3. Write one failing test or smallest red-capable check.
+4. Run it and confirm it fails for the right reason.
+5. Write the least code to pass.
+6. Refactor only while green.
+7. Repeat.
+
+## Rules
+
+- No bulk “write all tests first”.
+- No private-method tests unless there is no usable seam; if so, report the seam problem.
+- One runnable command must prove the final state.
+
+See `tests.md`, `mocking.md`, and `refactoring.md`.

package/skills/tdd/mocking.md

@@ -0,0 +1,5 @@
+# Mocking
+
+Mock network, time, randomness, and external services.
+
+Do not mock the module you are trying to gain confidence in. If the only way to test is to mock internals, report the seam problem instead.

package/skills/tdd/refactoring.md

@@ -0,0 +1,9 @@
+# Refactoring
+
+Refactor only when green.
+
+- remove duplication
+- deepen modules
+- simplify interfaces
+- improve naming with domain language
+- rerun the same verification command after each step

package/skills/tdd/tests.md

@@ -0,0 +1,5 @@
+# Tests
+
+Good tests describe observable behavior through public interfaces. Bad tests mirror implementation shape.
+
+Prefer integration-style tests at the smallest useful seam. Each test should fail for a user-visible reason and survive internal refactors.