x-internal-normalize-args
Parses an argv string against a declarative JSON schema with typed flags (boolean, string, integer, enum), defaults, mutually-exclusive groups, and deprecation warnings, then emits a normalized `{parsed, warnings, errors}` envelope on stdout. Replaces ~150 lines of inline argv parsing inlined inside `x-implement-epic`, `x-implement-story`, and `x-orchestrate-epic`, giving every orchestrator identical flag-validation syntax and error messages. Third skill in the x-internal-* convention (after x-internal-update-status pilot and x-internal-write-report): internal visibility, non-user-invocable, subdir scoping under internal/ops/.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-internal-normalize-args
- category
- internal-ops
- visibility
- internal
- description
- Parses an argv string against a declarative JSON schema with typed flags (boolean, string, integer, enum), defaults, mutually-exclusive groups, and deprecation warnings, then emits a normalized `{parsed, warnings, errors}` envelope on stdout. Replaces ~150 lines of inline argv parsing inlined inside `x-implement-epic`, `x-implement-story`, and `x-orchestrate-epic`, giving every orchestrator identical flag-validation syntax and error messages. Third skill in the x-internal-* convention (after x-internal-update-status pilot and x-internal-write-report): internal visibility, non-user-invocable, subdir scoping under internal/ops/.
- allowed-tools
- Bash
- argument-hint
- --schema <json-or-@path> --argv <string>
- context-budget
- medium
- user-invocable
- false
- requires-capabilities
- []
02 资源文件 1
- 参考文档references/full-protocol.md10.9 KB
03 SKILL.md 正文
Global Output Policy
- Language: English ONLY.
- Tone: Technical, Direct, and Concise.
- Efficiency: Remove all conversational fillers and greetings to save tokens.
🔒 INTERNAL SKILL Esta skill é invocada apenas por outras skills (orquestradores). NÃO é destinada a invocação direta pelo usuário. Caller principal: x-implement-epic, x-implement-story, x-orchestrate-epic. Terceira skill da convenção
x-internal-*(após x-internal-update-status, a story PILOTO 0049-0005, e x-internal-write-report, story 0049-0006): frontmattervisibility: internal, subdirinternal/ops/, marker 🔒 e filtragem do menu/helpvia generator.
Skill: x-internal-normalize-args
Purpose
Parse a Bash-style argv string against a declarative JSON schema and produce a normalized envelope describing:
parsed— map of flag name → typed value (after defaults applied).warnings— list of deprecation notices emitted for seendeprecatedflags.errors— list of validation errors (populated only on non-zero exit).
This removes the ~150 lines of ad-hoc argv parsing currently duplicated inside
x-implement-epic, x-implement-story, and x-orchestrate-epic (catalogued
in EPIC-0049 story-0049-0007 dependency matrix), so future orchestrators can
declare their flag surface once — as a schema — and reuse the same parser,
the same error codes, and the same deprecation-warning policy.
Convention Anchors (x-internal-*)
| Aspect | Value | Rationale |
|---|---|---|
| Path | internal/ops/x-internal-normalize-args/ |
internal/ prefix scopes visibility; ops/ aligns with sibling runtime-ops skills |
Frontmatter visibility |
internal |
Generator filters these from /help menu |
Frontmatter user-invocable |
false |
Declarative complement to visibility: internal |
| Body marker | > 🔒 **INTERNAL SKILL** block as first non-frontmatter content |
Visible to humans browsing the repo; no parsing required |
| Allowed tools | Bash only |
Minimal surface; parser is a single shell pipeline built on jq |
| Naming | x-internal-{subject}-{action} |
Mirrors Rule 04 skill taxonomy; args-normalize = subject+action |
Audit rule: Rule 22 (Lifecycle Integrity) validates every skill under
internal/** satisfies all 6 anchors above. Violations fail the
LifecycleIntegrityAuditTest.
Triggers
Bare-slash form is intentionally omitted — this skill is never invoked
by a human typing /x-internal-normalize-args in chat. All invocations
follow Rule 13 INLINE-SKILL pattern from a calling orchestrator:
Skill(skill: "x-internal-normalize-args",
args: "--schema @.claude/schemas/x-implement-epic.args.json \
--argv \"EPIC-0049 --parallel --auto-merge-strategy squash\"")
Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
--schema <json-or-@path> |
M | — | Declarative schema describing flags, defaults, mutually-exclusive groups, and deprecations. Inline JSON string OR @path/to/schema.json read from disk |
--argv <string> |
M | — | Bash-quoted argv string exactly as the caller received it (positional tokens preserved; --flag value and --flag=value both honoured) |
Schema Contract
The schema is a JSON object with two top-level keys: flags (required array)
and mutuallyExclusive (optional array of arrays of flag names).
{
"flags": [
{"name": "--parallel", "type": "boolean", "default": false},
{"name": "--story-id", "type": "string"},
{"name": "--max-retries", "type": "integer", "default": 3},
{"name": "--auto-merge-strategy", "type": "enum",
"values": ["merge", "squash", "rebase"], "default": "merge"},
{"name": "--no-merge", "type": "boolean",
"deprecated": "use --auto-merge-strategy=<strategy> instead"}
],
"mutuallyExclusive": [
["--auto-merge", "--no-merge", "--interactive-merge"]
]
}
Per-flag fields
| Field | Required | Description |
|---|---|---|
name |
M | Flag token including leading -- (double-dash mandatory). Unique across flags[] |
type |
M | One of boolean, string, integer, enum |
values |
M if type=enum |
Non-empty array of allowed string values |
default |
O | Typed default applied when the flag is absent from argv. For boolean, default is false unless set explicitly |
deprecated |
O | Non-empty string to emit as a warning when the flag appears in argv. Flag is still parsed and returned in parsed |
mutuallyExclusive
Each inner array lists flag names; at most one may be present in argv.
Violation triggers exit 2 (MUTUALLY_EXCLUSIVE). Empty or absent outer
array disables the check. Names MUST match flags[].name exactly;
references to unknown flags are a schema error.
Response Contract
On success (exit 0), the skill writes a single-line JSON object to stdout:
| Field | Type | Always Present | Description |
|---|---|---|---|
parsed |
Object |
yes | Map of flag-name (no leading --, kebab preserved) to typed value. Includes every schema-declared flag (explicit or defaulted); omits flags with no default that were absent from argv |
warnings |
List<String> |
yes | Deprecation messages emitted for each deprecated flag seen in argv (message = the schema's deprecated string verbatim). Empty array if none |
errors |
List<String> |
yes | Validation errors. Empty array on success. Populated and echoed to stderr on non-zero exit |
On non-zero exit, stderr carries the same human-readable error messages;
stdout still emits a best-effort envelope with errors populated and
parsed containing whatever was resolvable before the failure.
Exit Codes
| Code | Name | Condition | Message Format |
|---|---|---|---|
| 0 | SUCCESS | Parse completed; all validations passed | — |
| 1 | INVALID_SCHEMA | Schema JSON is malformed or violates contract | Schema validation failed: <detail> |
| 2 | MUTUALLY_EXCLUSIVE | Two or more flags from one mutuallyExclusive group seen |
Flags <A>, <B> are mutually exclusive |
| 3 | UNKNOWN_FLAG | argv contains a --flag not declared in flags[] |
Unknown flag '<--xxx>' |
| 4 | INVALID_ENUM_VALUE | enum flag value outside values[] |
Invalid value '<v>' for <--flag> (allowed: <v1,v2,...>) |
| 64 | USAGE | Missing --schema or --argv; unknown skill-level flag |
Usage banner on stderr |
| 127 | MISSING_DEPENDENCY | jq absent on PATH |
jq is required |
Integer parsing failures (non-numeric token for type=integer) and boolean
parsing failures (value for type=boolean is neither true, false, 1,
0, nor absent) are reported under exit 1 with INVALID_SCHEMA subcategory
TYPE_COERCION_FAILED in the message — the schema declared the type, so
malformed argv violates the schema contract from the parser's perspective.
Argv Grammar (Summary)
The parser consumes standard Bash-style argv tokens: --flag value,
--flag=value, implicit true for booleans, positional tokens (preserved
under parsed._positional), and the POSIX -- terminator. Full grammar,
quoting rules, and boolean-negation semantics in
references/full-protocol.md §1.
Workflow (High-Level)
| Step | Summary |
|---|---|
| 1 | Parse skill-level flags (--schema, --argv). Reject unknowns with exit 64 |
| 2 | Validate schema JSON shape via jq (flags array, types, enum values[], unique names, mutex references) |
| 3 | Tokenise argv into positional array (quote-aware via xargs) |
| 4 | Walk tokens: --flag[=value] matched against schema, else UNKNOWN_FLAG |
| 5 | Apply defaults; validate enum values |
| 6 | Check mutually-exclusive groups |
| 7 | Emit deprecation warnings for seen deprecated flags |
| 8 | Print {parsed, warnings, errors} envelope on stdout; exit with numbered code |
Per-step details, jq pipelines, and the canonical Bash implementation
skeleton live in references/full-protocol.md §2.
Examples (Minimal)
Defaults applied (empty argv)
Schema {"flags":[{"name":"--auto-merge-strategy","type":"enum", "values":["merge","squash"],"default":"merge"}]}, argv "".
Stdout: {"parsed":{"auto-merge-strategy":"merge"},"warnings":[],"errors":[]}.
Exit 0.
Happy path parse
Schema with --parallel (boolean) and --auto-merge-strategy (enum),
argv "--parallel --auto-merge-strategy squash".
Stdout: {"parsed":{"parallel":true,"auto-merge-strategy":"squash"},"warnings":[],"errors":[]}.
Exit 0.
Mutually-exclusive violation
argv "--auto-merge --no-merge" with mutex group.
Stderr: Flags --auto-merge, --no-merge are mutually exclusive. Exit 2.
Deprecation warning
argv "--no-merge" against schema with "deprecated":"use --auto-merge-strategy=merge instead".
warnings[] carries the schema string verbatim; exit 0.
Enum invalid value
argv "--auto-merge-strategy invalid" against enum ["merge","squash","rebase"].
Stderr: Invalid value 'invalid' for --auto-merge-strategy (allowed: merge,squash,rebase). Exit 4.
Six more examples — --flag=value form, positional preservation, unknown
flag, invalid schema (missing --), boolean coercion failure, integer
coercion failure — in references/full-protocol.md §3.
Outputs
| Artifact | Path | Description |
|---|---|---|
| Response envelope | stdout | Single-line JSON with parsed, warnings, errors |
| Human-readable errors | stderr | One line per error; same text that populates errors[] |
This skill writes NO files. The parsed envelope is the sole side effect,
consumed by the invoking orchestrator.
Error Handling (Quick Reference)
| Scenario | Action |
|---|---|
Missing --schema or --argv |
Usage banner on stderr; exit 64 |
jq absent on PATH |
Exit 127 with jq is required |
--schema @path unreadable |
Exit 1 (INVALID_SCHEMA) with the path echoed |
Schema has zero flags[] entries |
Exit 1 (INVALID_SCHEMA) |
flags[].name missing -- prefix |
Exit 1 with the offending name |
type=enum without values[] |
Exit 1 |
mutuallyExclusive references unknown flag |
Exit 1 with the unknown name |
Unknown --flag in argv |
Exit 3 (UNKNOWN_FLAG) |
enum value outside values[] |
Exit 4 (INVALID_ENUM_VALUE) |
mutuallyExclusive group violated |
Exit 2 (MUTUALLY_EXCLUSIVE) |
| Integer / boolean coercion failure | Exit 1 with TYPE_COERCION_FAILED detail |
Complete error-handling matrix, including argv tokenisation failures and
path-traversal guards, in references/full-protocol.md §4.
Performance Contract
- Parse < 50 ms for schemas with ≤ 30 flags and argv ≤ 20 tokens (DoD-local target of story-0049-0007).
- Memory usage bounded by schema size + argv size; the parser builds the
response envelope in-memory via
jqstreaming. - Deterministic output: identical schema + argv produces byte-identical stdout and exit code across runs.
- Idempotent under repeated invocations; no shared state between calls.
Testing
Story-0049-0007 ships 12 acceptance test scenarios covering defaults,
happy-path parse, --flag=value form, positional preservation, mutex
violations, unknown flag, enum invalid value, deprecation warning, and
four invalid-schema / coercion cases. Full matrix in
references/full-protocol.md §5.
Goldens under
src/test/resources/golden/internal/ops/x-internal-normalize-args/ lock
the SKILL.md rendering. Coverage requirement: ≥ 95% line / ≥ 90%
branch across the invoking Bash codepaths.
Generator Filter Contract
The ia-dev-env generator MUST exclude skills with
visibility: internal from:
- The
.claude/README.mdskill-inventory table. - The
/helpmenu listing surfaced by Claude Code. - User-facing autocomplete in the chat input.
Internal skills are still copied into .claude/skills/ (flat layout)
so Skill(skill: "x-internal-normalize-args") invocations from other
skills resolve correctly. The invariant — set by the pilot story
(0049-0005) — holds here: user cannot see it; orchestrators can
invoke it.
Telemetry
Internal skills DO NOT emit phase.start / phase.end markers —
telemetry is produced by the invoking orchestrator (the phase wrapping
the orchestrator's own step is the correct aggregation boundary).
Passive hooks still capture tool.call for the underlying Bash
invocation.
Reference: Rule 13 (Skill Invocation Protocol), Rule 22 (Lifecycle Integrity Audit), ADR-0010 (Interactive Gates Convention — exempts internal skills from the 3-option menu contract).
Integration Notes
| Skill | Relationship | Context |
|---|---|---|
x-implement-epic |
caller | Replaces inline argv parsing in Phase 0 (~150 LOC — story-0049-0018) |
x-implement-story |
caller | Replaces inline argv parsing in Phase 0 (~150 LOC — story-0049-0019) |
x-orchestrate-epic |
caller | Shares the same schema convention; parses epic-level flags |
x-internal-update-status |
peer | Pilot sibling x-internal-* skill; both scoped under internal/ops/ |
x-internal-write-report |
peer | Second sibling x-internal-* skill; no shared runtime state |
Downstream stories that depend on this skill: story-0049-0018 (x-implement-epic consumes it), story-0049-0019 (x-implement-story consumes it).
04 同仓库更多 Skills
x-parallel-eval
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
parallelism-heuristics
Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.
x-watch-pr-ci
Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.
x-validate-docs
Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.
x-update-system-architecture
Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.
x-update-architecture
Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.