pi-feature-dev 1.3.0 → 1.5.0

package/README.md

@@ -19,8 +19,16 @@ 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
 
+```
+npx skills add https://github.com/r13v/pi-feature-dev
+```
+
 From npm:
 
 ```bash
@@ -56,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
 
@@ -79,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
@@ -100,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.3.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/SKILL.md

@@ -5,7 +5,7 @@ description: Create structured implementation plans in docs/plans/ for feature w
 
 # Implementation Plan Creation
 
-Create an implementation plan in `docs/plans/YYYYMMDD-title.md` after focused discovery and user-guided scope decisions.
+Create an implementation plan in `docs/plans/YYYYMMDD-title.md` after focused discovery and user-guided scope decisions. The plan file is the execution contract: a fresh agent must be able to execute it without reading the prior chat.
 
 ## Workflow
 
@@ -14,9 +14,10 @@ Create an implementation plan in `docs/plans/YYYYMMDD-title.md` after focused di
 3. Present a concise context summary, including likely affected areas and any uncertainty.
 4. Ask focused questions one at a time. Prefer multiple-choice questions with a recommended option when the answer can be bounded.
 5. If there are multiple viable implementation paths, present 2-3 approaches with trade-offs and recommend one. Ask the user to choose before writing the plan. Skip this only when the path is obvious or the user already specified the approach.
-6. Preserve enough context in the plan for an isolated reviewer to understand the request, decisions, assumptions, and non-goals without hidden conversation context.
+6. Preserve enough context in the plan for an isolated executor and reviewer to understand the request, decisions, assumptions, non-goals, implementation path, and verification commands without hidden conversation context.
 7. Create the plan file under `docs/plans/` using the current date and a short slug.
-8. After creating the plan, ask the user whether to review, start implementation, or stop after the plan.
+8. Before finishing, audit the plan against the Self-Contained Plan Contract below and revise until it passes.
+9. After creating the plan, ask the user whether to review, start implementation, or stop after the plan.
 
 ## Project Guidance Discovery
 
@@ -85,6 +86,31 @@ Which direction do you prefer?
 
 If repeated code is involved, explicitly compare duplication versus abstraction and ask when both are reasonable.
 
+## Self-Contained Plan Contract
+
+Every plan must be autonomous. Treat the plan as the only document available to a fresh implementation worker besides the repository itself.
+
+A self-contained plan includes:
+- The original request and the exact outcome expected.
+- Explicit assumptions, decisions, non-goals, and unresolved questions.
+- Relevant repository context discovered during planning, with concrete file paths, components, exports, APIs, commands, and patterns.
+- The selected approach and why alternatives were rejected when alternatives were considered.
+- Acceptance criteria that define when the work is complete.
+- Ordered tasks with exact files to create or modify, specific implementation actions, specific test actions, and exact validation commands.
+- Any external dependency, credential, manual step, or environment constraint required to complete or verify the work.
+
+Avoid hidden-context references:
+- Do not write "as discussed", "current behavior", "use the existing helper", "same as above", or "the relevant file" without naming the file, symbol, or behavior.
+- Do not leave placeholders such as `[command]`, `[TBD]`, `[exact/path]`, or `[if needed]` in the final plan.
+- Do not rely on future executor discovery for decisions already made during planning. If discovery is still needed, make it an explicit task with what to inspect and why.
+- Do not include speculative abstractions, future-proofing, or optional work as implementation tasks. Put external or manual follow-up in Post-Completion.
+
+Before writing the final file, verify:
+- Could a fresh agent start from this plan and the repository alone?
+- Does every task explain why it exists and how to verify it?
+- Are all referenced commands, files, and symbols concrete?
+- Are all assumptions and user decisions recorded in the plan?
+
 ## Plan Template
 
 Use this structure and adapt it to the project:
@@ -96,17 +122,21 @@ Use this structure and adapt it to the project:
 - Clear description of the feature/change.
 - Problem it solves and key benefits.
 - How it integrates with the existing system.
+- Acceptance criteria for completion.
 
 ## Context
 - Files/components involved: [list from discovery]
-- Related patterns found: [patterns discovered]
+- Related patterns found: [patterns discovered, with file paths and symbols]
 - Dependencies identified: [dependencies]
+- Relevant commands discovered: [test/lint/build commands]
+- Constraints from project guidance: [AGENTS.md/CLAUDE.md/README rules that affect this plan]
 
 ## Review Handoff
 - Original request: [user's requested outcome]
 - Key decisions made during planning: [brief bullets]
 - Explicit non-goals: [if any]
 - Open questions or assumptions: [if any]
+- Hidden context: none; this plan is self-contained for a fresh executor.
 
 ## Development Approach
 - Testing approach: [TDD / Regular]
@@ -115,11 +145,13 @@ Use this structure and adapt it to the project:
 - Every code-change task must include new or updated tests.
 - All tests for a task must pass before starting the next task.
 - Update this plan when scope changes during implementation.
+- Do not rely on chat history; decisions and constraints must be recorded here before execution.
 
 ## Testing Strategy
 - Unit tests required for every code-change task.
 - E2E tests required for UI flows when the project has an E2E setup.
 - Cover success, error, and edge cases.
+- Exact validation commands: [commands discovered during planning]
 
 ## Progress Tracking
 - Mark completed items with `[x]` immediately when done.
@@ -134,14 +166,16 @@ Use this structure and adapt it to the project:
 ## Implementation Steps
 
 ### Task 1: [specific name]
+**Why:** [reason this task is needed for the requested outcome]
+
 **Files:**
 - Create: `exact/path/to/new_file`
 - Modify: `exact/path/to/existing_file`
 
-- [ ] [specific code action with file reference]
+- [ ] [specific code action with file and symbol reference]
 - [ ] [specific test action for success cases]
 - [ ] [specific test action for error/edge cases]
-- [ ] Run relevant tests and confirm they pass before next task.
+- [ ] Run relevant tests and confirm they pass before next task
 
 ### Task N-1: Verify Acceptance Criteria
 - [ ] Verify all Overview requirements are implemented.
@@ -155,9 +189,11 @@ Use this structure and adapt it to the project:
 - [ ] Move this plan to `docs/plans/completed/`.
 
 ## Technical Details
+- Existing APIs, exports, components, or commands the implementation must use.
 - Data structures and changes.
 - Parameters and formats.
 - Processing flow.
+- Invariants and edge cases the executor must preserve.
 
 ## Post-Completion
 Items requiring manual intervention or external systems.

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."