Why Swift Cycle

AI-assisted delivery often breaks at the handoffs: requirements evolve, repository reality diverges from the plan, local execution notes become mistaken for shared truth, and “done” is declared without fresh evidence.

Swift Cycle reconnects those handoffs without turning a small project into a governance program. It inspects the real state, chooses process proportional to the task, ships the smallest reviewable increment, and synchronizes what was learned.

Loop Engineering

Loop Engineering is the discipline of keeping intent, execution, evidence, and learning connected in one short, repeatable feedback loop.

flowchart LR
    A["SCAN<br/>real state"] --> B["SHAPE<br/>shared truth"]
    B --> C["SHIP<br/>smallest reviewable increment"]
    C --> D["VERIFY<br/>fresh evidence"]
    D --> E["LEARN<br/>synchronize or revert"]
    E --> A

The product model expands the loop; the execution rhythm stays intentionally short:

Scan quickly → make the smallest useful change → verify immediately → continue or revert.

AI Skill capabilities

Capability	What Swift Cycle does
Project shaping	Reads the repository before acting, establishes only the useful project structure, and makes boundaries explicit.
Scenario routing	Selects the smallest useful route for bootstrap/adopt, small changes, features, bug fixes, research, runtime integration, closeout, or document retirement.
Document profiles	Starts from minimal, standard, or runtime_integration without forcing a fixed document tree.
Language adaptation	Resolves conversation and file language separately, preserving existing file language and bilingual boundaries.
Governance Baseline	Captures a proportional before-state when non-trivial governance needs reliable comparison across authority or delivery boundaries.
Knowledge Promotion	Moves durable commitments, decisions, constraints, and reusable evidence from local capture into responsibility-appropriate shared assets.
State Separation	Splits composite labels into only the independent lifecycle concerns a project actually tracks, without imposing a fixed schema.
Commit Boundary Planning	Defines coherent, independently reviewable commit scopes before staging mixed, ordered, or multi-commit changes.
Source/Runtime Boundary	Keeps source, artifact, runtime, and consumer claims independently evidenced and authorized.
Freshness and learning	Detects stale status, freezes review snapshots, retires obsolete documents safely, and promotes confirmed failure guards.
Adaptive execution	Keeps simple work as a normal TODO; activates a milestone and dependency-ordered PR queue only when the work needs it.
Evidence-backed delivery	Keeps each increment reviewable, verifiable, and reversible, then continues or corrects based on fresh evidence.
Portable orchestration	Ships one standards-aligned Skill with localized guidance and host-specific metadata—without scripts, MCP servers, or external services.

Quick Start

GitHub CLI 2.90 or later can install the same Skill for multiple agent hosts.

Codex

gh skill install Solismuchengxue/skill_swift_cycle swift-cycle --agent codex --scope user

Invoke with $swift-cycle.

Claude Code

gh skill install Solismuchengxue/skill_swift_cycle swift-cycle --agent claude-code --scope user

Invoke with /swift-cycle.

GitHub Copilot

gh skill install Solismuchengxue/skill_swift_cycle swift-cycle --agent github-copilot --scope user

Invoke with /swift-cycle.

For project-only installation, replace --scope user with --scope project. See agent compatibility for platform behavior and manual installation paths.

What this project demonstrates

Swift Cycle is also an engineering portfolio artifact: it shows how a compact AI capability can be shaped, packaged, bounded, and verified for real delivery work.

FDE capability	Repository evidence
Solution shaping	Turns ambiguous maintenance requests into explicit scope, document responsibilities, and delivery contracts.
AI Skill productization	Packages a working methodology as a portable Agent Skill with bilingual guidance and host-specific metadata.
Delivery orchestration	Selects lightweight execution for small work and dependency-aware, PR-sized increments for larger work.
Evidence-first execution	Connects implementation, validation, rollback, and shared-state synchronization instead of treating output as proof.
Cross-context communication	Maintains equivalent English and Chinese product narratives for technical and business-facing readers.

How it works

Shared truth and local execution

Layer	Responsibility
README.md	User-facing value, installation, usage, and current limitations.
DESIGN.md + docs/	Durable design, requirements, roadmaps, evaluations, runbooks, and ADRs.
AGENTS.md	Repository-specific collaboration, safety, synchronization, and verification rules.
Local TODO.md	Current actions and blockers; only larger work adds an active milestone and PR queue.
Local DEVLOG.md	Failures, rejected approaches, maintenance evidence, and evolution history.

The local TODO is an execution view, not the only long-term plan. Cross-machine commitments stay in a committable feasibility report, docs/roadmap.md, or a shared issue tracker.

Swift Cycle selects a document profile after it selects the task scenario:

• minimal: existing core entry points plus local execution records and only necessary shared docs.
• standard: adds architecture, roadmap, evaluation, or ADR authorities only when corresponding durable facts exist.
• runtime_integration: adds operations, contracts, security, storage, integration, and identity evidence only for delivery layers the project actually has.

Profiles are starting configurations, not mandatory trees. Optional templates live under templates/ and are adapted to the resolved file language.

Governance boundaries

Swift Cycle activates governance only when repository evidence requires it:

• Governance Baseline: record the observed state before non-trivial governance, migration, replacement, or cross-boundary work; keep it separate from the intended outcome.
• Knowledge Promotion: promote durable commitments, decisions, constraints, and verified evidence into shared assets; keep short-term actions and one-off failures local.
• State Separation: separate a composite status only when it represents independent lifecycle questions with different closure evidence.
• Commit Boundary Planning: plan coherent commit scopes before staging when changes have mixed purposes, ordered dependencies, or multiple reviewable increments.
• Source/Runtime Boundary: verify source, artifact, runtime, and active-consumer claims at their own layers; evidence and authorization do not transfer between them.
• Documentation freshness: reconcile status, decisions, plans, identities, and frozen Review Packets when real milestones or boundaries change.

These capabilities are trigger-based. Simple, local, explicit changes continue to use the short loop without extra governance artifacts.

Proportional delivery

• Simple task: use a normal TODO checklist and the short verification loop.
• Multi-PR or milestone task: maintain a current milestone and dependency-ordered PR queue.
• Every PR-sized increment: record its ID, milestone, deliverable, scope, dependencies, verification, status, and PR link; keep it independently reviewable, verifiable, and reversible.

Small, local changes stay lightweight. Swift Cycle does not require an RFC, ADR, design document, or PR queue for every edit.

Example delivery loops

$swift-cycle Initialize a lightweight maintenance framework for this repository.

$swift-cycle Review the current documentation boundaries and fix only meaningful drift.

$swift-cycle Maintain this three-PR migration as a current milestone and dependency-ordered PR queue.

$swift-cycle Close out this project, reconcile the docs, and extract reusable methodology.

Use the invocation syntax supported by your agent host.

Compatibility and boundaries

• Swift Cycle is deliberately invoked by the user; it does not imply autonomous background execution.
• Codex, Claude Code, and GitHub Copilot use the same canonical package with host-specific behavior documented in agent compatibility.
• The canonical workflow resolves conversation and file language separately. This repository currently maintains an English Skill body, bilingual user entry points, and Simplified Chinese operational terminology in references/zh-CN.md.
• The package follows the open Agent Skills specification.
• No scripts, runtime dependencies, MCP servers, or external services are required.

Repository layout

skill_swift_cycle/
├─ skills/swift-cycle/
│  ├─ SKILL.md
│  ├─ agents/openai.yaml
│  ├─ references/
│  │  ├─ zh-CN.md
│  │  └─ document-profiles.md
│  └─ templates/                 # Optional profile-aligned starting points
├─ docs/compatibility.md
├─ README.md
├─ README.zh-CN.md
├─ DESIGN.md
├─ AGENTS.md
└─ LICENSE

Words in the repository name are separated with _. The standards-defined Skill name remains swift-cycle because Agent Skills names permit lowercase letters, digits, and hyphens.

License

Swift Cycle is released under the MIT License.