pi-orchestrator-config 4.1.5

package/prompts/create-coms-feature-manager.md

@@ -0,0 +1,186 @@
+---
+description: "Generate a coms feature-manager prompt customized for the current project"
+---
+
+## Raw Arguments
+
+```text
+$ARGUMENTS
+```
+
+# Create Coms Feature Manager Prompt
+
+> **Bug Reporting Policy:** If you encounter ANY error, unexpected behavior, or reproducible bug
+> while executing this command — DO NOT work around it silently. Ask the user:
+> "Should I create a GitHub issue for this?" Route to:
+> `myk-org/pi-config` for plugin/command spec or `myk-pi-tools` CLI issues.
+> Do not silently skip steps or apply manual fixes that hide the root cause.
+
+Generates a project-specific **coms feature manager** prompt from the template.
+The coms feature manager pattern uses pi's coms system (`coms_send`/`coms_list` — responses auto-deliver as followUp)
+to coordinate between a manager agent (reviewer) and a coder agent (implementer).
+
+## What This Creates
+
+A prompt file at `.pi/prompts/coms-feature-manager.md` in the current project that defines
+a Feature Manager role — an agent that:
+
+- Reviews and directs a coder peer via coms (inter-agent communication)
+- Owns feature quality end-to-end
+- Gates PR creation — coder cannot push without manager approval
+- Iterates: review → feedback → wait for fixes → re-review
+
+## Workflow
+
+### Step 0: Check for Existing Prompt
+
+Check if `.pi/prompts/coms-feature-manager.md` already exists in the current project.
+
+If it **does NOT exist** → proceed to Step 1.
+
+If it **exists** → ask the user using ask_user:
+
+> `.pi/prompts/coms-feature-manager.md` already exists. What do you want to do?
+
+Options:
+
+- **Update** — Re-generate from template, preserving any manual customizations where possible
+- **Overwrite** — Delete and generate fresh from template
+- **Cancel** — Keep the existing prompt, do nothing
+
+If **Update**: read the existing prompt first, then generate the new one, and merge any
+custom sections the user added (sections not in the template) into the new output.
+
+If **Overwrite**: delete the existing file and proceed from Step 1.
+
+If **Cancel**: stop and inform the user.
+
+### Step 1: Read the Template
+
+Read the template file:
+
+```text
+~/.pi/agent/git/github.com/myk-org/pi-config/templates/coms-feature-manager-prompt.md
+```
+
+This is the immutable source template. NEVER modify it.
+
+### Step 2: Analyze the Project
+
+Examine the current project to determine:
+
+1. **Test command**: Look for `Makefile` (test target), `tox.ini`, `pyproject.toml` (pytest config),
+   `package.json` (test script), or other test runners. Determine the exact command to run all tests.
+
+2. **Test locations**: Where are tests stored? (`tests/`, `test/`, `__tests__/`, `spec/`, etc.)
+
+3. **Project type**: Python, Node.js, Go, Java, etc. Determine from project files.
+
+4. **Verification approach**: Determined by user input (see Step 2.5)
+
+5. **AGENTS.md**: Does one exist? If so, note any architecture or review conventions.
+
+6. **Security concerns**: Does the project handle auth, secrets, sensitive data?
+
+### Step 2.5: Ask About Live Verification
+
+Ask the user using ask_user:
+
+> Does this project need **live/E2E verification** (deploy to dev, verify in browser/CLI, test unhappy paths)?
+
+Options:
+
+- **Yes** — Include E2E Verification AND Dev Server Operations sections
+- **No** — Remove both sections (tests are sufficient)
+
+If the user chooses **Yes**, ask a follow-up for the deploy details:
+
+> Provide deploy details (or leave empty to fill later):
+>
+> - Deploy command (e.g., `make deploy-dev`, `kubectl apply`, `docker compose up`)
+> - Dev URL (e.g., `http://localhost:8080`)
+> - Health check command (e.g., `curl -s http://localhost:8080/health`)
+> - Admin user (if applicable)
+
+If the user doesn't provide values, use `TBD` as the placeholder text (never leave `{{...}}` tokens in the output).
+
+### Step 3: Fill Placeholders
+
+Replace ALL `{{PLACEHOLDER}}` values in the template with project-specific values:
+
+| Placeholder | How to determine |
+|-------------|------------------|
+| `{{TEST_COMMAND}}` | From Makefile, tox.ini, pyproject.toml, package.json |
+| `{{TEST_LOCATIONS}}` | Scan for test directories |
+| `{{VERIFICATION_STEP}}` | Based on project type — deploy+verify or just tests |
+| `{{VERIFICATION_SIGNOFF}}` | Matching signoff line |
+| `{{ADMIN_USER}}` | From project config if applicable |
+| `{{DEV_URL}}` | From project config if applicable |
+| `{{DEPLOY_COMMAND}}` | From Makefile, scripts, or docs |
+| `{{DEPLOY_TASK}}` | Async subagent task description |
+| `{{PROJECT_DIR}}` | Current working directory |
+| `{{HEALTH_CHECK_COMMAND}}` | From project config if applicable |
+
+### Step 4: Handle Optional Sections
+
+For each section marked `[OPTIONAL]`:
+
+- **Include it** if the project has the relevant feature (deploy, E2E, security, CLI, etc.)
+- **Remove it entirely** (including the HTML comment markers) if not applicable
+- Remove the `<!-- [OPTIONAL] ... -->` comment wrappers from included sections
+- Remove the `<!-- -->` guidance comments (e.g., `<!-- Examples: ... -->`)
+
+Also remove:
+
+- The usage block at the top (between `> **Usage:**` and `---`)
+- Any remaining `<!-- ... -->` HTML comments
+
+### Step 5: Write the Output
+
+Create the directory if needed and write the customized prompt:
+
+```bash
+mkdir -p .pi/prompts
+```
+
+Write to `.pi/prompts/coms-feature-manager.md`
+
+**MANDATORY:** The output file MUST start with these exact 3 lines (the template does not include them):
+
+Line 1: `---`
+Line 2: `description: "Coms feature manager — review and direct a coder peer via inter-agent communication"`
+Line 3: `---`
+
+Do NOT include any fence markers or code block syntax — the file must start with literal `---` on line 1.
+This registers it as a `/coms-feature-manager` slash command in pi.
+
+### Step 6: Report
+
+Tell the user:
+
+> ✅ Created `.pi/prompts/coms-feature-manager.md`
+>
+> Run `/reload` to register the new `/coms-feature-manager` command.
+>
+> To use it: start a coms session, then run `/coms-feature-manager` to activate the manager role.
+> The manager will coordinate with a coder peer via coms to implement features.
+
+List the key customizations made (test command, verification approach, included/excluded sections).
+
+### Step 7: Validate the Generated Prompt (MANDATORY)
+
+After writing the file, read it back and validate against the current project:
+
+1. **No remaining placeholders** — search for `{{` in the output. If any `{{PLACEHOLDER}}` values
+   remain unfilled, either fill them now or remove the line/section they belong to.
+2. **No stale HTML comments** — search for `<!--`. All comment markers must be removed.
+3. **Test command works** — run the test command from the prompt and verify it executes
+   (it doesn't need to pass, just confirm the command is valid).
+4. **File paths are correct** — verify any hardcoded paths in the prompt exist on disk.
+5. **Sections match project** — if deploy/E2E sections are included, verify deploy commands
+   are real. If removed, verify no dangling references to deployment remain in other sections
+   (e.g., workflow steps, final sign-off).
+6. **Workflow is coherent** — read the Workflow section end-to-end and confirm every step
+   makes sense for this project. No references to features the project doesn't have.
+
+If any issues are found, fix the generated prompt and re-write it. Report what was fixed.

package/prompts/create-skill.md

@@ -0,0 +1,128 @@
+---
+description: "Create a reusable skill from a successful workflow — /create-skill <name>"
+---
+
+## Raw Arguments
+
+```text
+$ARGUMENTS
+```
+
+> **Bug Reporting Policy:** If you encounter ANY error, unexpected behavior, or reproducible bug
+> while executing this command — DO NOT work around it silently. Ask the user:
+> "Should I create a GitHub issue for this?" Route to:
+> `myk-org/pi-config` for prompt/extension issues, or to the relevant tool's repository for CLI issues.
+> Do not silently skip steps or apply manual fixes that hide the root cause.
+
+# Create Skill
+
+Save a successful workflow as a reusable pi skill.
+
+## Usage
+
+- `/create-skill <name>` — Create a skill with the given name from the current conversation
+- `/create-skill` — Prompt for a name and scope
+
+## Workflow
+
+### Step 1: Determine Skill Name
+
+If a name was provided in the raw arguments, use it. Otherwise, ask the user.
+
+The name must be:
+
+- lowercase, hyphenated (e.g., `debug-container-build`)
+- max 64 characters
+- descriptive of what the skill does
+
+Validate the name:
+
+- Must match `^[a-z][a-z0-9-]*$` (lowercase, hyphens, starts with letter)
+- No spaces, underscores, or special characters
+- If invalid, ask the user to provide a valid name
+
+### Step 1.5: Determine Skill Scope
+
+Ask the user where to create the skill:
+
+> Where should this skill be created?
+>
+> - **Global** (`~/.agents/skills/`) — available in all projects
+> - **Project** (`.pi/skills/`) — available only in this project
+
+Use `ask_user` with options: `["Global", "Project"]`
+
+Map the response to the path:
+
+- "Global" → `~/.agents/skills/`
+- "Project" → `.pi/skills/`
+
+Store the resolved path for Step 3.
+
+### Step 2: Extract the Workflow
+
+Review the current conversation and identify:
+
+- What task was accomplished
+- What steps were followed
+- What commands were run
+- What pitfalls were encountered
+- What verification was done
+
+### Step 3: Write the SKILL.md
+
+Create the skill file at the chosen location from Step 1.5:
+
+- **Global:** `~/.agents/skills/<name>/SKILL.md`
+- **Project:** `.pi/skills/<name>/SKILL.md`
+
+```bash
+mkdir -p <chosen-path>/<name>
+```
+
+The SKILL.md must follow this exact format:
+
+```markdown
+---
+name: <name>
+description: "<one-line description of what this skill does and when to use it — max 1024 chars>"
+---
+
+# <Skill Title>
+
+## When to Use
+
+- Trigger condition 1
+- Trigger condition 2
+
+## Steps
+
+1. Step one with exact commands
+2. Step two
+3. Verification step
+
+## Pitfalls
+
+- Common mistake and how to avoid it
+```
+
+**Security:** Before writing the SKILL.md, strip any secrets, API keys, tokens,
+passwords, or credentials from the workflow steps. Replace with placeholders
+like `<API_KEY>` or `$ENV_VAR`. Skills are stored in plain text.
+
+**Rules:**
+
+- **Be specific** — exact commands, exact file paths, exact verification steps
+- **No fluff** — skip background, motivation, history — just the procedure
+- **Include pitfalls** — what went wrong during this session and how it was resolved
+- **Include verification** — how to confirm each step worked
+- **One line description** — the description field is what pi uses to match skills to tasks
+
+### Step 4: Confirm
+
+Tell the user:
+
+> ✅ Skill `<name>` created at `<chosen-path>/<name>/SKILL.md`
+>
+> **Global skills** are available in all projects. **Project skills** are available only in this project.
+> Reload pi to use it immediately.

package/prompts/domain-model.md

@@ -0,0 +1,109 @@
+---
+description: Scan the codebase and build/update a CONTEXT.md domain glossary for consistent AI vocabulary
+argument-hint: "[focus area]"
+---
+
+## Raw Arguments
+
+```text
+$ARGUMENTS
+```
+
+> **Bug Reporting Policy:** If you encounter ANY error, unexpected behavior, or reproducible bug
+> while executing this command — DO NOT work around it silently. Ask the user:
+> "Should I create a GitHub issue for this?" Route to:
+> `myk-org/pi-config` for plugin/command spec or `myk-pi-tools` CLI issues.
+> Do not silently skip steps or apply manual fixes that hide the root cause.
+
+# Domain Model Command
+
+Scan the codebase, identify domain-specific terms and naming patterns, and create or update
+a `CONTEXT.md` glossary at the repository root. This gives all AI agents a shared vocabulary
+for the project — reducing verbosity and improving naming consistency.
+
+## Workflow
+
+### Phase 1: Scan the Codebase
+
+If raw arguments specify a focus area, narrow the scan to that area.
+Otherwise, scan the full codebase.
+
+Read **source code only** — TypeScript/Python files, variable/function/class/type names,
+file structure, code comments. Look for:
+
+- **Domain-specific terms** — words used in code identifiers that mean something specific
+  in this project (not general programming concepts)
+- **Naming patterns** — how the codebase names things in code (e.g., "handler" vs "controller")
+- **Overloaded terms** — same word used for different concepts in different files
+- **Inconsistent naming** — same concept called different things in different files
+- **Acronyms and abbreviations** — project-specific shorthand in code
+
+**DO NOT include:**
+
+- Operational workflows or processes (how things are done — that belongs in rules/memory)
+- Features described in README/docs (those are documentation, not vocabulary)
+- Memory system entries or session knowledge
+- Anything that isn't a term used in actual code identifiers or code comments
+
+The glossary is for **naming consistency in code** — so the AI uses the same
+identifier names the codebase uses. If a term doesn't appear as a variable name,
+function name, type name, or class name in the code, it probably doesn't belong.
+
+### Phase 2: Check Existing CONTEXT.md
+
+If `CONTEXT.md` exists at the repo root:
+
+1. Read it
+2. Cross-reference against the codebase scan — are definitions still accurate?
+3. Identify new terms that should be added
+4. Identify stale terms that no longer appear in the code
+5. Present a diff of proposed changes to the user
+
+If no `CONTEXT.md` exists, proceed to Phase 3.
+
+### Phase 3: Draft CONTEXT.md
+
+Create a draft following this format:
+
+```markdown
+# {Project Name}
+
+{One-sentence description of what this project is.}
+
+## Language
+
+**{Term}**:
+{One or two sentence definition of what it IS, not what it does.}
+
+**{Another Term}**:
+{Definition}
+_Avoid_: {alternative words people might use that would cause confusion}
+```
+
+**Rules for the glossary:**
+
+- **Keep definitions tight** — one or two sentences max
+- **Only project-specific terms** — general programming concepts don't belong
+- **Group under subheadings** when natural clusters emerge
+- **Cross-reference with code** — if the glossary says "Order", the code should use "Order"
+  not "Purchase" or "Transaction"
+- **`_Avoid_` is optional** — only add it when there's genuine ambiguity where someone
+  (human or AI) might use a different word for the same concept. For code identifiers
+  with clear names (e.g., `resolveRepoRoot`), no `_Avoid_` is needed — the name speaks
+  for itself. Use `_Avoid_` for domain concepts like "Worktree" where someone might say
+  "working copy" or "branch copy" instead.
+
+### Phase 4: Present to User
+
+Display the full draft and ask the user to review:
+
+- Approve as-is
+- Correct any definitions
+- Add missing terms
+- Remove terms that don't belong
+
+Apply corrections and write `CONTEXT.md` to the repo root.
+
+### Phase 5: Commit
+
+Stage and commit `CONTEXT.md` with message: `docs: create/update domain model glossary`