IntentDNA

面向 Codex CLI、Claude Code 等 AI 编程环境的声明式工作流资产、同步与运行工具。

English | 路线转换文章 | 历史 Online 看板

项目状态 / Project status: 本项目后续不再进行独立扩展；新的研发自动化能力将以独立 CLI 等工具的形式在其他仓库开发。 / This project will not be expanded independently; new engineering automation capabilities will be developed in other repositories as standalone CLIs and related tools.

IntentDNA 把一套可重复的 AI 工作方法描述为版本化的 .dna.yaml 资产，并提供确定性的校验、编译、同步、运行和证据能力。你可以用它定义步骤、角色、权限、交接、检查点、重试和验证规则，再把工作流同步到本地 Harness 中执行。

它解决什么问题

AI 编程工作流经常散落在 Prompt、对话、个人经验和临时脚本中。IntentDNA 将这些方法变成可以审查和复用的工程资产：

• 用 YAML 明确适用场景、输入、输出、角色、步骤和边界；
• 在执行前确定性校验结构、引用、权限和工作流约束；
• 同步为 Codex Skills、Claude agents/skills/hooks 等 Harness 资产；
• 用 Controller 支持持久运行、并行步骤、检查点、审查、重试和恢复；
• 打包、签名并验证本地运行证据；
• 从真实 Skills 和源码提炼候选资产，同时保留来源与许可证信息。

核心边界是：

.dna.yaml 资产 = 工作流定义
dna validate / compile / sync = 确定性工具链
Codex CLI / Claude Code / provider = 实际执行环境
本地运行记录与 verifier = 完成证据
Online = 历史看板与可选投影，不是运行时

IntentDNA 不重造通用模型循环，不把 Online 或 Supabase 当作本地权限来源，也不接受模型的“已完成”声明替代验证结果。

安装

npm install --global intentdna@latest
dna --version

Claude Code 插件与 npm 包使用相同版本发布：

claude plugin marketplace add lushan1314/intentdna-repo
claude plugin install intentdna@intentdna

使用现有工作流

先查看内置资产，再在目标项目中初始化和同步：

dna templates list
dna templates show flutter-rewrite
dna quickstart --asset flutter-rewrite --sync-target codex

dna init --template flutter-rewrite
dna sync --codex --dry-run
dna sync --codex

dna quickstart 只输出指引；dna sync --dry-run 预览文件变更；dna sync 才会写入 Harness 资产，但不会自动运行工作流。

同步完成后，在对应项目中使用 Codex CLI 或 Claude Code 调用生成的 Skill、agent 或工作流入口。检查同步状态：

dna sync status
dna sync doctor

打造自己的工作流

IntentDNA 将“理解人的意图”和“确定性验证”分开：外部 Agent 负责访谈并编写 YAML，dna 负责提供完整创作契约并验证结果，人负责确认是否保存和采用。

1. 生成创作包

dna workflow authoring-packet "描述要沉淀的重复工作方法" \
  --project-dir /path/to/project \
  --json

创作包包含字段约束、红线、真实示例、访谈问题、校验循环和交接边界。这个命令不调用模型，也不生成或保存 YAML。

2. 让 Agent 编写候选资产

候选文件放在：

.dna/authoring/<asset>.candidate.dna.yaml

一个工作流资产通常包括：

• id、name、version、purpose、maturity；
• fit、not_for、inputs、outputs；
• roles 及其工具权限和读写范围；
• workflow 或 workflows 中的步骤、依赖、交接、检查点和重试；
• boundaries、evidence 和 lineage。

3. 校验并修订

dna validate .dna/authoring/<asset>.candidate.dna.yaml

Agent 只根据校验诊断和已确认的人类意图修改 YAML，直到校验通过。dna 不推断目标，也不会自动放宽边界。

4. 人工确认并加入项目资产库

确认候选内容后，将同一份 YAML 保存为：

.dna/templates/<asset>.dna.yaml

然后检查资产并预览同步结果：

dna assets show <asset> --project-dir /path/to/project
dna assets inspect <asset> --project-dir /path/to/project
dna sync --project-dir /path/to/project --dry-run
dna sync --project-dir /path/to/project --codex --dry-run

保存、采用和同步是彼此独立的人工决策。校验通过不代表资产已被采用或执行。

运行与证据

工作流可以在同步后的 Harness 中执行，也可以使用 IntentDNA Controller 的运行入口。可用命令以当前 CLI 帮助为准：

dna run --help
dna run status <run-id>
dna run inspect <run-id>
dna run resume <run-id>

真实执行后，可打包、签名并验证本地证据：

dna report package --json
dna report sign --package .dna/reports/latest-report-package.json \
  --output .dna/reports/ingest/local-envelope.json \
  --json
dna report verify .dna/reports/ingest/local-envelope.json --json

云端上传是可选能力，并且必须先通过凭证和部署检查。本地工作流的运行事实不会因为上传而转移到云端。

内置工作流类型

仓库包含多种可直接查看和复用的资产，包括：

• Flutter 重写、行为锁定、诊断与修复审查；
• 代码审查、TDD、QA、调试、迁移和发布证据；
• 并行子 Agent、多角色交接和持久执行；
• 研究改进、工作流创作和资产提炼；
• 安全开发、事故响应和组织基线。

使用 dna templates list 查看当前安装版本中的完整目录。

路线转换与历史

IntentDNA 曾优先建设跨 Harness 抽象、组织治理、市场和 Online 控制面。实践表明，这些机制具备工程可行性，但平台优先并不是后续研发自动化最合适的起点。

完整反思见《IntentDNA 路线重置：从平台优先到工作流 CLI》。

IntentDNA Online 看板 作为历史产品证据继续保留，用于展示当时的资产选择、安装指引和证据投影。它不执行工作流。

仓库中的当前文档和历史证据采用两态管理：少量 living docs 描述当前实现，带日期和索引的 docs/archive/ 保存路线演进；本地会话状态、临时提示词、运行日志和 IDE workspace 不进入版本控制。

文档

• 快速开始
• 工作流资产格式
• 工作流创作包契约
• Controller 与 worker 运行时
• 工作流运行时清单
• 本地证据捕获
• 产品重置 ADR
• 文档与历史档案索引

License

Apache-2.0

English

Declarative workflow assets, synchronization, and runtime tooling for AI coding harnesses such as Codex CLI and Claude Code.

Route reset article (Chinese) | Historical Online dashboard

IntentDNA describes repeatable AI work methods as versioned .dna.yaml assets and provides deterministic validation, compilation, synchronization, runtime, and evidence tooling. A workflow can define steps, roles, permissions, handoffs, checkpoints, retries, and verifiers before being synchronized into a local harness.

What It Solves

AI coding workflows often remain scattered across prompts, conversations, personal experience, and temporary scripts. IntentDNA turns those methods into reviewable engineering assets:

• define fit, inputs, outputs, roles, steps, and boundaries in YAML;
• validate structure, references, permissions, and workflow constraints deterministically;
• synchronize Codex Skills, Claude agents/skills/hooks, and other harness assets;
• support durable runs, parallel steps, checkpoints, reviews, retries, and recovery;
• package, sign, and verify local runtime evidence;
• refine candidates from real skills and source while retaining provenance and license data.

The authority model is:

.dna.yaml asset = workflow definition
dna validate / compile / sync = deterministic toolchain
Codex CLI / Claude Code / provider = execution environment
local run records and verifiers = completion evidence
Online = historical dashboard and optional projection, not runtime

IntentDNA does not rebuild the generic model loop, make Online or Supabase the authority for local execution, or accept a model's completion claim as a substitute for verification.

Install

npm install --global intentdna@latest
dna --version

The Claude Code plugin is released at the same version as the npm package:

claude plugin marketplace add lushan1314/intentdna-repo
claude plugin install intentdna@intentdna

Use An Existing Workflow

Inspect built-in assets, then initialize and synchronize one inside the target project:

dna templates list
dna templates show flutter-rewrite
dna quickstart --asset flutter-rewrite --sync-target codex

dna init --template flutter-rewrite
dna sync --codex --dry-run
dna sync --codex

dna quickstart only prints guidance. dna sync --dry-run previews file changes. dna sync writes harness assets but does not execute the workflow.

Use the generated Skill, agent, or workflow entry point from Codex CLI or Claude Code. Inspect synchronization state with:

dna sync status
dna sync doctor

Author A Workflow

IntentDNA separates probabilistic intent interpretation from deterministic validation. An external agent interviews the human and authors YAML; dna emits the complete authoring contract and validates the result; the human decides whether the candidate is saved and adopted.

Generate an authoring packet:

dna workflow authoring-packet "describe the repeated work method" \
  --project-dir /path/to/project \
  --json

The packet includes field constraints, red lines, real examples, interview questions, the validation loop, and handoff boundaries. It does not call a model or create YAML.

Have the external agent write the candidate to:

.dna/authoring/<asset>.candidate.dna.yaml

A workflow asset normally describes metadata, fit, inputs and outputs, roles and permissions, steps and dependencies, handoffs, checkpoints, retries, boundaries, evidence, and lineage.

Validate and revise it:

dna validate .dna/authoring/<asset>.candidate.dna.yaml

After explicit human confirmation, save the same YAML under .dna/templates/<asset>.dna.yaml, then inspect it and preview synchronization:

dna assets show <asset> --project-dir /path/to/project
dna assets inspect <asset> --project-dir /path/to/project
dna sync --project-dir /path/to/project --dry-run
dna sync --project-dir /path/to/project --codex --dry-run

Saving, adopting, and synchronizing are separate human decisions. Successful validation does not mean the asset has been adopted or executed.

Runtime And Evidence

Workflows can execute in the synchronized harness or through the IntentDNA Controller. Use the installed CLI help as the command authority:

dna run --help
dna run status <run-id>
dna run inspect <run-id>
dna run resume <run-id>

After a real run, package, sign, and verify local evidence:

dna report package --json
dna report sign --package .dna/reports/latest-report-package.json \
  --output .dna/reports/ingest/local-envelope.json \
  --json
dna report verify .dna/reports/ingest/local-envelope.json --json

Cloud upload is optional and credential-gated. Uploading evidence does not move runtime authority away from the local workflow.

Included Workflow Categories

The repository includes assets for Flutter rewrites and repair reviews, code review, TDD, QA, debugging, migrations, release evidence, parallel subagents, multi-role handoffs, durable execution, research improvement, workflow authoring, asset refinement, secure development, incident response, and organization baselines.

Run dna templates list for the complete catalog in the installed version.

Route Reset And History

IntentDNA previously led with cross-harness abstraction, organization governance, a marketplace, and an Online control plane. Those experiments demonstrated engineering feasibility, but platform-first development is not the chosen starting point for the next phase of task-specific automation.

The rationale is documented in IntentDNA Route Reset: From Platform to Workflow CLI.

The IntentDNA Online dashboard remains available as historical product evidence. It demonstrates the earlier asset selection, setup guidance, and evidence projection work; it does not execute workflows.

Current documentation and historical evidence follow a two-state model: a small living set describes the implementation, while dated, indexed files under docs/archive/ preserve route history. Local session state, temporary prompts, runtime logs, and IDE workspace data are excluded from version control.

Documentation

• Quickstart
• Workflow asset format
• Workflow authoring packet
• Controller and worker runtime
• Workflow runtime manifest
• Local evidence capture
• Product reset ADR
• Documentation and archive index

License

Apache-2.0