pi-feature-dev 1.6.0 → 1.7.0

package/README.md

@@ -73,6 +73,7 @@ versions came from:
 - [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)
 - [danyuchn/asd-ste100-skill](https://github.com/danyuchn/asd-ste100-skill)
+- [AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish/tree/main/skills/simple-english)
 
 ## Usage
 
@@ -139,8 +140,9 @@ The `ste` skill selects one of two modes:
 - **STE clarity** transfers the same clarity discipline to other technical
   text without claiming formal ASD-STE100 compliance.
 
-The skill loads its detailed writing rules and before/after examples only when
-they are relevant to the request. Standard provenance and source links stay in
+The skill loads its detailed writing rules, review checklist, text-type
+patterns, and before/after examples only when they are relevant to the request.
+Standard provenance, design references, and source links stay in
 `skills/ste/README.md`, outside the agent's writing context.
 
 ## Package contents
@@ -172,6 +174,8 @@ pi-feature-dev/
         ├── agents/openai.yaml
         ├── references/
         │   ├── before-after.md
+        │   ├── checklist.md
+        │   ├── use-cases.md
         │   └── writing-rules.md
         ├── README.md
         └── SKILL.md

package/package.json

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

package/skills/ste/README.md

@@ -9,6 +9,9 @@ This project skill applies ASD-STE100 Simplified Technical English principles to
 
 The skill is Markdown-only and has no runtime or tool dependency.
 
+Its agent-facing instructions stay compact. Detailed writing rules, review checklists, text-type
+patterns, and examples are separate references that the agent loads only when a task needs them.
+
 ## Standard Baseline
 
 The skill uses ASD-STE100 Simplified Technical English, Issue 9, dated 2025-01-15.
@@ -32,3 +35,13 @@ not as a compliant or certified document.
 
 ASD owns the copyright and trademarks for ASD-STE100. Do not copy the official dictionary or
 extended passages without permission.
+
+## Design References
+
+The skill design also incorporates ideas from these open-source implementations:
+
+- [danyuchn/asd-ste100-skill](https://github.com/danyuchn/asd-ste100-skill)
+- [AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish/tree/main/skills/simple-english)
+
+This project keeps its own conservative verification boundary. External checklists and examples
+do not establish formal STE compliance.

package/skills/ste/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ste
-description: Draft, rewrite, and review clear, unambiguous English with ASD-STE100 Simplified Technical English Issue 9 principles. Use for technical procedures, safety instructions, descriptions, prompts, agent-to-agent instructions, tool descriptions, error messages, status reports, translation-ready text, controlled English, terminology normalization, and STE compliance reviews. Support strict STE verification when the official dictionary and project glossary are available; otherwise produce an STE-aligned or STE-style result without claiming compliance.
+description: Draft, rewrite, and review clear, unambiguous English with ASD-STE100 Simplified Technical English Issue 9 principles. Use for READMEs, runbooks, procedures, safety instructions, API and tool documentation, prompts, agent instructions, UI and error messages, status and incident reports, release notes, support text, translation-ready content, terminology normalization, controlled English, and STE compliance reviews. Also use when asked to simplify or de-slop English, help non-native readers, or prepare text for translation. Support strict verification only with the official dictionary and project glossary; otherwise report an STE-aligned or STE-style result.
 ---
 
 # STE
@@ -29,6 +29,10 @@ status reports, translation-ready text, and other technical or operational Engli
 
 - Read [references/writing-rules.md](references/writing-rules.md) for strict STE work, compliance
   reviews, safety text, word-count decisions, or rule details.
+- Read [references/checklist.md](references/checklist.md) for strict reviews, audits, high-risk
+  text, or long documents. Use its quick check or full check as the task requires.
+- Read [references/use-cases.md](references/use-cases.md) when the text type needs a clear
+  information order or a reusable structure.
 - Read [references/before-after.md](references/before-after.md) when rewriting dense text,
   explaining changes, or producing a comparison.
 - Read all user-supplied glossaries, safety policies, style guides, and regulatory directives that
@@ -51,6 +55,18 @@ Do not invent missing facts. Do not remove precision only to meet a length targe
 Keep a qualitative modifier such as `carefully` when it affects task intent. Flag it when the
 project requires a measurable criterion, but do not invent that criterion.
 
+## Protect Untouchable Text
+
+Unless the user explicitly asks to edit the exact literal, do not change:
+
+- Code blocks, inline code, identifiers, placeholders, and data values.
+- CLI commands, flags, file paths, URLs, and protocol elements.
+- Product, API, configuration, database, and schema names.
+- Quoted UI labels, error strings, log text, and externally defined messages.
+
+Rewrite the sentence around an untouchable literal when necessary. Never silently normalize the
+literal itself.
+
 ## Apply the Core Discipline
 
 | Area | Apply |
@@ -81,6 +97,18 @@ project requires a measurable criterion, but do not invent that criterion.
 
 If the input is already clear and meets the applicable rules, say so. Do not force a rewrite.
 
+## Self-check Before Delivery
+
+Always confirm that:
+
+1. The revision preserves every fact, condition, limit, unit, exception, sequence, and
+   responsibility.
+2. Untouchable text is unchanged unless the user requested that exact change.
+3. Each procedural sentence has one independent action unless actions occur at the same time.
+4. Actors, referents, conditions, results, and terminology are unambiguous and consistent.
+5. The result uses the correct mode, verification status, and unresolved checks.
+6. Each cited rule number was verified directly against the authoritative standard.
+
 ## Choose the Output
 
 For a direct drafting or rewriting request:
@@ -103,6 +131,10 @@ After the table, give the complete revised text. Group unresolved items as:
 
 Use the user's requested format when it conflicts with these defaults.
 
+Name the applicable rule area in explanations. Cite an Issue 9 rule number only after you verify
+that number in the official standard or an authoritative copy supplied by the user. Do not infer
+rule numbers from memory, summaries, or another skill.
+
 ## State Verification Honestly
 
 Use one of these statuses only when a status is useful:

package/skills/ste/references/checklist.md

@@ -0,0 +1,95 @@
+# STE Review Checklist
+
+Use this checklist as an operational review aid. It is not a replacement for the official
+ASD-STE100 standard or dictionary. A search result identifies text to inspect; it does not prove
+that the text violates a rule.
+
+## Quick Check
+
+Use this check for a general clarity rewrite:
+
+- Compare the source and revision. Preserve facts, conditions, limits, units, exceptions,
+  sequence, and responsibility.
+- Confirm that code, identifiers, commands, paths, labels, quoted messages, and other protected
+  literals did not change.
+- Use explicit actors, referents, conditions, actions, and results.
+- Put a prerequisite condition before the action that depends on it.
+- Keep one independent action in each procedural sentence unless actions occur at the same time.
+- Use one term for one concept and one wording for one repeated action.
+- Separate observed facts, possible causes, and recovery actions.
+- Report unresolved technical, lexical, safety, or regulatory questions.
+
+## Full Check
+
+Use this check for strict STE work, compliance reviews, safety text, high-risk content, or long
+documents.
+
+### 1. Meaning and Scope
+
+- Make an inventory of actions, facts, conditions, negation, quantities, units, limits,
+  exceptions, warnings, consequences, and cross-references.
+- Confirm the scope of each modifier and logical connector.
+- Confirm that the revision does not add a cause, risk level, requirement, or technical fact.
+
+### 2. Vocabulary and Terminology
+
+- Verify each general word against the official Issue 9 dictionary.
+- Verify its approved meaning, part of speech, form, and use.
+- Verify each technical noun and technical verb against the applicable category and project
+  glossary.
+- Record unverified terms instead of assuming that they are approved.
+- Check abbreviations, spelling, and alternate names for the same concept.
+
+### 3. Grammar and Sentences
+
+- Check active voice, permitted verb forms, articles, complete constructions, and explicit
+  referents.
+- Inspect each `-ing` form, passive construction, modal verb, and multi-word verb in context.
+- Split overloaded sentences and complex alternatives.
+- Confirm that connecting words show the intended logical relation.
+
+### 4. Procedures and Descriptions
+
+- Classify each section as a procedure, description, safety instruction, or mixed content.
+- For procedures, use imperative commands and put prerequisite conditions first.
+- For descriptions, present information gradually and keep one topic in each paragraph.
+- Put complex sequences and alternatives in vertical lists.
+
+### 5. Length and Mechanics
+
+- Apply the Issue 9 word-count method.
+- Check the 20-word procedure limit and the 25-word description limit.
+- Check the six-sentence description-paragraph limit.
+- Inspect semicolons, parentheses, hyphens, and long multi-word nouns.
+
+### 6. Safety
+
+- Preserve the governing safety label and required wording.
+- Start with the required command or condition.
+- State only the known risk or possible result.
+- Confirm that simplification did not weaken the safety intent.
+
+### 7. Delivery
+
+- Apply project, regulatory, and customer directives before general STE preferences.
+- Use the correct verification status.
+- List unresolved checks.
+- Cite a rule number only after direct verification in an authoritative copy of Issue 9.
+
+## Search Cues
+
+Search for these features during a large review:
+
+- Contractions such as `can't`, `don't`, `'re`, and `'ve`.
+- Semicolons.
+- `-ing` forms.
+- Perfect or continuous auxiliary constructions.
+- Forms of `be` followed by a past participle.
+- Modal verbs such as `should`, `would`, `may`, `might`, and `could`.
+- Vague referents such as `it`, `this`, `that`, `they`, and `which`.
+- `and` or `then` between commands.
+- Different nouns or verbs that might name the same concept or action.
+- Sentences and description paragraphs above their applicable limits.
+
+Inspect each match in context. Do not treat every `if`, `when`, `-ing` form, passive construction,
+modal verb, or repeated connector as an automatic violation.

package/skills/ste/references/use-cases.md

@@ -0,0 +1,95 @@
+# Text-Type Patterns
+
+Use these patterns when the source does not already have a required structure. They describe
+useful information order, not additional ASD-STE100 rules. Preserve the user's requested format
+and all protected literals.
+
+## Procedure or Runbook
+
+Present information in this order:
+
+1. Prerequisite conditions and applicable safety instructions.
+2. One command for each independent action.
+3. Expected result, when the reader must verify it.
+4. Recovery or escalation action, when the source supplies one.
+
+Do not move a command into a note. Do not invent missing steps or sequence.
+
+## Error Message
+
+Include only the fields that are known:
+
+1. What failed.
+2. Why it failed.
+3. What effect the failure has.
+4. What the user can do next.
+5. A stable identifier or context value.
+
+Separate facts from possible causes. Preserve quoted system messages, codes, paths, and
+identifiers unless the user asks to rewrite those exact values.
+
+## API or Tool Documentation
+
+Present:
+
+1. The operation and its purpose.
+2. Required inputs and prerequisites.
+3. Constraints and defaults.
+4. The result.
+5. Errors and recovery actions.
+6. A minimal example when it adds necessary clarity.
+
+Keep API names, parameter names, commands, flags, code, and protocol terms unchanged.
+
+## Prompt or Agent Instruction
+
+State:
+
+1. The objective.
+2. The scope and supplied inputs.
+3. Required actions and decision conditions.
+4. Constraints and protected content.
+5. The expected output.
+6. Stop, escalation, or uncertainty behavior when it matters.
+
+Make ownership explicit when more than one agent or tool can act.
+
+## Status or Incident Report
+
+Separate:
+
+1. Observed facts.
+2. User or system impact.
+3. Confirmed cause and unconfirmed hypotheses.
+4. Completed and current actions.
+5. Next action, owner, or checkpoint when provided.
+
+Use time references that are unambiguous in the target context. Do not present a hypothesis as a
+fact.
+
+## Release Note, Commit, or Pull Request
+
+State:
+
+1. What changed.
+2. Why it changed or what user-visible effect it has.
+3. What component or audience it affects.
+4. How the change was verified.
+5. Known limitations or required user actions.
+
+Do not add promotional claims to a technical summary.
+
+## Support or UI Text
+
+Name the problem or action directly. Use the same terms that the interface uses. Give the next
+action before secondary explanation when the reader must act.
+
+Treat exact UI labels, control names, placeholders, and external error text as protected literals
+unless the task explicitly targets them for revision.
+
+## Translation-ready Text
+
+Use self-contained sentences and stable sentence boundaries. Repeat terminology instead of
+rotating synonyms. Make conditions, negation, quantities, units, and references explicit.
+
+Preserve placeholders, markup, segmentation controls, and variables exactly.