Cynos

Languages: English · 简体中文

Cynos is an autonomous AI engineering runtime for the pi coding agent. It lets an agent work freely, then verifies completion with evidence-based checkpoints instead of trusting a plain "done" message.

The name Cynos comes from cynosure — the North Star: a guiding point for agents to navigate complex engineering work without losing the evidence trail.

Why Cynos

AI agents are great at producing convincing completion summaries. The hard part is trusting them.

• "I fixed the bug" — did it actually reproduce first?
• "Tests pass" — did it run the real test suite, or summarize from memory?
• "I updated the docs" — did it really write the file?

Cynos changes the trust model. The agent works however it wants; before it claims done, Cynos checks the claim against captured tool results — the actual reads, writes, bash commands, search/fetch results, and subagent calls that happened in the session. No captured evidence, no completion.

completionEvidence  →  explains what the agent says happened
capturedToolResults →  proves what actually happened
checkpoints         →  decide whether the work is really complete

Quick start

Install Cynos into pi (global, for the current user):

pi install npm:@cynos-ai/engineer

Or install it project-locally (writes to .pi/settings.json, shareable with your team):

pi install npm:@cynos-ai/engineer -l

Open pi in any project and just describe the work in natural language:

> Add a multiply function to src/app.ts and verify it works.

Cynos routes the request to the right practice (here: develop), lets the agent implement, then runs cynos_check_completion. If a checkpoint finds missing real evidence, the work stays active with an actionable reason — not a false "done". When all checkpoints pass, the work is archived under .cynos/archive/.

Upgrade or remove:

pi update --extensions       # upgrade all installed packages
pi remove npm:@cynos-ai/engineer

Benchmark baseline

All project benchmark and smoke-test baselines are run with DeepSeek; the current benchmark suite passes under DeepSeek.

Core model

practice = methodology skill + completion checkpoints
work     = objective + acceptanceCriteria + status + completionEvidence + capturedToolResults

There is no activity state machine and no per-step ceremony. The agent starts a work item, explores/edits/tests normally, then calls cynos_check_completion. If checkpoints fail, the work stays active with actionable missing evidence. If they pass, the work is archived under .cynos/archive/.

Practices

Cynos currently includes 12 practices:

• review — read-only assessment of existing code, design, PRs, commits, or docs
• docs — documentation/report-only changes with no runtime behavior change
• onboard — understand an existing project and create/refresh durable project memory
• init — create a new project from scratch
• debug — reproduce, diagnose, fix, and verify bugs or failures
• test — test/validate existing behavior by running it and reporting a PASS/FAIL/FLAKE/BLOCKED verdict
• develop — implement features, runtime config, and general changes
• refactor — behavior-preserving structural changes with baseline/final verification
• ui-design — visual UI/design-system/styling work with browser evidence
• usability — frontend usability observation, fix, and re-verification
• release — push/tag/publish/deploy/CI-CD/post-release validation
• default — narrow fallback when no specific practice fits

Users can describe work naturally or use slash commands such as /review, /test, /develop, /debug, /release, and /onboard.

Tools

Work lifecycle:

• cynos_start_work · cynos_work_status · cynos_check_completion
• cynos_ask_user · cynos_resume_work · cynos_abandon_work

Capabilities:

• cynos_subagent · cynos_search · cynos_fetch

State and configuration

Project state lives in the target project:

.cynos/
  work.json
  last-outcome.json
  archive/

User configuration lives in:

~/.pi/agent/cynos-config.json

The /cynos-config command edits common settings: language, onboard mode, vision model, subagent timeout, work-aware compaction, and telemetry. Telemetry is opt-in (off by default); a one-time consent prompt asks on first session.

License

Copyright (c) 2026 Jay Shen. All rights reserved.

This package is distributed under a proprietary license that permits installation and use (including inside AI coding agents), with copyright attribution required and redistribution prohibited. The skill and subagent content is shipped in readable form so that agents can load it at runtime — this readability is a feature of the software, not a grant of additional rights.

• Full license text: see LICENSE
• Third-party content: skills/ui-design/ is MIT-licensed, bundled from ConardLi/garden-skills. See skills/ui-design/LICENSE and skills/ui-design/SOURCE.md. That directory is governed by its upstream MIT license, not by the package's proprietary license.

For commercial licensing or partnership, contact: [email protected]