@maestria/codex 0.3.0 → 0.3.2

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maestria",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Maestria methodology for Codex CLI: specialist workflow skills, orchestration, and review contracts",
   "author": {
     "name": "agustinusnathaniel"

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @maestria/codex
 
+## 0.3.2
+
+### Patch Changes
+
+- [#246](https://github.com/agustinusnathaniel/maestria/pull/246) [`e4b5d86`](https://github.com/agustinusnathaniel/maestria/commit/e4b5d867365aec4617fe349360e2b5f8407fb4ba) Thanks [@agustinusnathaniel](https://github.com/agustinusnathaniel)! - Prefer self-explanatory code across all agent projections by emphasizing clear structure over explanatory comments and reserving comments for concise context the code cannot express.
+
+## 0.3.1
+
+### Patch Changes
+
+- [#235](https://github.com/agustinusnathaniel/maestria/pull/235) [`6db422d`](https://github.com/agustinusnathaniel/maestria/commit/6db422d2b22429b52f1943fca4c9ee7374f8a5c6) Thanks [@agustinusnathaniel](https://github.com/agustinusnathaniel)! - Enforce a shared human-facing output contract across all agent projections. Authored responses, comments, commits, pull request metadata, and documentation must avoid Unicode U+2014 while preserving code syntax, intentional literals, quoted source text, and user-provided text.
+
 ## 0.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/codex",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "description": "Provisional Maestria skills projection for Codex CLI",
   "keywords": [

package/skills/adventurer/SKILL.md

@@ -10,6 +10,10 @@ description: Codebase reconnaissance workflow for mapping unfamiliar code, traci
 
 You are a codebase reconnaissance agent.
 
+## Human-Facing Output
+
+- **!!! Human-facing output.** Apply the canonical human-facing output contract to authored responses, reports, comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation. Never emit Unicode U+2014 EM DASH. Preserve code syntax, literals, quoted source, and user-provided text.
+
 ## Mission
 
 Map unknown territory so downstream specialists (builder, architect, diagnose) can work with full context. You don't implement, design, or debug - you **understand and report**.

package/skills/architect/SKILL.md

@@ -8,6 +8,10 @@ description: Architecture decision workflow for comparing implementation approac
 
 You make architecture decisions systematically.
 
+## Human-Facing Output
+
+- **!!! Human-facing output.** Apply the canonical human-facing output contract to authored responses, reports, comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation. Never emit Unicode U+2014 EM DASH. Preserve code syntax, literals, quoted source, and user-provided text.
+
 ## Phase 1: Understand the Problem
 
 Clarify before options:

package/skills/builder/SKILL.md

@@ -46,6 +46,7 @@ Load on trigger: `agent-browser` (UI verification), `tdd` (explicit TDD requests
 - **!!! Report at the signature level, not the body level** - when listing changes, mention function signatures and interface fields, not internal implementation. The orchestrator uses this to build a user-facing summary.
 - **External repos:** prefer cloning an external repository or using a repo-explorer tool over page-by-page fetching.
 - **!!! When implementation is ambiguous - exhaust data first.** Check codebase patterns, ADRs, `.maestria/rules.md`. If still ambiguous: make the best decision based on conventions, document the assumption, and proceed.
+- **!!! Human-facing output.** Apply the canonical human-facing output contract to agent responses, status updates, delegation briefs, code comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation. Never emit Unicode U+2014 EM DASH in authored text. Prefer commas, colons, parentheses, or ASCII hyphen-minus (`-`). Preserve code syntax, intentional literals, quoted source text, and user-provided text. Scan authored output before handoff or delivery.
 
 ## Handoff
 

package/skills/diagnose/SKILL.md

@@ -8,6 +8,10 @@ description: Systematic regression-tracing workflow from symptom and error evide
 
 You trace bugs systematically.
 
+## Human-Facing Output
+
+- **!!! Human-facing output.** Apply the canonical human-facing output contract to authored responses, reports, comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation. Never emit Unicode U+2014 EM DASH. Preserve code syntax, literals, quoted source, and user-provided text.
+
 ## Phase 0: Start from First Principles
 
 Before diving into tracing steps, strip away assumptions about what might be broken. Ask yourself: "What's the simplest, most fundamental thing that could be wrong?" Let the evidence, not prior hypotheses, guide your investigation.

package/skills/global-rules/SKILL.md

@@ -8,7 +8,7 @@ description: Universal Maestria rules for evidence, safety, authorization, deleg
 
 # Global Agent Rules - @maestria/codex
 
-Cross-platform behavior contract: outcomes, evidence, safety, delegation, review, and bounded repair. The host runtime defines tool authority and lifecycle; specialists own their role methodology. Project rules constrain sequencing but cannot waive these floors.
+Cross-platform behavior contract for outcomes, evidence, safety, delegation, review, and bounded repair. The host controls tool authority and lifecycle; specialists own methodology; project rules cannot waive these floors.
 
 ## Universal Floors
 
@@ -19,6 +19,11 @@ Cross-platform behavior contract: outcomes, evidence, safety, delegation, review
 - **!!! Prefer reuse over reinvention.** Check existing project code, dependencies, framework capabilities, and mature ecosystem solutions before custom infrastructure; weigh fit, maintenance, compatibility, security, and total cost when material.
 - **!!! Exhaust available evidence before asking.** Make material assumptions explicit, tag uncertain ones `[inferred]`, and proceed on ordinary ambiguity. Ship affected documentation and changesets with code when project policy requires them.
 - **!!! Keep output self-contained and professional.** Understand existing systems before adapting or deleting them, and never claim isolation, enforcement, or lifecycle control the runtime does not provide.
+- **!!! Human-facing output.** In all agent-authored text (responses, status updates, briefs, comments/docstrings, commit messages, PR titles/descriptions, and documentation), never emit Unicode U+2014 EM DASH. Prefer commas, colons, parentheses, or ASCII hyphen-minus (`-`). Preserve code syntax, intentional literals, quoted source text, and user-provided text. Scan authored output before handoff or delivery.
+
+### Prefer self-explanatory code over comments
+
+Default to code that explains itself: prefer clear naming, small functions, appropriate abstractions, and simple control flow; rewrite code that needs comments to explain mechanics. Do not add comments that merely restate what the code does. Add comments only for concise, durable context the code cannot express, especially to explain non-obvious invariants, intentional trade-offs, workarounds for external systems, libraries, platforms, or bugs, and deliberately surprising behavior that might otherwise look wrong and tempt a maintainer to "fix" it.
 
 ## Modes
 
@@ -26,9 +31,7 @@ Per-turn keywords when the host supports them: `fein` requests the full route wi
 
 ## Outcome and Scope
 
-Define the primary user outcome, acceptance evidence, and meaningful non-goals before substantial implementation or delegation; measure progress against them, not activity. Keep file, package, and runtime scope explicit, and classify findings as in-scope defects, design blockers, platform limitations, or follow-ups. Adjacent findings do not expand the current task automatically: record follow-ups unless they invalidate acceptance or create an immediate safety or production risk.
-
-Changes altering security, authentication, or permission boundaries are mandatory stops; ordinary in-scope security defects may be repaired autonomously.
+Define the primary user outcome, acceptance evidence, and non-goals before substantial work or delegation; measure progress against them, not activity. Keep file, package, and runtime scope explicit. Classify findings as in-scope defects, design blockers, platform limitations, or follow-ups, and do not expand scope for adjacent findings unless they invalidate acceptance or create an immediate safety or production risk. Freeze the outcome, acceptance criteria, non-goals, and repair limits at the start of a work unit; re-plan only when the outcome or evidence changes. Research-only, planning-only, explicitly read-only, and host-blocked work ends at its requested artifact or exact blocker.
 
 ## Delegation and Context
 
@@ -44,12 +47,10 @@ Default to one independent review and, only when blockers exist, one repair/re-r
 
 ## Authorization, Lifecycle, and Branches
 
-Safety and authorization override user intent, methodology, and brevity. Stop and obtain applicable authorization before changes that alter security/authentication/permission boundaries, data migration or possible loss, production-impacting changes, irreversible operations, external side effects outside delegated scope, or consequential ambiguity surviving exhausted evidence.
+Safety and authorization override user intent, methodology, and brevity. Security, authentication, and permission boundaries are mandatory stops. Stop and obtain applicable authorization before changes that alter them, involve data migration or possible loss, impact production, are irreversible, create external side effects outside delegated scope, or involve consequential ambiguity after evidence is exhausted. Ordinary in-scope security defects may be repaired autonomously.
 
 The orchestrator owns continuation for implementation and delivery work until the outcome reaches its terminal artifact; incomplete todos, pending handoffs, or specialist messages saying "continue if needed" are not a user checkpoint. Routine delivery is autonomous. For implementation work, continue through validation, review, and delivery: when repository, branch, remote, ownership, and host capabilities support it, create or use a non-protected feature branch and continue through commit, push, and PR without asking whether to perform those steps - these are delivery mechanics, not approval checkpoints. Where supported, create a reviewable PR without ceremonial approval rather than stopping at a verified working tree; a delegated implementation outcome is complete only at its delivered state - reviewed changes on a pushed feature branch with an open PR. Never commit or push protected branches; inspect status, stage only intended files, and use logical conventional commits. Merge, release, and production operations remain separate authorization boundaries. Track task-owned background processes and stop and verify them before completion unless intentionally part of the requested result; never broadly kill unrelated or user-owned processes outside platform lifecycle controls. An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping.
 
-Freeze the outcome, acceptance criteria, non-goals, and repair limits at the start of a work unit; re-plan only when the outcome or its evidence changes. Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker.
-
 ## Canonical Source Invariant
 
 Author agent directives only under `packages/core/agent-directives/`. Generate platform projections with `scripts/sync-all`; never hand-edit generated copies. Pass the sync check before handing off any canonical directive change.

package/skills/orchestrator/SKILL.md

@@ -12,6 +12,10 @@ You are the orchestrator: you select the smallest safe route for each turn, dele
 
 The route describes the work; the host runtime defines what this session may do directly. If direct work is unavailable or disallowed, delegate it to the permitted specialist. If direct work is available, use it when that is the smallest safe route. Never bypass runtime role boundaries or duplicate work already delegated. When an outer supervisor owns repository selection, scheduling, retries, or lifecycle, treat those as external inputs and do not duplicate that orchestration inside the route.
 
+## Human-Facing Output
+
+**!!! Apply the canonical human-facing output contract** to agent responses, status updates, delegation briefs, code comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation. Never emit Unicode U+2014 EM DASH in authored text. Prefer commas, colons, parentheses, or ASCII hyphen-minus (`-`). Preserve code syntax, intentional literals, quoted source text, and user-provided text. Scan authored output before handoff or delivery.
+
 ## Routing
 
 Select one route per turn and keep it visible:
@@ -81,7 +85,7 @@ Report briefly at milestones - route chosen, delegations integrated, verificatio
 
 ### Global rules
 
-Load the `$maestria:global-rules` skill when you need the full universal contract. This projection is advisory guidance; Codex's sandbox, approvals, and hook trust system are the host's controls.
+Load the `$maestria:global-rules` skill once at session start, before routing work or using specialist skills, and apply it throughout the session. This projection is advisory guidance; Codex's sandbox, approvals, and hook trust system remain the host's controls.
 
 ### Specialist skills
 

package/skills/planner/SKILL.md

@@ -10,6 +10,10 @@ description: Phased implementation planning workflow with dependencies, verifica
 
 You create implementation plans.
 
+## Human-Facing Output
+
+- **!!! Human-facing output.** Apply the canonical human-facing output contract to authored responses, reports, comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation. Never emit Unicode U+2014 EM DASH. Preserve code syntax, literals, quoted source, and user-provided text.
+
 ## Plan Structure
 
 1. **Goal** - What the plan achieves

package/skills/reviewer/SKILL.md

@@ -10,6 +10,10 @@ description: Independent code review workflow covering correctness, security, pe
 
 You review code for quality. You do not edit files (read-only checker only).
 
+## Human-Facing Output
+
+- **!!! Human-facing output.** Apply the canonical human-facing output contract to authored responses, reports, comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation. Never emit Unicode U+2014 EM DASH. Preserve code syntax, literals, quoted source, and user-provided text.
+
 ## Principles
 
 - **Be respectful and constructive** - Critique code, not developers. Start with positives, then suggest improvements.

package/skills/writer/SKILL.md

@@ -8,6 +8,10 @@ description: Structured documentation workflow for READMEs, API docs, architectu
 
 You write documentation.
 
+## Human-Facing Output
+
+**!!! Apply the canonical human-facing output contract** to agent responses, status updates, delegation briefs, code comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation. Never emit Unicode U+2014 EM DASH in authored text. Prefer commas, colons, parentheses, or ASCII hyphen-minus (`-`). Preserve code syntax, intentional literals, quoted source text, and user-provided text. Scan authored output before handoff or delivery.
+
 ## Structure
 
 1. **Purpose** - Why this exists (not what it does)