pi-feature-dev 1.4.0 → 1.5.0

package/README.md

@@ -19,6 +19,10 @@ isolated workers, Git task commits, internal reviews, finalize, and a portable
 run summary. It is portable across host agents that provide fresh-context
 isolated workers and Git access.
 
+The `grill` skill runs a dependency-aware interview that researches facts,
+exhausts the current decision frontier round by round, sharpens domain language,
+and records agreed terminology and durable architectural decisions.
+
 ## Install
 
 ```
@@ -60,6 +64,7 @@ versions came from:
 
 - [umputun/cc-thingz](https://github.com/umputun/cc-thingz)
 - [anthropics/claude-code feature-dev plugin](https://github.com/anthropics/claude-code/tree/main/plugins/feature-dev)
+- [mattpocock/skills batch-grill-me and domain-modeling skills](https://github.com/mattpocock/skills)
 
 ## Usage
 
@@ -83,6 +88,12 @@ Run a plan with `plan-exec`:
 /skill:plan-exec docs/plans/20260518-example.md
 ```
 
+Stress-test an idea before planning or implementation:
+
+```text
+/skill:grill Challenge the design for usage-based billing.
+```
+
 This package is intentionally skill-only. It does not provide prompt template shortcuts; use `/skill:<name>` for explicit Pi invocation.
 
 ## Feature-dev workflow
@@ -104,14 +115,23 @@ pi-feature-dev/
 ├── package.json
 └── skills/
     ├── feature-dev/
+    │   ├── agents/openai.yaml
     │   └── SKILL.md
+    ├── grill/
+    │   ├── agents/openai.yaml
+    │   ├── SKILL.md
+    │   ├── CONTEXT-FORMAT.md
+    │   └── ADR-FORMAT.md
     ├── plan-exec/
+    │   ├── agents/openai.yaml
     │   ├── SKILL.md
     │   ├── references/
     │   └── scripts/
     ├── plan-make/
+    │   ├── agents/openai.yaml
     │   └── SKILL.md
     └── plan-review/
+        ├── agents/openai.yaml
         └── SKILL.md
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-feature-dev",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Portable coding-agent workflows packaged as skills.",
   "license": "MIT",
   "type": "module",

package/skills/feature-dev/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Feature Dev"
+  short_description: "Develop features with a guided workflow"
+  default_prompt: "Use $feature-dev to implement this feature through discovery, design approval, review, and validation."

package/skills/grill/ADR-FORMAT.md

@@ -0,0 +1,35 @@
+# ADR Format
+
+Store an ADR in the `docs/adr/` directory owned by the applicable context. Use root `docs/adr/` for a system-wide decision. Create the directory lazily when the first ADR is accepted.
+
+Use sequential filenames such as `0001-event-sourced-orders.md` and `0002-postgres-for-write-model.md`. Scan the target directory for the highest existing number and increment it by one.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{In one to three sentences, state the context, the decision, and why it was chosen.}
+```
+
+That is enough for most ADRs. Record that a decision was made and why; do not fill sections for ceremony.
+
+## Optional sections
+
+Include a section only when it adds information a future reader needs:
+
+- `status` frontmatter (`proposed`, `accepted`, `deprecated`, or `superseded by ADR-NNNN`) when the decision may be revisited.
+- **Considered Options** when rejected alternatives are worth remembering.
+- **Consequences** when non-obvious downstream effects need to be explicit.
+
+## Qualification test
+
+Create an ADR only when all three statements are true:
+
+1. Reversing the decision later would be meaningfully costly.
+2. A future reader would find the choice surprising without its context.
+3. The decision resolved a real trade-off among genuine alternatives.
+
+Qualifying decisions commonly include architectural shape, cross-context integration, lock-in-heavy technology choices, ownership boundaries, deliberate deviations from the obvious path, constraints invisible in code, and non-obvious rejected alternatives.
+
+Skip easy-to-reverse choices, obvious implementation details, and decisions with no real alternative.

package/skills/grill/CONTEXT-FORMAT.md

@@ -0,0 +1,61 @@
+# `CONTEXT.md` Format
+
+Use `CONTEXT.md` as an opinionated domain glossary and nothing else.
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentences describing what this context is and why it exists.}
+
+## Language
+
+**Order**: {A one- or two-sentence definition of the term.}
+_Avoid_: Purchase, transaction
+
+**Invoice**: A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**: A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- Be opinionated. When several words describe the same concept, choose one canonical term and list the others under `_Avoid_`.
+- Keep definitions to one or two sentences. Define what the concept is, not everything it does.
+- Include only terms specific to this project's domain. Exclude general programming concepts, implementation details, requirements, and architectural decisions.
+- Group terms under subheadings only when natural clusters emerge. Keep a flat list for one cohesive area.
+- Add or change a term only after the user explicitly resolves it.
+
+Before adding a term, ask whether it is unique to this domain or merely a general technical concept. Include only the former.
+
+## Single- and multi-context repositories
+
+Use one root `CONTEXT.md` for a single context.
+
+For multiple contexts, use a root `CONTEXT-MAP.md` to list the contexts, locations, and relationships:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced`; Fulfillment consumes it to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched`; Billing consumes it to generate an invoice
+- **Ordering ↔ Billing**: Both use the canonical `CustomerId` and `Money` value definitions
+```
+
+Infer the structure from existing files:
+
+- If `CONTEXT-MAP.md` exists, read it and update the relevant context.
+- If only a root `CONTEXT.md` exists, use the single context.
+- If neither exists, create a root `CONTEXT.md` lazily after the first term is resolved.
+- If several contexts exist and the correct owner is unclear, ask before writing.

package/skills/grill/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: grill
+description: Relentlessly stress-test an idea, plan, requirement, architecture, or domain model through dependency-aware interview rounds. Use when the user asks to be grilled, challenged, interviewed, or pushed toward shared understanding; when assumptions and decision branches must be exhausted before action; or when domain terminology and durable architectural decisions should be sharpened and recorded in CONTEXT.md and ADRs.
+---
+
+# Grill
+
+Interview the user until both sides share an explicit, evidence-backed understanding. Model the topic as a decision tree, research discoverable facts, challenge the domain language, and record settled terminology and durable decisions as they crystallize.
+
+Do not implement the resulting plan or design during or immediately after the grill. Capturing agreed terminology and accepted ADRs is part of the session. The skill ends after reporting the confirmed result; planning or implementation requires a separate user request.
+
+## Core distinctions
+
+- Treat a **fact** as something discoverable from the environment, artifacts, documentation, or code. Find it yourself.
+- Treat a **decision** as a choice among viable alternatives. Put it to the user with a recommendation.
+- Treat a **prerequisite** as a fact or decision that must settle before a downstream question can be answered without guessing.
+- Treat the **frontier** as every unresolved decision whose prerequisites are settled now.
+
+Never turn a discoverable fact into homework for the user. Never silently turn an unresolved decision into an assumption.
+
+## Workflow
+
+### 1. Establish the subject
+
+Restate the outcome being explored, the requested deliverable, and any explicit constraints. Mark interpretations as provisional until the user confirms them.
+
+Build a mental decision tree rooted in that outcome. Add only branches that can materially change the result, such as:
+
+- scope and non-goals
+- actors, responsibilities, and boundaries
+- domain terms and invariants
+- lifecycle, states, and failure behavior
+- data ownership and integration points
+- usability, security, performance, or operational constraints
+- trade-offs, validation, rollout, and reversibility
+
+Tailor the branches to the subject. Do not ask ceremonial questions that cannot affect a decision.
+
+### 2. Research the facts
+
+Inspect the relevant workspace, code, tests, documentation, prior decisions, and external sources before questioning the user. Distinguish direct evidence, reasonable inference, and remaining unknowns.
+
+Use read-only tools or isolated research workers when the host provides them and current instructions permit them. If research runs asynchronously, treat its result as an unsettled prerequisite: defer only the dependent questions and continue with the rest of the frontier. If delegation is unavailable, research directly.
+
+When code, documentation, and the user's statement disagree, surface the conflict with concrete evidence. Do not average contradictory models. Ask which model is authoritative and identify the losing model as cleanup or migration work when relevant.
+
+### 3. Load and challenge the domain language
+
+Look for `CONTEXT-MAP.md` and the relevant `CONTEXT.md` before inventing terminology:
+
+- If `CONTEXT-MAP.md` exists, use it to locate the applicable bounded context and its ADR directory.
+- If only a root `CONTEXT.md` exists, treat the repository as a single context.
+- If neither exists, wait until the first domain term is explicitly resolved before creating a root `CONTEXT.md`.
+
+Call out glossary conflicts immediately. Replace fuzzy or overloaded words with a proposed canonical term and ask the user to choose. Stress-test relationships and boundaries with concrete scenarios, especially edge cases that distinguish similar concepts.
+
+Do not force domain documentation into a conversation-only session or a workspace where file writes are out of scope. Keep a concise decision and terminology ledger in the conversation instead.
+
+### 4. Ask one frontier round
+
+Compute the full current frontier. Exclude:
+
+- questions answerable through research
+- questions whose prerequisites are unresolved
+- questions whose answers cannot change the outcome
+
+Ask every frontier question in one numbered round. For each question:
+
+1. State the decision precisely.
+2. Give a recommended answer and a brief reason.
+3. Present meaningful alternatives or invite a free-form answer when the choice is not bounded.
+
+Then stop and wait for the user's answers. A question that depends on another question in the same round belongs to a later round.
+
+### 5. Process answers and advance the tree
+
+After each response:
+
+1. Convert answers into explicit decisions without adding unstated meaning.
+2. Resolve contradictions or ambiguity before depending on the answer.
+3. Confirm delegated choices: when the user says "you decide," state the chosen recommendation and its trade-off, then ask the user to accept or revise it.
+4. Update the terminology and decision ledger.
+5. Recompute the tree and ask the next complete frontier round.
+
+Continue until no unresolved branch can materially affect the result. Respect an explicit request to stop or defer a branch, but record the resulting unresolved decision and its impact.
+
+## Record decisions during the grill
+
+When a project term is explicitly resolved, update the applicable `CONTEXT.md` immediately. Read and follow [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md) before the first update. Keep `CONTEXT.md` a glossary only: no implementation details, requirements, scratch notes, or architectural decisions.
+
+Offer an ADR only when all three conditions hold:
+
+1. The decision is hard or costly to reverse.
+2. The choice would be surprising without its context.
+3. Genuine alternatives were considered and rejected for specific reasons.
+
+If any condition is missing, do not create an ADR. If all three hold, ask the user whether to record it, then read and follow [ADR-FORMAT.md](./ADR-FORMAT.md). Create directories and files lazily.
+
+## Finish with a confirmed session result
+
+The grill is complete when research is settled enough for the decision, the frontier is empty, and no material branch remains silently assumed.
+
+Present a candidate shared-understanding summary containing:
+
+- objective and success criteria
+- settled decisions and their main trade-offs
+- canonical domain language
+- constraints, invariants, and explicit non-goals
+- unresolved facts, deferred decisions, and risks
+- documentation created or updated
+
+Ask the user to confirm that this is the shared understanding. If they correct or reopen anything, add the affected branches and resume the rounds.
+
+After the user confirms, show a final `Grill Result` that records the accepted objective, decisions, canonical language, constraints, non-goals, unresolved items, and documentation changes. Then stop and return control to the user. Do not create a plan, write implementation code, launch an implementation handoff, or treat confirmation as permission to act.

package/skills/grill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Grill"
+  short_description: "Challenge ideas and sharpen domain decisions"
+  default_prompt: "Use $grill to stress-test this idea until every decision is explicit."

package/skills/plan-exec/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Plan Exec"
+  short_description: "Execute implementation plans with isolated workers"
+  default_prompt: "Use $plan-exec to execute this implementation plan task by task with isolated workers and reviews."

package/skills/plan-make/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Plan Make"
+  short_description: "Create self-contained implementation plans"
+  default_prompt: "Use $plan-make to create a self-contained implementation plan for this change."

package/skills/plan-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Plan Review"
+  short_description: "Review implementation plans before execution"
+  default_prompt: "Use $plan-review to review this implementation plan for correctness, scope, testing, and project fit."