pi-feature-dev 1.5.0 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-feature-dev
 
-Portable coding-agent workflows, packaged as Pi skills.
+Portable agent workflows and writing skills, packaged as Pi skills.
 
 The `feature-dev` skill describes a tool-agnostic process for non-trivial
 feature work:
@@ -23,6 +23,13 @@ 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.
 
+The `ste` skill drafts, rewrites, and reviews clear English with
+[ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/)
+principles. It supports strict technical-documentation work and a general
+clarity mode for prompts, tool descriptions, error messages, status reports,
+translation-ready text, and agent instructions. The skill is Markdown-only and
+has no runtime dependency.
+
 ## Install
 
 ```
@@ -65,6 +72,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)
+- [danyuchn/asd-ste100-skill](https://github.com/danyuchn/asd-ste100-skill)
 
 ## Usage
 
@@ -80,7 +88,8 @@ Natural language also works when Pi's skill matcher triggers:
 Use feature-dev to implement API rate limiting.
 ```
 
-The `skills/feature-dev/SKILL.md` file is portable markdown and can be adapted for other coding assistant environments.
+The files under `skills/*/SKILL.md` are portable Markdown and can be adapted for
+other agent environments.
 
 Run a plan with `plan-exec`:
 
@@ -94,6 +103,18 @@ Stress-test an idea before planning or implementation:
 /skill:grill Challenge the design for usage-based billing.
 ```
 
+Rewrite technical or operational English:
+
+```text
+/skill:ste Rewrite this maintenance instruction as an STE-aligned draft.
+```
+
+Use STE principles for general agent communication:
+
+```text
+/skill:ste Rewrite this error message so another agent can parse it reliably.
+```
+
 This package is intentionally skill-only. It does not provide prompt template shortcuts; use `/skill:<name>` for explicit Pi invocation.
 
 ## Feature-dev workflow
@@ -108,6 +129,20 @@ The `feature-dev` skill guides a coding assistant through a seven-phase process:
 6. Quality review — inspect the diff from correctness, validation, and maintainability perspectives
 7. Validation and summary — run focused checks and summarize changes
 
+## STE modes
+
+The `ste` skill selects one of two modes:
+
+- **Strict STE** applies Issue 9 rules to regulated, operational, maintenance,
+  and safety-critical documentation. Exact verification requires the official
+  dictionary and the applicable project glossary.
+- **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
+`skills/ste/README.md`, outside the agent's writing context.
+
 ## Package contents
 
 ```text
@@ -130,8 +165,15 @@ pi-feature-dev/
     ├── plan-make/
     │   ├── agents/openai.yaml
     │   └── SKILL.md
-    └── plan-review/
+    ├── plan-review/
+    │   ├── agents/openai.yaml
+    │   └── SKILL.md
+    └── ste/
         ├── agents/openai.yaml
+        ├── references/
+        │   ├── before-after.md
+        │   └── writing-rules.md
+        ├── README.md
         └── SKILL.md
 ```
 

package/package.json

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

package/skills/ste/README.md

@@ -0,0 +1,34 @@
+# STE Skill
+
+This project skill applies ASD-STE100 Simplified Technical English principles to:
+
+- regulated and safety-critical technical documentation;
+- procedures and technical descriptions;
+- prompts, tool descriptions, error messages, and agent instructions;
+- controlled or translation-ready English.
+
+The skill is Markdown-only and has no runtime or tool dependency.
+
+## Standard Baseline
+
+The skill uses ASD-STE100 Simplified Technical English, Issue 9, dated 2025-01-15.
+Issue 9 contains 53 writing rules in nine sections. Its dictionary contains 875 approved entries
+and 1,274 selected unapproved entries.
+
+Authoritative sources:
+
+- [ASD-STE100 official site](https://www.asd-ste100.org/)
+- [Official downloads page](https://www.asd-ste100.org/STE_downloads.html)
+- [Official Issue 9 PDF](https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf)
+
+## Verification Boundary
+
+This skill paraphrases the writing method. It does not reproduce the official controlled
+dictionary or replace the authoritative standard.
+
+Use the official Issue 9 dictionary and the applicable project glossary for strict verification.
+Without those checks, describe the result as an `STE-aligned draft` or an `STE-style rewrite`,
+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.

package/skills/ste/SKILL.md

@@ -0,0 +1,116 @@
+---
+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.
+---
+
+# STE
+
+Write English that has one clear meaning and a structure that is easy to parse. Preserve technical
+accuracy before you simplify language.
+
+## Select the Operating Mode
+
+Use **strict STE mode** when the user requests ASD-STE100 compliance or works on regulated,
+maintenance, operational, or safety-critical documentation.
+
+- Apply Issue 9 rules and the applicable project directives.
+- Verify general vocabulary against the official Issue 9 dictionary.
+- Verify technical nouns and verbs against the project glossary.
+- Use `STE-aligned draft` when these lexical checks are not possible.
+
+Use **STE clarity mode** for prompts, tool descriptions, error messages, agent instructions,
+status reports, translation-ready text, and other technical or operational English.
+
+- Transfer the clarity rules that fit the text.
+- Prefer explicit actors, actions, conditions, inputs, and results.
+- Do not imply formal ASD-STE100 compliance.
+
+## Load References Selectively
+
+- 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/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
+  apply.
+
+If sources conflict, follow the explicit regulatory or project requirement and report the
+deviation. Do not merge inconsistent terminology.
+
+## Preserve Meaning
+
+Before rewriting:
+
+1. Identify each fact, action, condition, limit, unit, exception, warning, causal relation, and
+   cross-reference.
+2. Resolve what each pronoun and modifier refers to.
+3. Keep the original sequence and scope unless the user authorizes a technical change.
+4. Ask when ambiguity can change safety, responsibility, or task outcome.
+
+Do not invent missing facts. Do not remove precision only to meet a length target.
+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.
+
+## Apply the Core Discipline
+
+| Area | Apply |
+|---|---|
+| Vocabulary | Use one familiar word for one meaning. In strict mode, confirm its approved meaning, part of speech, and form. |
+| Terminology | Use one term for one concept. Keep necessary domain terms and define or flag unclear terms. |
+| Verbs | Prefer active voice, simple tenses, and direct action verbs. Avoid noun-heavy and complex auxiliary constructions. |
+| Instructions | Use the imperative form. Put one independent action in each sentence. Combine actions only when they occur at the same time. Put prerequisite conditions first. |
+| Length | Use no more than 20 words for procedures and 25 words for descriptions under Issue 9 counting rules. |
+| Noun phrases | Keep multi-word nouns to three words when possible. Preserve longer official names and define a clear short form if needed. |
+| Structure | Use complete sentences, one topic per paragraph, and vertical lists for complex sequences or alternatives. |
+| Safety | Start with the required command or condition, then state the risk or possible result. Never infer the risk level. |
+| Consistency | Reuse the same wording for the same action and context. Do not rotate synonyms for style. |
+
+## Rewrite in Passes
+
+1. Classify each section as instruction, description, safety text, or mixed content.
+2. Read for meaning before changing words.
+3. Record repeated or uncertain terms when terminology control matters.
+4. Find ambiguity, indirect wording, complex tense, passive voice, omitted words, long noun
+   phrases, overloaded sentences, and inconsistent terminology.
+5. In procedural text, count the independent actions in each sentence. Split actions that do not
+   occur at the same time.
+6. Rewrite only the text that benefits from a change.
+7. Compare the result with the source. Confirm that all facts, conditions, limits, exceptions,
+   and responsibilities remain.
+8. Review sentence length, paragraph structure, punctuation, and term consistency manually.
+
+If the input is already clear and meets the applicable rules, say so. Do not force a rewrite.
+
+## Choose the Output
+
+For a direct drafting or rewriting request:
+
+1. Give the revised text first.
+2. Add `Unresolved checks` only when lexical, technical, regulatory, or safety facts remain
+   unverified.
+
+For an audit or an explained rewrite, use:
+
+| Rule area | Original | Revised | Reason |
+|---|---|---|---|
+| Concise rule name | Exact source fragment | Replacement | What ambiguity or violation the change removes |
+
+After the table, give the complete revised text. Group unresolved items as:
+
+- `Confirmed issue`
+- `Manual review`
+- `Project decision`
+
+Use the user's requested format when it conflicts with these defaults.
+
+## State Verification Honestly
+
+Use one of these statuses only when a status is useful:
+
+- `STE-style rewrite` for general-purpose clarity mode.
+- `STE-aligned draft` when Issue 9 or project terminology checks are incomplete.
+- `Verified against Issue 9 and project terminology` only when those checks occurred.
+
+Do not call the result certified. Do not reproduce the official dictionary. Do not apply STE
+mechanically to creative, marketing, or persuasive text unless the user explicitly values
+literal clarity more than voice.

package/skills/ste/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "STE"
+  short_description: "Write clear, unambiguous English with STE"
+  default_prompt: "Use $ste to rewrite this text for clear, unambiguous technical communication."

package/skills/ste/references/before-after.md

@@ -0,0 +1,131 @@
+# Before and After Examples
+
+Use these original examples to recognize rewrite patterns. They illustrate the skill workflow.
+They are not evidence that a word is approved in the official ASD-STE100 dictionary.
+
+## Contents
+
+- [Maintenance procedure](#maintenance-procedure)
+- [Tool description](#tool-description)
+- [Error message](#error-message)
+- [Agent instruction](#agent-instruction)
+- [Status report](#status-report)
+- [Terminology consistency](#terminology-consistency)
+- [Already clear text](#already-clear-text)
+
+## Maintenance Procedure
+
+**Before**
+
+> Prior to carrying out removal of the filter housing, the technician should ensure that
+> electrical power has been disconnected, and thereafter the retaining bolts should be taken
+> off.
+
+**Issues**
+
+- Indirect instruction.
+- Passive voice.
+- Noun-heavy construction.
+- More than one instruction in one sentence.
+
+**After**
+
+> Disconnect electrical power.
+>
+> Remove the retaining bolts.
+>
+> Remove the filter housing.
+
+**Unresolved check:** Confirm that these steps have the correct sequence and that the project
+glossary approves `retaining bolt` and `filter housing`.
+
+## Tool Description
+
+**Before**
+
+> This tool is intended to facilitate the synchronization of configuration values across all of
+> the services that have been selected.
+
+**After**
+
+> The tool synchronizes configuration values across the selected services.
+
+**Why:** The revision identifies the actor and action directly. It removes a nominalization and a
+passive construction.
+
+## Error Message
+
+**Before**
+
+> The request could not be completed due to the fact that the credentials which were provided
+> are no longer valid.
+
+**After**
+
+> The request failed because the credentials expired.
+
+**Why:** The revision separates the result from the cause and removes indirect wording. Confirm
+that expiration is the actual cause before using this message.
+
+## Agent Instruction
+
+**Before**
+
+> Once the build has finished, the agent should inspect the report and then, if any failures have
+> been identified, it should post a summary.
+
+**After**
+
+> Wait for the build to finish.
+>
+> Inspect the report.
+>
+> If the report shows failures, post a summary.
+
+**Why:** The revision uses direct commands, simple verb forms, an explicit condition, and one
+instruction per sentence.
+
+## Status Report
+
+**Before**
+
+> We have successfully completed the database migration, which was performed after all of the
+> validation checks had been carried out.
+
+**After**
+
+> We completed all validation checks. Then we migrated the database.
+
+**Why:** The revision uses simple past tense and makes the sequence explicit. Keep `successfully`
+only when it communicates a defined result that the text must preserve.
+
+## Terminology Consistency
+
+**Before**
+
+> Check the connection. Verify the cable. Confirm the plug.
+
+**Decision**
+
+Do not replace these verbs automatically. First determine whether they describe one action or
+three different actions.
+
+**After, only if the intended action is identical**
+
+> Check the connection. Check the cable. Check the plug.
+
+**Why:** STE favors one term for one concept, but terminology consistency must not erase a real
+technical distinction.
+
+## Already Clear Text
+
+**Input**
+
+> Close the inlet valve. Disconnect the power cable.
+
+**Result**
+
+Keep the text unchanged if the terms are correct for the project.
+
+**Why:** A rewrite is not an objective by itself. Change text only when the change improves
+clarity, correctness, or compliance.

package/skills/ste/references/writing-rules.md

@@ -0,0 +1,257 @@
+# ASD-STE100 Issue 9 Writing Rules
+
+## Contents
+
+- [Decision priority](#decision-priority)
+- [Vocabulary and terminology](#vocabulary-and-terminology)
+- [Compact rule coverage map](#compact-rule-coverage-map)
+- [Issue 9 general recommendations](#issue-9-general-recommendations)
+- [General-purpose transfer](#general-purpose-transfer)
+- [Authoring templates](#authoring-templates)
+- [Review protocol](#review-protocol)
+
+## Decision Priority
+
+Apply these priorities:
+
+1. Preserve technical accuracy, safety intent, limits, and required sequence.
+2. Follow applicable law, regulation, customer requirements, and project directives.
+3. Apply the current Issue 9 rule and dictionary entry.
+4. Use the approved project glossary for technical nouns and technical verbs.
+5. Prefer one clear construction when more than one construction is permitted.
+
+If priorities conflict, select the higher-priority requirement and report the conflict. Do not merge
+two inconsistent wordings.
+
+## Vocabulary and Terminology
+
+Use only these word classes:
+
+- A general word approved in the Issue 9 dictionary.
+- A technical noun applicable to the subject field.
+- A technical verb applicable to the subject field.
+
+For an approved general word, verify all of these properties:
+
+- Part of speech.
+- Approved meaning.
+- Approved inflected form.
+- Correct use in the sentence.
+
+Treat a project term as a technical noun only when it names a precise subject-field concept. Use
+terms from drawings, parts data, standards, official documents, and the approved project
+glossary. Issue 9 organizes technical nouns into broad areas such as parts, machines, tools,
+materials, systems, science, navigation, measurements, quoted labels, roles, medical concepts,
+documents, conditions, colors, damage, computing, operations, law, and living things.
+
+Treat a project verb as a technical verb only when it names a precise subject-field process.
+Issue 9 permits categories for manufacturing, computer operations, applicable technical fields,
+and legal or regulatory texts. Use a dictionary-approved verb instead when it communicates the
+same action accurately.
+
+Apply these terminology controls:
+
+- Use one technical noun for one item.
+- Do not use a technical noun as a verb.
+- Do not use a technical verb as a noun.
+- Prefer short, familiar, project-approved terms.
+- Reject slang, regional wording, and unexplained jargon.
+- Define an abbreviation at first use unless the audience and governing directive make it
+  unnecessary.
+- Keep quoted interface text, placards, labels, and identifiers unchanged.
+
+## Compact Rule Coverage Map
+
+Use this map to confirm coverage. Consult the authoritative standard for definitions, exceptions,
+dictionary entries, and official examples.
+
+### Words (Issue 9 section 1)
+
+- Limit vocabulary to approved general words, technical nouns, and technical verbs.
+- Use each approved word only with its listed part of speech, meaning, and form.
+- Validate technical nouns and verbs by category and project authority.
+- Keep one term for one concept and do not change noun/verb roles.
+- Use American English spelling unless an official directive overrides it.
+
+### Multi-word nouns (section 2)
+
+- Keep a multi-word noun to three words or fewer when possible.
+- When the official term is longer, write it in full first. Then define a clear short form or use
+  hyphens to show words that function as one unit.
+- Do not shorten a term in a way that creates ambiguity.
+
+### Verbs (section 3)
+
+- Use only approved verb forms.
+- Use the infinitive, imperative, simple present, simple past, simple future, or a past participle
+  used as an adjective.
+- Avoid complex auxiliary constructions.
+- Use an `-ing` form only as a technical noun or as a modifier inside a technical noun.
+- Prefer active voice. In descriptive text, use passive voice only when the agent is unknown.
+- Express an action with an accurate verb, not a noun-heavy construction.
+
+### Sentences (section 4)
+
+- Write short, complete, explicit sentences.
+- Do not omit necessary words and do not use contractions.
+- Convert complex series or alternatives into vertical lists.
+- Use clear connecting words between related statements.
+- Use an article or demonstrative adjective before a noun when English grammar requires one.
+
+### Procedures (section 5)
+
+- Limit each sentence to 20 words.
+- Put one instruction in each sentence, except for actions that occur at the same time.
+- Count independent actions, not only grammatical clauses. Do not join sequential actions with
+  `and`.
+- Use the imperative form.
+- Put a prerequisite condition before the command and separate it with a comma.
+- Keep commands out of notes.
+
+### Descriptions (section 6)
+
+- Present information gradually and in a logical sequence.
+- Repeat key terms where they make structure clear.
+- Limit each sentence to 25 words.
+- Keep one topic in each paragraph.
+- Limit each paragraph to six sentences.
+
+### Safety instructions (section 7)
+
+- Identify risk with the label required by the applicable safety system.
+- Begin with a clear command or condition.
+- Explain the risk or possible result.
+- Preserve official safety wording when a governing directive prohibits changes.
+
+### Punctuation and word count (section 8)
+
+- Do not use semicolons.
+- Use hyphens only to connect words that function together.
+- Use parentheses only for clear supporting purposes, such as references, identifiers,
+  abbreviations, alternatives, or brief explanations.
+- In a vertical list, treat the introductory colon as a sentence boundary for word count.
+- Count a complete parenthetical group as one word.
+- Count each number, number-plus-unit, abbreviation, alphanumeric identifier, quoted text,
+  title, label, and applicable proper name as one word.
+- Count a hyphenated unit as one word.
+
+### Writing practices (section 9)
+
+- Restructure a sentence when a word-for-word synonym change is not sufficient.
+- Confirm the meaning and grammar of each approved word.
+- Do not create phrasal verbs.
+- Use the same terminology and wording for the same context.
+
+## Issue 9 General Recommendations
+
+Apply these recommendations when they improve clarity:
+
+- Include `that` when it clearly marks the start of a subordinate clause.
+- Review each use of `with` for multiple possible meanings.
+- Replace an ambiguous pronoun with its noun.
+- Make the referent of `this` explicit.
+- Check false friends when the author is not a native English speaker.
+- Replace Latin abbreviations with plain English.
+- Use inclusive, gender-neutral language.
+- Avoid a possessive form when it can confuse the reader.
+
+These recommendations help quality but are not part of the 53 rules.
+
+## General-Purpose Transfer
+
+For prompts, tool descriptions, error messages, agent instructions, and status reports:
+
+- Treat a command as procedural text and an explanation as descriptive text.
+- Name the actor when responsibility matters.
+- State conditions before the action that depends on them.
+- Separate actual results from possible causes and suggested recovery actions.
+- Replace vague references such as `it`, `this`, and `they` when more than one referent is
+  possible.
+- Keep API names, identifiers, quoted UI text, code, and protocol terms unchanged.
+- Define a necessary domain term once and use it consistently.
+
+For translation-ready text:
+
+- Prefer repeated terminology over stylistic variation.
+- Keep sentence boundaries aligned with complete ideas.
+- Make negation, quantities, units, and conditions explicit.
+
+Use the status `STE-style rewrite` for these transferred applications unless strict verification
+also occurred.
+
+## Authoring Templates
+
+### Procedure
+
+Use this pattern:
+
+```text
+If [prerequisite condition], [imperative command].
+[Imperative command].
+[Imperative command].
+
+NOTE: [Information only.]
+```
+
+Example:
+
+```text
+If the pressure is more than 500 kPa, stop the pump.
+Close the inlet valve.
+Disconnect the power cable.
+
+NOTE: The indicator can stay on for 5 seconds.
+```
+
+### Description
+
+Use this pattern:
+
+```text
+[Identify the item and its primary function.]
+[Explain the next fact with the same key terminology.]
+[State a condition and its result.]
+```
+
+Example:
+
+```text
+The controller monitors the inlet pressure. It sends a stop signal when the pressure is more than
+500 kPa.
+```
+
+### Safety instruction
+
+Use the label from the governing safety policy:
+
+```text
+[RISK LABEL]: [Command or condition]. [Risk or possible result.]
+```
+
+Example:
+
+```text
+WARNING: Disconnect electrical power before you open the housing. Electrical power can cause
+injury.
+```
+
+Do not reuse the example risk level without validating it for the real hazard.
+
+## Review Protocol
+
+Review in separate passes:
+
+1. **Meaning:** Compare source and output action by action. Confirm conditions, negation, limits,
+   units, sequence, references, and consequences.
+2. **Vocabulary:** Verify each general word in the Issue 9 dictionary. Record technical nouns and
+   technical verbs in the term ledger.
+3. **Grammar:** Check verb form, voice, articles, complete constructions, pronouns, and
+   modifiers.
+4. **Structure:** Apply the procedure, description, or safety pattern.
+5. **Mechanics:** Apply sentence and paragraph limits, punctuation, spelling, and word-count
+   rules.
+6. **Consistency:** Search for alternate names and alternate wording for the same concept or
+   action.
+
+Record unverified items. A clear limitation is more accurate than an unsupported claim of
+compliance.