pi-feature-dev 1.4.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:
@@ -19,6 +19,17 @@ 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.
+
+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
 
 ```
@@ -60,6 +71,8 @@ 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
 
@@ -75,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`:
 
@@ -83,6 +97,24 @@ 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.
+```
+
+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
@@ -97,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
@@ -104,14 +150,30 @@ 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
-    └── plan-review/
+    └── 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.4.0",
+  "version": "1.6.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/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."

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.