SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscs-goal

cs-goal

General & other

View repository

Updated 10-15 20:30

About this skill

cs-goal

Before any judgment or action, execute CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not read external AI entry points as a substitute (see .codestable/reference/execution-conventions.md）。

cs-goal Handle a bounded goal: the owner gives the starting point and expected end state, CodeStable first does a lightweight interview / grill, writes a starting-point report before acting, then autonomously implements, verifies, and iterates; before completion it must request a Task agent to do functional acceptance, and write an iteration report. The report body follows the project report language in .codestable/attention.md ; when there is no language policy, use the owner's current conversation language.

This is a goal wrapper and does not replace feature / issue / refactor rules. When a goal crosses a capability boundary, exposes a bug root cause, or requires behavior-invariant refactor governance, the corresponding feature / issue / refactor artifact must be created or referenced in a goal iteration.

For artifact templates,state.yaml schema, report headings, and recovery rules, see reference.md。

Startup

Before acting:

  1. Read .codestable/attention.md。
  2. If it exists, read .codestable/reference/system-overview.md。
  3. Read this skill's reference.md。
  4. If it exists, read .codestable/reference/goal-conventions.md。
  5. If it exists, read .codestable/reference/approval-conventions.md。
  6. Before code editing, review, commit, finish, or merge, if it exists, read .codestable/reference/execution-conventions.md。
  7. Check .codestable/goals/ for an existing matching active goal.
  8. When the goal points to an existing domain, search .codestable/compound/ and related feature / issue / refactor documents.

If .codestable/is missing, route to cs-onboard。

Usage scenarios

Use when the owner expresses a bounded goal cs-goal：

  • "starting from this broken state, make the tests pass";
  • "reach this acceptance result";
  • "run autonomously and self-iterate";
  • "keep trying until complete or blocked";
  • "grill me first, then implement";
  • "I care about the outcome, not the technical choices".

Do not use for:

  • Pure design, roadmap, or discussion requests with no goal implementation.
  • Open-ended brainstorm where the owner does not yet know the end state.
  • Status checks or audits that do not require the AI to drive to completion.

State model

Follow the Codex simple goal states:

active | complete | blocked

state.yaml is the machine source of truth, Markdown is for humans. Recovery priority:

  1. .codestable/goals/YYYY-MM-DD-{slug}/state.yaml
  2. latest iteration frontmatter
  3. Markdown body text

As long as state.yaml has a definite value, do not infer the current machine state from the report body.

Phase 1: Grill alignment

Always grill before creating a new goal. Treat interview / grill as the formal goal starting point, not a one-off chat. Keep it short and focused on owner-level information.

Ask at most 3-5 focused questions. One question per round, with 2-4 substantively different options. Unless the answer would change the goal boundary, do not ask about implementation details.

If the grill answers require owner approval of scope, route, budget, risk, or stopping strategy, and the options need explanation, first write .codestable/goals/YYYY-MM-DD-{slug}/approval-report.md. Simple clarification questions can stay in chat; decision checkpoints must have a report.

Collect only:

  • objective。
  • starting point。
  • acceptance / done signal。
  • non-goals。
  • The budget or stopping preference already given.
  • Strict owner-stop conditions specific to this goal.

If the owner has already given enough information, summarize before continuing. Before any code edit or autonomous implementation attempt, Phase 2 must create or refresh the starting-point report.

Phase 2: Create or resume Goal

Goal lifecycle directory:

.codestable/goals/YYYY-MM-DD-{slug}/
├── state.yaml
├── goal.md
├── functional-acceptance.md
└── iterations/

The directory name uses the goal creation date, keeping the same style as feature / issue / refactor directories. state.yaml of goal field keeps the bare business slug.

functional-acceptance.md Only create it at the terminal acceptance gate, not as an empty file when the goal starts.

goal.md It is a persistent starting point report generated from interview / grill and must exist before implementation. Its content includes objective, starting point, acceptance criteria, non-goals, owner decisions, unresolved assumptions, and next action. Keep it concise and update it only at goal boundaries or when state changes.

By default use the canonical report path with no suffix. If .codestable/attention.md explicitly requires additional language copies, then add suffixed copies such as goal.{lang}.md、functional-acceptance.{lang}.md、 iterations/{nnn}.{lang}.md ; these variants are not required by default.

If a matching active goal already exists, resume it instead of creating a duplicate directory, even if the date prefix is not today. First read state.yaml, then read the starting point report matching goal*.md , then read the latest iterations/{nnn}*.md. If the starting point report is missing, rebuild it from state and interview evidence before editing code.

Phase 3: Autonomous iteration

One iteration is one coherent implementation / verification attempt, not one command.

Loop while state: active :

  1. From state.yaml choose the smallest useful next attempt.
  2. Implement according to the existing CodeStable constraints; when applicable this includes worktree, review, spec-governance, and commit rules.
  3. Verify with fresh commands or evidence.
  4. Before modifying state.yaml.current_iteration , derive the next three-digit iteration number from state.yaml.current_iteration and the existing iterations/{nnn}*.md files; do not overwrite old reports.
  5. Update state.yamlfor the completed attempt, leaving current_iteration: {n}。
  6. write the canonical report for that completed iteration:iterations/{nnn}.md. Only add language-suffixed copies when .codestable/attention.md requires them.
  7. Continue autonomously unless an owner-stop condition is triggered.

Do not write a report after every command; a report is an iteration summary. Do not mark the goal complete based only on ordinary test evidence; the terminal functional acceptance gate must be run first.

Terminal functional acceptance

Before changing state.yaml.status to complete :

  1. Run normal verification with fresh evidence.
  2. According to .codestable/reference/execution-conventions.md 's Task agent selection rules, start a Task agent to perform functional acceptance against the recorded owner acceptance criteria and actual product / artifact behavior.
  3. Write the result to functional-acceptance.md, including reviewer, scope, acceptance checks, functional evidence, verdict, residual risks, and follow-up.
  4. Reference the functional acceptance report in the final iteration.

Functional acceptance is product-facing evidence. It can include black-box usage, artifact inspection, UI / API workflow checks, fixture output review, or other proof relevant to the owner. Unit tests, lint, and build are useful evidence, but alone they are not sufficient to complete the goal.

If a Task agent cannot be started or is not authorized, write approval-report.md and owner-stop; do not self-accept the goal as complete.

Strict Owner Stop

Stop and ask the owner only in the following cases:

  • The acceptance criteria conflict, or are no longer sufficient to judge completion.
  • There is significant ambiguity in the objective, start point, or terminal condition.
  • Continuing would change long-term spec, public contract, or capability boundary beyond the recorded goal.
  • The same blocker appears repeatedly for three consecutive iterations.
  • budget is exhausted or nearly exhausted.
  • The next step requires explicit human risk acceptance, secrets, destructive operations, external purchases, merge / deployment approval.

Ordinary technical choices, test failures, implementation alternatives, and local refactors are the AI's responsibility, unless they cross the above stop conditions.

Complete and Blocked rules

Only when the acceptance signal has been satisfied, the Task agent functional acceptance report records a passing verdict, and the evidence has been written into the final iteration can it be marked complete。

Only when the same blocker repeats for at least three consecutive iterations, or the owner-stop rule states that the AI cannot safely continue, can it be marked blocked. Record blocker_signature、blocker_count, the evidence, and the required owner decision. Before asking the owner for a decision, first write in the goal directory approval-report.md, unless the latest iteration report already contains the full decision context, options, recommendation, trade-offs, evidence, consequences, and next steps.

If the budget ends before acceptance, stop with approval context; do not pretend it is complete.

Exit

The goal run exits with one of the following statuses:

  • complete: acceptance evidence, Task agent functional acceptance, and the final iteration have all been written.
  • blocked: blocker evidence and the owner question have been recorded.
  • active: the iteration report and next action have been recorded, but the current turn or budget is insufficient to continue.

The final reply should be short; when the goal is complete, point to goal.md, the latest iteration report, and functional-acceptance.md。

Guardrails

  • Do not make the owner choose everyday technical details.
  • Do not let the report body override state.yaml。
  • Do not create duplicate active goals for the same objective.
  • Do not skip iteration reports after substantive work.
  • Do not mark completion based on tests alone, and do not fake Task agent acceptance.
  • Do not continue iterating after a strict owner-stop is triggered.
  • Each Markdown artifact must be fewer than 300 lines; split it if it is too long.