[codex] add Codex skill package

README.md

@@ -62,6 +62,18 @@ npm install
 npm link
 ```
 
+## Install as a Codex skill
+
+Install the bundled Codex skill from this repository:
+
+```bash
+python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
+  --repo Hanjo92/codex-goal-parser \
+  --path skills/codex-goal-parser
+```
+
+Restart Codex after installing so it can discover the new skill.
+
 ## Quick start
 
 Run the basic example:
@@ -201,6 +213,7 @@ The generated `/goal` commands use a compressed version of that context so they
   - `sample-plan.md` — migration-style decomposition
   - `release-plan.md` — release-readiness decomposition
 - `prompts/` — reusable prompts for Codex or Claude
+- `skills/` — installable Codex skill package
 - `src/` — CLI implementation
 - `tests/` — fixture-based CLI tests
 

skills/codex-goal-parser/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: codex-goal-parser
+description: Turn broad software objectives, issues, specs, or repository cleanup requests into compact, verifiable Codex /goal plans. Use when the user wants to decompose a large coding objective into ordered goal-mode tasks, generate ready-to-run /goal commands, or create a repo-aware implementation plan with done conditions and validation steps.
+---
+
+# Codex Goal Parser
+
+Use this skill to convert a large software objective into a short sequence of bounded Codex `/goal` tasks.
+
+## Workflow
+
+1. Decide whether goal decomposition is useful.
+   - Use it for broad implementation, migration, refactor, release, stabilization, or documentation objectives.
+   - If the task is already small enough for one focused coding pass, say that goal mode is unnecessary unless the user explicitly wants a plan.
+2. Gather only the needed inputs.
+   - Objective: the user's desired outcome.
+   - Constraints: non-goals, validation requirements, risk boundaries, or time limits.
+   - Repo path: prefer the current repository path when available.
+   - Issue/spec/context files: pass them when the user points to local files.
+3. Run the bundled CLI from this skill.
+   - Resolve paths relative to this `SKILL.md`.
+   - Use markdown output for human-readable plans.
+   - Use JSON output only when another tool or script needs structured data.
+4. Return the generated plan or a concise summary of it.
+   - Do not execute the generated `/goal` commands unless the user asks.
+   - Keep the plan sequential; later goals should assume earlier checkpoints are complete.
+
+## Commands
+
+Basic repo-aware markdown plan:
+
+```bash
+node scripts/codex-goal-parser.js \
+  --objective "Prepare this project for a safe public release." \
+  --repo-path . \
+  --output markdown
+```
+
+With constraints:
+
+```bash
+node scripts/codex-goal-parser.js \
+  --objective "Refactor this service safely." \
+  --repo-path . \
+  --constraints "Do not change runtime behavior unless needed." \
+  --output markdown
+```
+
+From issue/spec files:
+
+```bash
+node scripts/codex-goal-parser.js \
+  --issue-file ./docs/issue-notes.md \
+  --context-file ./docs/architecture.md \
+  --repo-path . \
+  --output markdown
+```
+
+For machine-readable output:
+
+```bash
+node scripts/codex-goal-parser.js \
+  --objective "Refactor this service safely." \
+  --repo-path . \
+  --output json
+```
+
+## References
+
+- Read `references/output-contract.md` when producing or consuming JSON output.
+- Read `references/codex-goal-decompose.md` when the user wants a reusable prompt instead of running the CLI.
+
+## Notes
+
+- The bundled CLI is deterministic and does not call remote services.
+- It requires Node.js 18 or newer.
+- It plans work only; it does not modify repositories.

skills/codex-goal-parser/references/codex-goal-decompose.md

@@ -0,0 +1,22 @@
+# Codex goal decomposition prompt
+
+```text
+Break this large objective into a short sequence of Codex `/goal` tasks.
+
+Requirements:
+- restate the final objective in one sentence
+- produce 3-7 smaller goals
+- preserve dependency order
+- every goal must have a clear done condition
+- every goal must include a validation method
+- every goal must end with a concrete stopping condition
+- generate a ready-to-run `/goal ...` command for each goal
+- if a goal is still too vague, split it further before finishing
+- if the whole task is too small for goal mode, say so
+
+Output format:
+1. Final objective
+2. Recommended sub-goals
+3. Suggested execution order
+4. Notes / risks
+```

skills/codex-goal-parser/references/output-contract.md

@@ -0,0 +1,68 @@
+# Output contract
+
+`codex-goal-parser --output json` emits a stable plan object for downstream tools.
+
+## Contract version
+
+- `contract_version`: `1.0.0`
+- `plan_format`: `codex-goal-plan`
+
+## Top-level fields
+
+- `contract_version` — version of this JSON contract
+- `plan_format` — fixed discriminator for this plan shape
+- `final_objective` — normalized final objective sentence
+- `repo_context_summary` — compact summary used to keep generated `/goal` commands readable
+- `objective_type` — one of `migration`, `refactor`, `release`, `stabilization`, `documentation`, `generic`
+- `broad_objective` — whether the planner narrowed the goal into a first slice/checkpoint first
+- `input_sources` — file paths supplied with `--issue-file` / `--context-file`
+- `sub_goals` — ordered list of executable planning checkpoints
+- `execution_order` — human-readable ordered list derived from `sub_goals`
+- `notes` — additional planning guidance and source disclosure
+
+## `sub_goals[]`
+
+Each sub-goal contains:
+
+- `title`
+- `why`
+- `scope`
+- `done_when`
+- `validate_with`
+- `goal_command`
+
+## Stability notes
+
+- New fields may be added in future minor releases, but existing fields in `1.x` should remain compatible.
+- Consumers should key off `contract_version` and `plan_format` before assuming exact behavior.
+- Markdown output is human-oriented; JSON output is the supported integration format.
+
+## Example
+
+```json
+{
+  "contract_version": "1.0.0",
+  "plan_format": "codex-goal-plan",
+  "final_objective": "Prepare this project for a safe public release.",
+  "repo_context_summary": "README summary: ...",
+  "objective_type": "release",
+  "broad_objective": false,
+  "input_sources": [],
+  "sub_goals": [
+    {
+      "title": "Audit release readiness",
+      "why": "identify the real blockers across build, packaging, docs, and delivery before trying to ship",
+      "scope": "inspect release-critical scripts, metadata, docs, and distribution assumptions only",
+      "done_when": "the exact release blockers and the first shippable checkpoint are clearly listed",
+      "validate_with": "reviewing the build path, package metadata, release docs, and distribution steps end to end",
+      "goal_command": "/goal Audit release readiness for this repository ..."
+    }
+  ],
+  "execution_order": [
+    "1. Audit release readiness"
+  ],
+  "notes": [
+    "Prefer sequential execution; later goals assume the earlier checkpoint is complete."
+  ]
+}
+```