Civ Finish Quotes

civ-finish-quotes is a platform-neutral skill and toolkit for adding Civilization-style completion quotes to real finished work.

It is designed for agent environments such as Codex, Claude Code, or OpenCode: lightweight to install if you only want the skill, but also maintainable as a full quote-library project if you want to curate, rebuild, and extend the dataset.

简体中文 README

Quick Install

If you only want to use the skill, copy this repo into your agent’s skills/tooling directory, or install it from its GitHub source when published, and point your runtime at SKILL.md.

The runtime path is local and offline:

• the skill definition lives in SKILL.md
• the agent metadata lives in agents/openai.yaml
• the approved runtime library lives in assets/quotes/approved_quotes.jsonl

For most users, that is enough. Rebuilding the quote library is optional.

Showcase

Examples from Chinese and English agent conversations:

Example

Input payload:

{
  "task_summary": "Completed the architecture refactor and shipped the new system build.",
  "deliverable_type": "code",
  "completion_class": "engineering",
  "completion_mode": "build",
  "keywords": ["architecture", "refactor", "system", "build"],
  "user_language": "en",
  "recent_quote_ids": []
}

Render it locally:

python3 ./scripts/render_finish_quote.py \
  --library ./assets/quotes/approved_quotes.jsonl \
  --input-json ''

Typical output:

----------

"The fewer moving parts, the better. No truer words were ever spoken in the context of engineering."
-- Christian Cantrell, Containment

How It Works

The runtime flow is intentionally small:

1. Detect whether the agent is actually closing a substantial task.
2. Build a compact request payload with task summary, completion class, completion mode, keywords, and user language.
3. Rank quotes from the bundled approved library.
4. Render a short ceremonial block with quote, author, and source.

The selector is designed to avoid obvious misses:

• it skips small talk and trivial completions
• it applies a relevance floor before returning a quote
• it prefers language-matching display text when available
• it automatically avoids reusing the same quote within a rolling 24-hour local window when alternatives exist
• it writes local history to the user cache directory when possible, and falls back to a repo-local .cache/ in restricted environments
• it filters high-risk themes by default for ordinary tasks

Runtime Support

This repository is GitHub-first and runtime-neutral. The core contract is just SKILL.md, local Python scripts, and JSONL assets.

• Codex / OpenAI-style setups: install as a normal skill and invoke it near final task completion
• Claude Code-style setups: reuse the same renderer and payload shape in your finish-hook or post-task instruction flow
• OpenCode-style setups: treat this repo as a local skill package with a scripted completion step

Repository Layout

• SKILL.md: installable skill instructions
• scripts/render_finish_quote.py: final renderer used at task close
• scripts/select_quote.py: quote ranking and filtering
• scripts/build_quote_library.py: maintainer rebuild pipeline
• assets/quotes/approved_quotes.jsonl: bundled runtime library
• assets/quotes/raw_candidates.jsonl: normalized review pool
• references/quote-schema.md: data contract for requests and libraries

About This Repository

This repository is both:

• an installable skill for users who only want the completion behavior
• a maintainable quote toolkit for contributors who want to review, rebuild, and extend the library

It does not define a universal skill standard. It is a practical, file-based implementation intended to be easy to adapt across agent runtimes.

Distribution

GitHub is the canonical distribution source for this project.

• use the repository directly for project-local or user-local installation
• treat the repo as compatible with GitHub-backed skill indexes and installer workflows
• publish updates from the GitHub source of truth, not from copied zip snapshots

Development

Run the test suite:

python3 -m unittest discover -s tests

The repo is split into two use cases:

• users can install the skill and use the checked-in approved quote library directly
• maintainers can review raw candidates and rebuild the approved runtime library

License

MIT