Embed pre-commit and code-quality guardrails in spec template and agent prompt

[caoergou]

Problem

During a real owloop go run, the implementation agent produced commits that contained unrelated side-effect files (backend/uv.lock, logs/events.jsonl) and helpers with suboptimal implementation details (primitive-value sentinel, missing type hints). These issues are not caught by the current pytest/ruff acceptance gates.

The current approach of creating many small external agent skills is not ideal: it fragments maintenance and makes it hard for the agent to know which skill to invoke.

Proposed solution

Instead of multiple independent skills, bake quality guardrails directly into owloop's existing artifacts:

1. Spec template
   Add standard checklist items to every generated spec under ## Requirements or ## Verification, for example:

   • Before committing, run git status --short; revert any side-effect files (lockfile, log, cache, coverage) unless the spec explicitly requires changing them.
   • New helpers must include type hints.
   • Do not use primitive values (e.g. True, None) as sentinels; use a private sentinel object.
   • If the refactor changes error-response order or control flow, document it in a <behavior-change> note.

2. Implementation agent system prompt
   Prepend a concise fixed instruction to every implementation agent run:

   • Review git diff --cached --stat before each commit.
   • Keep commits scoped to the spec's target files.
   • Prefer semantic return types; avoid mixed-type returns when possible.
   • Preserve existing behavior unless the spec explicitly allows a change.

3. Single optional skill (only if needed)
   If users want a reusable external checklist, provide one owloop-quality skill that combines pre-commit review, helper quality, and behavior-change note templates. Do not split these into separate tiny skills.

Why this is better

• No proliferation of micro-skills.
• Every spec and every agent run inherits the same guardrails by default.
• Constraints are visible to users in the spec itself, making failures explainable.

Acceptance criteria

• The default spec template includes pre-commit / quality checklist items.
• The implementation agent receives a fixed quality instruction in its system prompt.
• A new end-to-end run does not commit lockfile/log/cache side effects.
• New helpers in a test run include type hints and avoid primitive sentinels.

Related

• Meta issue: owloop go end-to-end UX issues (Meta: owloop go end-to-end UX issues discovered during refactor test #75)
• Spec auto-generator emits invalid specs (Spec auto-generator emits invalid specs with missing titles and self-contradictory Exclusions #73)