@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.11

package/skills/create-skill/SKILL.md

@@ -0,0 +1,548 @@
+---
+name: create-skill
+description: >-
+  Create or revise a Pi skill (a directory with SKILL.md plus optional scripts,
+  references, and assets). Covers the requirements interview, placement,
+  frontmatter, agent-facing writing, progressive disclosure, common patterns,
+  a draft-test-iterate loop, and tuning the description so the skill triggers
+  when it should. Use for /create-skill, "write a skill", "turn this workflow
+  into a skill", or editing an existing SKILL.md.
+---
+
+# Create a skill
+
+A skill is a directory whose `SKILL.md` holds YAML frontmatter and instructions for an agent. Pi lists a skill's name, description, and path in the system prompt and loads the body only when a task calls for it, or when the user types `/skill:<name>`.
+
+## Before you begin: gather requirements
+
+Before creating a skill, gather this from the user:
+
+1. **Purpose and scope.** What specific task or workflow should this skill help with?
+2. **Target location.** Personal (`~/.pi/agent/skills/`), project (`.pi/skills/`), or packaged (`skills/` inside a Pi package)?
+3. **Trigger scenarios.** When should the agent automatically apply this skill?
+4. **Key domain knowledge.** What specialized information does the agent need that it would not already know?
+5. **Output format preferences.** Are there specific templates, formats, or styles required?
+6. **Existing patterns.** Are there existing examples or conventions to follow?
+
+### Verbatim text from the user
+
+If the user includes exact wording to use in the skill, respect it and use it **verbatim** in `SKILL.md` (same words, same order). Do not paraphrase, soften, or expand their copy, and do not add unrequested headings or commentary around it.
+
+### Inferring from context
+
+If you have previous conversation context, infer the skill from what was discussed. You can create skills based on workflows, patterns, or domain knowledge that emerged in the conversation.
+
+### Gathering additional information
+
+If you need clarification, use the AskQuestion tool when available:
+
+```
+Example AskQuestion usage:
+- "Where should this skill be stored?" with options like ["Personal (~/.pi/agent/skills/)", "Project (.pi/skills/)"]
+- "Should this skill include executable scripts?" with options like ["Yes", "No"]
+```
+
+If the AskQuestion tool is not available, ask these questions conversationally.
+
+---
+
+## Skill file structure
+
+### Directory layout
+
+Skills are stored as directories containing a `SKILL.md` file:
+
+```
+skill-name/
+├── SKILL.md              # Required - main instructions
+├── references/           # Optional - detailed documentation the agent reads on demand
+│   └── reference.md
+├── examples.md           # Optional - usage examples (or under references/)
+└── scripts/              # Optional - utility scripts
+    ├── validate.py
+    └── helper.sh
+```
+
+### Storage locations
+
+| Type | Path | Scope |
+|------|------|-------|
+| Personal | `~/.pi/agent/skills/<name>/` (respect `PI_CODING_AGENT_DIR` when set) | Available in every project on this machine |
+| Project | `.pi/skills/<name>/`, or `.agents/skills/<name>/` for other Agent Skills hosts | Shared with anyone using the repository |
+| Packaged | `skills/<name>/` inside a Pi package | Ships with the package (`pi install`) |
+
+**IMPORTANT.** Never write personal or project skills into a Pi package's `skills/` tree unless the user is editing that package on purpose. Packaged skills are owned by the package maintainer.
+
+Before creating a new skill, search the existing skills for one that already covers the job. Extend it instead of adding an overlap.
+
+### SKILL.md structure
+
+Every skill requires a `SKILL.md` file with YAML frontmatter and markdown body:
+
+```markdown
+---
+name: your-skill-name
+description: Brief description of what this skill does and when to use it
+disable-model-invocation: true
+---
+
+# Your skill name
+
+## Instructions
+Clear, step-by-step guidance for the agent.
+
+## Examples
+Concrete examples of using this skill.
+```
+
+Default `disable-model-invocation: true` so the skill only loads when named explicitly (`/skill:<name>` or an explicit handoff). Omit it only when the agent should auto-invoke from ambient context.
+
+### Required metadata fields
+
+| Field | Requirements | Purpose |
+|-------|--------------|---------|
+| `name` | Max 64 chars, lowercase letters/numbers/hyphens only. Must match the directory name. | Unique identifier for the skill |
+| `description` | Max 1024 chars, non-empty. One YAML scalar. | Helps the agent decide when to apply the skill |
+
+`name` and `description` are required. Pi skips a skill without a description.
+
+Quote the description, or use `description: >-` with indented continuation lines, when it contains `: `, a leading special character, or line breaks.
+
+Other Agent Skills fields are `license`, `compatibility`, `metadata` (a key-value map), and `allowed-tools`. Put host-specific fields under `metadata`.
+
+---
+
+## Writing effective descriptions
+
+The description is **critical** for skill discovery. The agent uses it to decide when to apply your skill. It is the only text the model sees before deciding to load the body.
+
+### Description best practices
+
+1. **Write in third person** (the description is injected into the system prompt):
+   - Good: "Processes Excel files and generates reports"
+   - Avoid: "I can help you process Excel files"
+   - Avoid: "You can use this to process Excel files"
+
+2. **Be specific and include trigger terms**:
+   - Good: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
+   - Vague: "Helps with documents"
+
+3. **Include both WHAT and WHEN**:
+   - WHAT: What the skill does (specific capabilities)
+   - WHEN: When the agent should use it (trigger scenarios)
+
+### Description examples
+
+```yaml
+# PDF processing
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+
+# Excel analysis
+description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
+
+# Git commit helper
+description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
+
+# Code review
+description: Review code for quality, security, and best practices following team standards. Use when reviewing pull requests, code changes, or when the user asks for a code review.
+```
+
+### Tune the description (trigger loop)
+
+Use this loop when a skill exists but does not trigger, or triggers on the wrong requests.
+
+1. Write five prompts that should trigger it and five near misses that should not.
+2. For each prompt, run a fresh session with the skill discoverable and check whether the agent read the skill's `SKILL.md`.
+3. Rewrite the description to name the missing triggers and to exclude the near misses. Keep it one scalar.
+4. Repeat until both sets behave. Skills with `disable-model-invocation: true` never auto-trigger, so this loop does not apply to them.
+
+---
+
+## Core authoring principles
+
+### 1. Concise is key
+
+The context window is shared with conversation history, other skills, and requests. Every token competes for space.
+
+**Default assumption.** The agent is already very smart. Only add context it does not already have.
+
+Challenge each piece of information:
+- "Does the agent really need this explanation?"
+- "Can I assume the agent knows this?"
+- "Does this paragraph justify its token cost?"
+
+**Good (concise):**
+```markdown
+## Extract PDF text
+
+Use pdfplumber for text extraction:
+
+\`\`\`python
+import pdfplumber
+
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+\`\`\`
+```
+
+**Bad (verbose):**
+```markdown
+## Extract PDF text
+
+PDF (Portable Document Format) files are a common file format that contains
+text, images, and other content. To extract text from a PDF, you'll need to
+use a library. There are many libraries available for PDF processing, but we
+recommend pdfplumber because it's easy to use and handles most cases well...
+```
+
+### 2. Keep SKILL.md under 500 lines
+
+For optimal performance, the main SKILL.md file should be concise. Use progressive disclosure for detailed content.
+
+### 3. Progressive disclosure
+
+Put essential information in SKILL.md. Put detailed reference material in separate files that the agent reads only when needed.
+
+```markdown
+# PDF processing
+
+## Quick start
+[Essential instructions here]
+
+## Additional resources
+- For complete API details, see \`references/api.md\`
+- For usage examples, see \`examples.md\`
+```
+
+**Keep references one level deep.** Link directly from SKILL.md to reference files. Deeply nested references may result in partial reads.
+
+Use paths relative to the skill directory for bundled files. Pi tells the agent where the skill lives.
+
+### 4. Set appropriate degrees of freedom
+
+Match specificity to the task's fragility:
+
+| Freedom level | When to use | Example |
+|---------------|-------------|---------|
+| **High** (text instructions) | Multiple valid approaches, context-dependent | Code review guidelines |
+| **Medium** (pseudocode/templates) | Preferred pattern with acceptable variation | Report generation |
+| **Low** (specific scripts) | Fragile operations, consistency critical | Database migrations |
+
+### 5. Write the body for an agent reader
+
+- Start with what the skill produces, then the steps in order. One instruction per sentence.
+- Give exact commands, paths, and file names.
+- Encode a rule that must always hold as a script, check, or lint the skill runs. Prose alone is a request, not a guarantee.
+- Cut anything the agent already knows. Keep the body short enough to read in full before acting.
+
+---
+
+## Common patterns
+
+### Template pattern
+
+Provide output format templates:
+
+```markdown
+## Report structure
+
+Use this template:
+
+\`\`\`markdown
+# [Analysis title]
+
+## Executive summary
+[One-paragraph overview of key findings]
+
+## Key findings
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+
+## Recommendations
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+\`\`\`
+```
+
+### Examples pattern
+
+For skills where output quality depends on seeing examples:
+
+```markdown
+## Commit message format
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+\`\`\`
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+\`\`\`
+
+**Example 2:**
+Input: Fixed bug where dates displayed incorrectly
+Output:
+\`\`\`
+fix(reports): correct date formatting in timezone conversion
+
+Use UTC timestamps consistently across report generation
+\`\`\`
+```
+
+### Workflow pattern
+
+Break complex operations into clear steps with checklists:
+
+```markdown
+## Form filling workflow
+
+Copy this checklist and track progress:
+
+\`\`\`
+Task progress:
+- [ ] Step 1: Analyze the form
+- [ ] Step 2: Create field mapping
+- [ ] Step 3: Validate mapping
+- [ ] Step 4: Fill the form
+- [ ] Step 5: Verify output
+\`\`\`
+
+**Step 1: Analyze the form**
+Run: \`python scripts/analyze_form.py input.pdf\`
+...
+```
+
+### Conditional workflow pattern
+
+Guide through decision points:
+
+```markdown
+## Document modification workflow
+
+1. Determine the modification type:
+
+   **Creating new content?** Follow "Creation workflow" below.
+   **Editing existing content?** Follow "Editing workflow" below.
+
+2. Creation workflow:
+   - Use docx-js library
+   - Build document from scratch
+   ...
+```
+
+### Feedback loop pattern
+
+For quality-critical tasks, implement validation loops:
+
+```markdown
+## Document editing process
+
+1. Make your edits
+2. **Validate immediately**: \`python scripts/validate.py output/\`
+3. If validation fails:
+   - Review the error message
+   - Fix the issues
+   - Run validation again
+4. **Only proceed when validation passes**
+```
+
+---
+
+## Utility scripts
+
+Pre-made scripts offer advantages over generated code:
+- More reliable than generated code
+- Save tokens (no code in context)
+- Save time (no code generation)
+- Ensure consistency across uses
+
+```markdown
+## Utility scripts
+
+**analyze_form.py**: Extract all form fields from PDF
+\`\`\`bash
+python scripts/analyze_form.py input.pdf > fields.json
+\`\`\`
+
+**validate.py**: Check for errors
+\`\`\`bash
+python scripts/validate.py fields.json
+# Returns: "OK" or lists conflicts
+\`\`\`
+```
+
+Make clear whether the agent should **execute** the script (most common) or **read** it as reference. Prefer `bash` for running scripts. Prefer `read`, `grep`, and `find` when inspecting skill files.
+
+---
+
+## Anti-patterns to avoid
+
+### 1. Windows-style paths
+- Use: `scripts/helper.py`
+- Avoid: `scripts\helper.py`
+
+### 2. Too many options
+```markdown
+# Bad - confusing
+"You can use pypdf, or pdfplumber, or PyMuPDF, or..."
+
+# Good - provide a default with escape hatch
+"Use pdfplumber for text extraction.
+For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
+```
+
+### 3. Time-sensitive information
+```markdown
+# Bad - will become outdated
+"If you're doing this before August 2025, use the old API."
+
+# Good - use an "old patterns" section
+## Current method
+Use the v2 API endpoint.
+
+## Old patterns (deprecated)
+<details>
+<summary>Legacy v1 API</summary>
+...
+</details>
+```
+
+### 4. Inconsistent terminology
+Choose one term and use it throughout:
+- Always "API endpoint" (not mixing "URL", "route", "path")
+- Always "field" (not mixing "box", "element", "control")
+
+### 5. Vague skill names
+- Good: `processing-pdfs`, `analyzing-spreadsheets`
+- Avoid: `helper`, `utils`, `tools`
+
+---
+
+## Skill creation workflow
+
+When helping a user create a skill, follow this process.
+
+### Phase 1: Discovery
+
+Gather information about:
+1. The skill's purpose and primary use case
+2. Storage location (personal vs project vs packaged)
+3. Trigger scenarios
+4. Any specific requirements or constraints
+5. Existing examples or patterns to follow
+
+If you have access to the AskQuestion tool, use it for efficient structured gathering. Otherwise, ask conversationally.
+
+### Phase 2: Design
+
+1. Draft the skill name (lowercase, hyphens, max 64 chars, matches directory)
+2. Write a specific, third-person description
+3. Outline the main sections needed
+4. Identify if supporting files or scripts are needed
+
+### Phase 3: Implementation
+
+1. Create the directory structure
+2. Write the SKILL.md file with frontmatter (`write` for new files, `edit` for revisions)
+3. Create any supporting reference files
+4. Create any utility scripts if needed
+
+### Phase 4: Draft, test, iterate
+
+1. Draft the skill in place.
+2. Load it: start Pi where the skill is discoverable, or run `pi --skill <dir>`. Fix every startup diagnostic.
+3. Run it on two or three realistic tasks with `/skill:<name> <task>` in a fresh session, for example `pi -p --no-session "/skill:<name> <task>"`. Read what the agent actually did, not its summary.
+4. Note each place it skipped a step, guessed, or went off course. Tighten the instruction that allowed it, then rerun the same tasks.
+5. Stop when the runs follow the skill without help. Run `/reload` in open sessions after edits.
+
+### Phase 5: Verification
+
+1. Verify the SKILL.md is under 500 lines
+2. Check that the description is specific and includes trigger terms
+3. Ensure consistent terminology throughout
+4. Verify all file references are one level deep
+5. Confirm the skill loads with no diagnostics after `/reload`
+6. Report the path, the frontmatter, what each run showed, and anything left to tune
+
+---
+
+## Complete example
+
+Here's a complete example of a well-structured skill:
+
+**Directory structure:**
+```
+code-review/
+├── SKILL.md
+├── references/
+│   └── STANDARDS.md
+└── examples.md
+```
+
+**SKILL.md:**
+```markdown
+---
+name: code-review
+description: Review code for quality, security, and maintainability following team standards. Use when reviewing pull requests, examining code changes, or when the user asks for a code review.
+---
+
+# Code review
+
+## Quick start
+
+When reviewing code:
+
+1. Check for correctness and potential bugs
+2. Verify security best practices
+3. Assess code readability and maintainability
+4. Ensure tests are adequate
+
+## Review checklist
+
+- [ ] Logic is correct and handles edge cases
+- [ ] No security vulnerabilities (SQL injection, XSS, etc.)
+- [ ] Code follows project style conventions
+- [ ] Functions are appropriately sized and focused
+- [ ] Error handling is comprehensive
+- [ ] Tests cover the changes
+
+## Providing feedback
+
+Format feedback as:
+- **Critical**: Must fix before merge
+- **Suggestion**: Consider improving
+- **Nice to have**: Optional enhancement
+
+## Additional resources
+
+- For detailed coding standards, see \`references/STANDARDS.md\`
+- For example reviews, see \`examples.md\`
+```
+
+---
+
+## Summary checklist
+
+Before finalizing a skill, verify:
+
+### Core quality
+- [ ] Description is specific and includes key terms
+- [ ] Description includes both WHAT and WHEN
+- [ ] Written in third person
+- [ ] SKILL.md body is under 500 lines
+- [ ] Consistent terminology throughout
+- [ ] Examples are concrete, not abstract
+
+### Structure
+- [ ] File references are one level deep
+- [ ] Progressive disclosure used appropriately
+- [ ] Workflows have clear steps
+- [ ] No time-sensitive information
+- [ ] Placement is personal, project, or packaged as intended
+
+### If including scripts
+- [ ] Scripts solve problems rather than punt
+- [ ] Required packages are documented
+- [ ] Error handling is explicit and helpful
+- [ ] No Windows-style paths

package/skills/create-verification-skill/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: create-verification-skill
+description: "Generate a project-local verification skill that drives your app the way a user does — any language, framework, or platform. Use for /create-verification-skill, \"make a control skill for this repo\", or when a project has no scripted way to prove UI/CLI/service behavior."
+disable-model-invocation: true
+---
+
+# Create a verification skill
+
+Every serious project needs a scripted way to drive the real app and prove behavior: launch it, exercise a feature the way a user would, and capture evidence. This skill generates that as a project-local skill (`.pi/skills/verify-<app>/`) tailored to the repo. You write the generator's output for the next agent, not for a human: it will be read cold, mid-task, by an agent that has never seen the app.
+
+## 1. Interview the repo, not the user
+
+Answer these from the codebase and only ask the user what you cannot observe:
+
+- **Surface:** what does a user actually touch? A web UI, a CLI/TUI, a desktop app, an API, a mobile app, a library? A repo can have several; pick the primary one and note the rest.
+- **Run:** how does the app start locally? Prefer the repo's own documented dev command (package scripts, Makefile, README quickstart). Note ports, env vars, seed data, auth.
+- **Drive:** how can an agent interact with it programmatically? Existing harnesses first — Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port. Only then pick a generic recipe: browser/CDP for web and Electron, a tmux/PTY harness for CLI/TUI, plain HTTP for services.
+- **Observe:** what evidence can be captured? Screenshots, terminal transcripts, response bodies, logs, exit codes, DB state.
+- **Isolate:** can two instances run side by side (ports, data dirs, profiles)? If not, say so in the generated skill: refusing to double-drive a shared instance beats corrupting the user's session.
+
+If the checkout doesn't build or start as-is, fix that first (or report it precisely) before generating; a skill written against a broken base teaches wrong steps. When an irrelevant missing asset blocks startup (a static dir the API never serves, a sample config), the generated skill may create it, clearly marked as verification scaffolding, and remove it in cleanup.
+
+## 2. Generate the skill
+
+Write `.pi/skills/verify-<app>/SKILL.md` with YAML frontmatter (`name: verify-<app>` and a `description` that names the app, the surface, and when to reach for it — without frontmatter the skill never registers) and these sections, each grounded in what the interview actually found (no placeholders left):
+
+- **Launch:** the exact command that starts the app for verification, and how to tell it's ready (a log line, a prompt). Launch must reach a usable state from an empty data dir, including any migrations and seed data. Ready means usable, not just that a process answers. A database health check can pass while its init scripts are still running. Include teardown. For a short-lived CLI or TUI there is no server to keep alive: launch means build the binary (or install deps) once, then start each drive in its own isolated PTY or tmux session.
+- **Doctor:** one read-only check that answers "is this instance worth driving?" — process up, right version/build, port owned by us, auth valid. An agent runs this first whenever anything looks off.
+- **Drive:** the harness recipe with real selectors/commands from this repo, not examples. Prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order.
+- **Evidence:** what to capture for a proof and where it goes. State the proof standards: exercise the real user path, not internal setters or test-only endpoints; capture the action and the resulting state, not just the final screen; verify side effects (files written, rows inserted, messages sent) alongside what's visible; mocks only where a production boundary already isolates the external system. When the safe path is a dry-run or test mode, verify what it actually skips by observing (files, network, git refs) rather than trusting its name: some dry-runs still touch the network or open a browser.
+- **Cleanup:** how to tear down instances the run created. Never kill by process name; kill what you started. Cleanup removes instances and scratch state, never the evidence: proof artifacts survive the teardown, in a location the skill names.
+- **Helpers:** any script the skill ships is executable and its invocation is shown in the skill body. A helper the reader has to reverse-engineer is not a helper.
+
+## 3. Seed the feature map
+
+Create `.pi/skills/verify-<app>/features/README.md` plus one file per user-facing feature you can identify (aim for the top 3-5 to start, from routes, commands, menus, or docs). Follow the shape in [`references/feature-map-example/`](references/feature-map-example/), with a README index and one file per feature. Each file answers, from the user's point of view: what the feature is, how to reach it, how to drive it with the harness, and what observable end state proves it works. The four H2s are `Sub-features`, `How to get to it (user POV)`, `Driving it with <harness>`, and `Gotchas`. If the seed data lacks a precondition that a journey needs, the journey reports a failure and the reason goes in that feature's `Gotchas`. Never weaken the journey to make it pass. The map is the repo's maintained verification source; a proof that drives one convenient entry point is incomplete when the map lists others.
+
+## 4. Prove the generated skill before handing it over
+
+Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough; the map exists so later runs can cover the rest), capture evidence, clean up. After cleanup, confirm the evidence still exists at the named location — a cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable. If you proved it in a stand-in for the real target (a container in place of a fresh VM, a local stack in place of a remote one), list every setup step the stand-in did that the target will not. Those steps stay unverified until a run on the real target covers them.
+
+## 5. Offer the maintenance loop
+
+Point the user at `/maintain-verification-skill` for keeping the map honest as the app changes. Suggest a cadence only if they ask.

package/skills/create-verification-skill/references/feature-map-example/README.md

@@ -0,0 +1,47 @@
+# Notes verification map
+
+This directory is the maintained source for verifying the user-facing behavior of Notes. Read the index before driving the app, then use the matching feature file as the recipe.
+
+## Baseline preconditions
+
+- Launch Notes at `http://127.0.0.1:4173` with a disposable data directory.
+- Set `NOTES_DATA_DIR=/tmp/notes-verify-$RUN_ID` so concurrent runs do not share state.
+- Seed notes titled `Quarterly plan` and `Grocery list`.
+- Put `control-notes` and the `notes` CLI on `PATH`.
+- Run `control-notes doctor` and require the expected URL, data directory, and build revision.
+- Never drive an instance that was not started by this verification run.
+
+## Driving conventions
+
+- Start every recipe from the baseline state unless its preconditions say otherwise.
+- Prefer ARIA roles and accessible names over CSS selectors or DOM position.
+- Treat every command as literal. Keep quoted names and flags unchanged.
+- Run browser actions through `control-notes browser`.
+- Run terminal actions through `control-notes cli -- <command>`.
+- Restore seeded data after a mutation. Do not remove proof artifacts during cleanup.
+
+## Proof and skip reporting
+
+- Capture the user action and the resulting state, not only the final screen.
+- UI proof includes an ARIA snapshot and a screenshot with the app identity visible.
+- CLI proof includes the command, stdout, stderr, and exit code.
+- Mutation proof includes a read-only second view of the stored value.
+- Record the feature ID and entry point used with every artifact.
+- Report an unreachable path with the attempted command and the unmet precondition.
+- Do not report a skipped entry point as verified through a different path.
+
+## Feature entry contract
+
+Each feature file starts with an H1 title and one paragraph describing the user-visible behavior. It then uses exactly four H2 sections in this order.
+
+1. `Sub-features` lists short IDs with one line for each behavior.
+2. `How to get to it (user POV)` lists every user entry point.
+3. `Driving it with <harness>` starts with `Preconditions:` and uses labeled bullets that pair each user action with an exact command and observable result.
+4. `Gotchas` lists traps that can waste or invalidate a verification run.
+
+Keep implementation details out of the map. Name only user paths, stable handles, required state, commands, and observable proof.
+
+## Features
+
+- [Create a note](./create-note.md) covers browser and CLI creation, cancellation, persistence, and cleanup.
+- [Search notes](./search.md) covers toolbar, keyboard, and CLI search with matching, empty, and clear states.

package/skills/create-verification-skill/references/feature-map-example/create-note.md

@@ -0,0 +1,39 @@
+# Create a note
+
+Create note lets a user save a titled note from the browser or CLI, cancel an unfinished draft, and confirm the saved note from a second user-facing view.
+
+## Sub-features
+
+- `create-open` opens a blank editor from each browser entry point.
+- `create-save` persists a title and body.
+- `create-cancel` discards an unfinished browser draft.
+- `create-cli` creates the same note shape from the terminal.
+
+## How to get to it (user POV)
+
+- Choose the `New note` button in the browser toolbar.
+- Press `n` in the browser while focus is outside an editable field.
+- Run `notes create --title <title> --body <body>` in a terminal.
+
+## Driving it with control-notes
+
+Preconditions:
+
+- Notes is healthy at `http://127.0.0.1:4173`.
+- No note is titled `Release checklist`.
+- `control-notes doctor` reports the expected URL and disposable data directory.
+
+- **Open editor.** Choose `New note`. Run `control-notes browser click --role button --name "New note"`. A form named `Note editor` appears with focus in the `Title` textbox.
+- **Enter content.** Type the title and body. Run `control-notes browser fill --role textbox --name "Title" --value "Release checklist"` and `control-notes browser fill --role textbox --name "Body" --value "Tag and publish"`. The `Save note` button becomes enabled.
+- **Save note.** Choose `Save note`. Run `control-notes browser click --role button --name "Save note"`. A status named `Note saved` appears and the heading reads `Release checklist`.
+- **Confirm persistence.** Return to the note list and reopen the note. Run `control-notes browser click --role link --name "All notes"` and `control-notes browser click --role link --name "Release checklist"`. The editor shows both saved values.
+- **Cancel draft.** Open a new note, enter `Discard me`, and choose `Cancel`. Run `control-notes browser click --role button --name "New note"`, `control-notes browser fill --role textbox --name "Title" --value "Discard me"`, and `control-notes browser click --role button --name "Cancel"`. The note list returns and has no `Discard me` link.
+- **CLI entry.** Create a second note. Run `control-notes cli -- notes create --title "CLI note" --body "Created from terminal" --format json`. Exit code `0` and stdout contain the new note ID and title.
+- **Proof.** Reopen both saved notes from `All notes`. Run `control-notes browser snapshot --aria --path artifacts/create-note/list.aria.txt` and `control-notes browser screenshot --path artifacts/create-note/list.png`. The artifacts show `Release checklist` and `CLI note`.
+
+## Gotchas
+
+- Pressing `n` while a textbox has focus types the character instead of opening a new editor.
+- Titles are trimmed on save. Assert the rendered title, not the draft input value.
+- A save status alone is insufficient proof. Reopen the note from the list.
+- Remove `Release checklist` and `CLI note` during fixture cleanup, but retain their proof artifacts.