Skip to content
Back to search

goal-forge

SkillWorks with Claude CodeGitHub

Turn a rough coding or repo idea into a spec, executable plan, and long-running Codex /goal contract. Use when the user wants to create a coding spec, spec out a repo feature, tighten a coding spec, turn an implementation idea into a /goal-ready plan, prepare for autonomous coding, forge a goal, start a /goal, generate GOAL.md, prepare measurable done_when criteria, or check Codex config readiness.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/michaelpersonal--goal-forge/badge.svg)](/listings/michaelpersonal--goal-forge)

HTML

<a href="/listings/michaelpersonal--goal-forge"><img src="/api/listings/michaelpersonal--goal-forge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Drop the folder into your Codex skills directory:

git clone https://github.com/michaelpersonal/goal-forge.git ~/.codex/skills/goal-forge

Then invoke from Codex with `$goal-forge` or any of the natural-language triggers in `SKILL.md`'s frontmatter.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 176 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: goal-forge
  3. description: Turn a rough coding or repo idea into a spec, executable plan, and long-running Codex /goal contract. Use when the user wants to create a coding spec, spec out a repo feature, tighten a coding spec, turn an implementation idea into a /goal-ready plan, prepare for autonomous coding, forge a goal, start a /goal, generate GOAL.md, prepare measurable done_when criteria, or check Codex config readiness.
  4. ---
  5. # Goal Forge
  6. Goal Forge converts a rough coding idea into an executable Codex `/goal` contract.
  7. Default pipeline:
  8. 1. Interview rough intent into `SPEC.md`.
  9. 2. Tighten `SPEC.md` until scope, scoring, feedback, and verification are concrete.
  10. 3. Compile `SPEC.md` into `GOAL.md`.
  11. 4. Check Codex config readiness before running `/goal`.
  12. Use this skill for coding and repo work first. If the task is mostly exploratory, research-only, security-critical, or lacks verifiable completion criteria, keep the user in the loop instead of compiling a `/goal`.
  13. Long-running goals need a runtime harness, not just a task description. Every `/goal` contract should make four things explicit:
  14. - **Scorecard**: how Codex repeatedly scores progress toward the goal.
  15. - **Feedback loop**: the fastest representative check Codex can run while iterating.
  16. - **Working memory**: markdown files Codex maintains so multi-hour runs do not rely only on conversation context.
  17. - **Human control surface**: small, task-specific knobs and sidecar inputs the user can inspect or adjust while the goal runs.
  18. ## Modes
  19. Choose the smallest mode that satisfies the request.
  20. - **Interview**: User gives a rough idea, asks to create a spec, or the spec lacks user-approved success criteria.
  21. - **Tighten**: User has a `SPEC.md` and wants it challenged, clarified, or made executable.
  22. - **Compile**: User has a good enough `SPEC.md` and wants a `/goal` prompt or `GOAL.md`.
  23. - **Check config**: User asks whether their Codex setup can run long goals.
  24. ## Interview Mode
  25. When the user gives a rough idea or asks to create a spec:
  26. 1. Read the existing `SPEC.md` if present. Otherwise treat the rough idea as the interview seed; do not draft `SPEC.md` until step 6.
  27. 2. Interview the user in detail before finalizing the spec.
  28. 3. Ask about anything relevant: technical implementation, UI/UX, architecture, data model, edge cases, tradeoffs, rollout, scoring, feedback-loop speed, verification, risks, and non-goals.
  29. 4. Do not ask obvious checklist questions. Ask questions that force decisions or expose hidden ambiguity.
  30. 5. Continue interviewing until the spec is complete enough to compile into an executable `/goal`.
  31. 6. Then write or update `SPEC.md`.
  32. Use structured user-question tooling when available. If it is not available, ask concise batches of questions in chat. Keep each batch focused on unresolved blockers.
  33. Hard gate: do not compile a `/goal` prompt until `done_when` contains concrete, user-approved success criteria. After the interview has covered scope, architecture, scoring, and verification, Codex may propose candidate `done_when` criteria as a starting point. The user must confirm or edit product and acceptance criteria before the spec is considered complete.
  34. For long-running or exploratory goals, also identify:
  35. - the primary score or checklist Codex should optimize
  36. - the threshold or stop condition that means the goal is complete
  37. - the fastest useful check Codex can run repeatedly while working
  38. - the slower final check required before completion
  39. - whether Codex should create or maintain `PLAN.md`, `ATTEMPTS.md`, and `NOTES.md`
  40. - what the user may need to observe or tune while the goal runs, such as phase/status visibility, scope limits, resource budgets, review gates, sidecar inputs, or pivot approvals
  41. ## Tighten Mode
  42. Read `SPEC.md` skeptically before any execution prompt is created.
  43. For each ambiguity:
  44. - explain why it matters
  45. - give two distinct interpretations
  46. - recommend the interpretation that produces the more maintainable result
  47. - ask the user when the choice defines product intent
  48. - update the spec only after the choice is clear
  49. Do not add scope. Remove or mark anything that cannot be verified. Preserve clear existing decisions.
  50. The tightened spec should include:
  51. - goal and non-goals
  52. - user-visible behavior
  53. - architecture and implementation constraints
  54. - files, modules, or systems likely involved
  55. - explicit edge cases
  56. - risk boundaries
  57. - scorecard with metric, threshold, regression checks, and stop condition
  58. - fast feedback loop with expected runtime and proxy validity
  59. - working-memory files for long-running goals
  60. - a minimal human control surface when the user may need visibility or steering during the run
  61. - verification commands or manual checks
  62. - user-approved `done_when` criteria
  63. ## Compile Mode
  64. Compile `SPEC.md` into `GOAL.md` using the block structure in `references/goal_prompt_blocks.md`. Load `references/standard_execution_rules.md` for default `<execution_rules>` content. If scaffolding long-run tracking files, load `references/working_memory_templates.md`. If the goal benefits from human steering during a long run, load `references/control_surface_templates.md`.
  65. Before writing `GOAL.md`, reject weak specs that lack:
  66. - measurable `done_when`
  67. - a scorecard for how Codex evaluates progress during the run
  68. - scope boundaries or non-goals
  69. - a fast feedback loop, or an explicit reason one is impossible
  70. - concrete verification commands or checks
  71. - enough context for an agent to start reading the repo
  72. If the spec is weak, route the user back to Interview or Tighten mode with a specific list of missing decisions. Do not write `GOAL.md` until the gaps are resolved.
  73. Concrete gate: each `done_when` item must name a command, file artifact, or user-observable behavior. Otherwise mark it as weak and ask for clarification.
  74. Scorecard gate: each `scorecard` must name the primary metric or checklist, the passing threshold, regression checks, the scoring command or inspection path, and the stop condition. If the score is model-judged, require a checklist or rubric that makes the judgment auditable.
  75. Feedback-loop gate: each `feedback_loop` must name a fast check, expected runtime, run cadence, why the proxy is representative enough, and the slower escalation or final check. If the only available check is slow, say so explicitly and adjust the workflow cadence.
  76. Working-memory gate: if the goal may run for hours, involves repeated experiments, or has high context churn, include a `working_memory` block. Prefer `PLAN.md`, `ATTEMPTS.md`, and `NOTES.md` unless the repo already has equivalent files. If no working-memory files are needed, state why the goal is short and linear enough to skip them.
  77. Human-control gate: if a goal may run while the user or another Codex session reviews in parallel, may consume scarce resources, may require strategic pivots, or may benefit from human priority changes, include a `human_control_surface` block and scaffold a compact `CONTROL.md`. Keep `CONTROL.md` small: only include knobs relevant to this goal. Do not create a second `GOAL.md` full of static instructions.
  78. Map the spec into the goal blocks:
  79. - spec summary -> `<goal>`
  80. - relevant files/modules/discovery commands -> `<context>`
  81. - architecture rules, non-goals, anti-patterns -> `<constraints>`
  82. - scoring metric, threshold, regression checks, stop condition -> `<scorecard>`
  83. - acceptance criteria -> `<done_when>`
  84. - fast iterative check and slower escalation check -> `<feedback_loop>`
  85. - implementation phases -> `<workflow>`
  86. - long-run tracking files and update cadence -> `<working_memory>`
  87. - user-visible status, tunable knobs, sidecar inputs, and pivot/resource gates -> `<human_control_surface>`
  88. - test/build/manual checks -> `<verification_loop>`
  89. - `references/standard_execution_rules.md` plus repo-specific rules -> `<execution_rules>`
  90. - final artifacts and completion signal -> `<output_contract>`
  91. After writing `GOAL.md`, self-check it:
  92. - `done_when` is measurable and user-approved
  93. - `scorecard` tells Codex how to score progress and stop
  94. - `feedback_loop` is fast enough to run repeatedly, or its limits are explicit
  95. - `working_memory` is present for long-running or exploratory work
  96. - `human_control_surface` is present when the user needs visibility or tuning knobs during a long run, and absent when it would be ceremony
  97. - context names files or discovery commands
  98. - constraints prevent obvious shortcuts
  99. - verification is executable or explicitly manual
  100. - the task is execution-oriented enough for `/goal`
  101. ## Config Check
  102. Use `scripts/inspect_codex_config.py` for a read-only report:
  103. ```bash
  104. python3 ~/.codex/skills/goal-forge/scripts/inspect_codex_config.py --project-path /path/to/project
  105. ```
  106. Run it from the target project root, or pass `--project-path`. The script reports the installed Codex version, selected config keys, trusted-project status, and gaps against the autonomous `/goal` configuration.
  107. Before telling the user a long-running `/goal` is ready, verify the config against `references/config_checklist.md`. The important autonomous settings are:
  108. - `model = "gpt-5.5"`
  109. - `model_context_window = 1050000`
  110. - `model_auto_compact_token_limit = 997500`
  111. - `model_reasoning_effort = "high"`
  112. - `plan_mode_reasoning_effort = "xhigh"`
  113. - `approval_policy = "never"`
  114. - `sandbox_mode = "danger-full-access"`
  115. - `[features] goals = true`
  116. Do not edit `~/.codex/config.toml` unless the user explicitly asks for config changes. If asked to change config, prefer applying the dangerous `approval_policy = "never"` and `sandbox_mode = "danger-full-access"` settings only for explicitly trusted project paths rather than globally.
  117. Read `references/config_checklist.md` when explaining config tradeoffs.
  118. ## Output
  119. Depending on the request, produce one or more of:
  120. - updated `SPEC.md`
  121. - generated `GOAL.md`
  122. - optional `PLAN.md`, `ATTEMPTS.md`, and `NOTES.md` scaffolds for long-running goals
  123. - optional `CONTROL.md` scaffold for long-running goals that need human visibility or tuning knobs
  124. - config readiness report
  125. - the exact `/goal` prompt body to paste into Codex
  126. When the user asks to run the goal, verify that their Codex version supports `/goal` first.
README.md · README · 101 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # goal-forge
  2. ![Goal Forge cover](assets/readme-cover.svg)
  3. Codex skill that turns a rough coding idea into a Codex `/goal`-ready contract.
  4. Pipeline: **rough idea → interviewed `SPEC.md` → tightened `SPEC.md` → budgeted `GOAL.md` → config readiness check**.
  5. Goal Forge treats long-running `/goal` work as a runtime system with five explicit parts:
  6. - **Budget** — optional ceilings on elapsed time, cost, iterations, or parallel work, with warning and exhaustion behavior.
  7. - **Scorecard** — the metric, checklist, threshold, regression checks, and stop condition Codex should use to judge progress.
  8. - **Feedback loop** — the fastest representative check Codex can run repeatedly while iterating, plus the slower final check used before completion.
  9. - **Working memory** — markdown files such as `PLAN.md`, `ATTEMPTS.md`, and `NOTES.md` that keep multi-hour runs coherent across context compaction.
  10. - **Human control surface** — an optional compact `CONTROL.md` with task-specific knobs, sidecar inputs, resource limits, and pivot gates the user can inspect or tune while a goal runs.
  11. A request such as `5 hour budget max` compiles into an explicit contract:
  12. ```xml
  13. <budget>
  14. max_elapsed_time: 5h
  15. warning_at: 4h30m
  16. check_interval: 15m
  17. on_warning: checkpoint_and_prioritize
  18. on_exhaustion: checkpoint_and_stop
  19. extension_policy: explicit_user_approval
  20. </budget>
  21. ```
  22. The budget is a ceiling, not a target. The run should finish as soon as `done_when` passes. Prompt-level budgets guide agent behavior; use an external supervisor when hard process termination is required.
  23. ## Modes
  24. - **Interview** — open-ended interview that forces decisions on scope, architecture, edge cases, verification, and resource budgets. Hard gate: spec is not "done" until `done_when` has user-approved measurable criteria.
  25. - **Tighten** — read `SPEC.md` skeptically; surface ambiguities with two interpretations + a recommendation.
  26. - **Compile** — emit `GOAL.md` using the XML block structure in `references/goal_prompt_blocks.md`. Weak specs route back to Interview/Tighten, especially when scorecard, feedback loop, budget semantics, or long-run working memory are missing.
  27. - **Check config** — run `scripts/inspect_codex_config.py` for a read-only report on Codex version, project trust, and the full autonomous `/goal` config.
  28. ## Install
  29. Drop the folder into your Codex skills directory:
  30. ```bash
  31. git clone https://github.com/michaelpersonal/goal-forge.git ~/.codex/skills/goal-forge
  32. ```
  33. Then invoke from Codex with `$goal-forge` or any of the natural-language triggers in `SKILL.md`'s frontmatter.
  34. ## Autonomous `/goal` config
  35. For multi-hour autonomous `/goal` sessions, the skill checks `~/.codex/config.toml` against this target configuration:
  36. ```toml
  37. model = "gpt-5.5"
  38. model_context_window = 1050000
  39. model_auto_compact_token_limit = 997500
  40. model_reasoning_effort = "high"
  41. plan_mode_reasoning_effort = "xhigh"
  42. approval_policy = "never"
  43. sandbox_mode = "danger-full-access"
  44. [features]
  45. goals = true
  46. ```
  47. `model_reasoning_effort = "high"` is for execution work. `plan_mode_reasoning_effort = "xhigh"` is for the planning pass. `model_auto_compact_token_limit = 997500` lets long sessions compact context before they hit the hard context limit.
  48. Use `approval_policy = "never"` and `sandbox_mode = "danger-full-access"` only in project paths you have explicitly marked trusted. They give the agent unsupervised filesystem access.
  49. Run the inspector from a target project root:
  50. ```bash
  51. python3 ~/.codex/skills/goal-forge/scripts/inspect_codex_config.py --project-path "$PWD"
  52. ```
  53. The report prints `autonomous_goal_status: ready` only when the config, feature flag, Codex version, and project trust are aligned.
  54. ## Layout
  55. ```
  56. goal-forge/
  57. ├── SKILL.md
  58. ├── agents/openai.yaml UI metadata + implicit invocation
  59. ├── references/
  60. │ ├── goal_prompt_blocks.md GOAL.md XML structure, including budget, scorecard, feedback loop, and working memory
  61. │ ├── budget_contract.md Budget normalization, warning, exhaustion, and extension rules
  62. │ ├── config_checklist.md Long-running /goal config notes
  63. │ ├── control_surface_templates.md Optional CONTROL.md knobs and sidecar collaboration patterns
  64. │ ├── standard_execution_rules.md Compile-time execution rules
  65. │ └── working_memory_templates.md PLAN.md, ATTEMPTS.md, and NOTES.md scaffolds
  66. └── scripts/
  67. └── inspect_codex_config.py Read-only config readiness report
  68. ```
  69. ## Credits
  70. Inspired by [@ynkzlk](https://x.com/ynkzlk)'s blog post [*Codex /goal: A Six-Hour Run*](https://www.tectontide.com/en/blog/codex-goal-six-hour-run/), which makes the case that long-running `/goal` runs succeed or fail on upfront specification discipline: explicit measurable `done_when` criteria, XML-structured prompts, and context architecture that keep the agent from taking shortcuts. This skill operationalizes that discipline as a repeatable pipeline.
  71. ## License
  72. MIT. See `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.