yotta-workflow

What it is

AI sessions are inherently stateless: each conversation is independent, and the longer a chat grows the more memory it loses; switching sessions or agents means the previous context is gone. The built-in memory solutions of each platform usually serve a single agent, so different agents each keep their own records and produce multiple "sources of truth".

yotta-workflow distills "cross-session collaboration" into an agent-agnostic protocol that answers three questions:

• Where is the state stored and in what format? — determined by rules, not left to each agent's free choice.
• When to read, when to write? — read on start, write actively while working, always leave an anchor on finish.
• How to hand off? — a fixed template generates a self-contained handoff anchor; the next session resumes painlessly from just that anchor.

It depends on no specific agent or platform: the state is just Markdown files under the project root, readable and writable by any agent or tool.

Core value

• One source of truth — all agent sessions of the same project read and write the same .workflow\ state directory, instead of each building its own and keeping separate records.
• State follows the project root — .workflow belongs to the project root, not to a source checkout or a workspace container; an existing .workflow is always reused in place and never auto-migrated.
• Proactive anti-amnesia — every completed action is written to logs / tasks / decisions while working, not relied on in-conversation memory (context gets auto-compressed).
• Self-contained handoff — on finish, generate a fixed-format handoff anchor; the next session restores full context from the anchor plus state files.
• Compatible with existing mechanisms — if the project already has its own handoff / state mechanism, keep it, only satisfying two mandatory points: read state on start, update state and leave an anchor on finish.

Core advantages

Protocol details

Path model and state file location rule

First distinguish three concepts: the project root owns the whole project state and is the only anchor for .workflow; the source directory is normally a code subdirectory under the project root; a workspace root is only a container for multiple project roots.

<project root>\
├── .workflow\         # state; directly under the project root
└── <source dir>\      # source directory; under the project root

Resolution order (two signals only):

1. The user explicitly specifies a project root → use it.
2. Walk upward from the cwd and use the nearest existing .workflow\STATE.md; its parent is the project root. Keep it in place; never auto-migrate it.
3. If neither signal exists, stop and ask: What is this task's project root directory? Do not infer it from .git, package.json, src, README, the cwd, or directory structure.

This skill defines only the standard layout and state location. How a real project names or layers its source directories is left to the user to adapt.

Project state system (five file types)

Three-phase protocol

On start (every session) — locate the state directory by the rule → if present, fully read STATE / TASKS / ROADMAP / DECISIONS and recent logs to restore context; if absent, initialize all files and confirm with the user; a session delivers one milestone.

While working (write actively, don't rely on memory) — append to the day's log after each completed action; update TASKS status in real time; write directional decisions into DECISIONS on the spot; keep STATE "current progress" up to date; key info must be persisted, not left only in the conversation.

On finish (every session) — update STATE / TASKS / ROADMAP → append the day's log → generate a handoff anchor by template and output it verbatim for the user to copy.

Handoff anchor format

On finish, output by the fixed template; the anchor must be self-contained and its content must match the state files (never invented). The full template is in SKILL.md "五、交接话术模板". Structure points:

Usage examples

On start — read state, then talk about the task:

Please read .workflow\STATE.md, TASKS.md, ROADMAP.md first to restore the project context.

While working — after completing one thing, persist it immediately:

Completed "xxx", append to logs\2026-08-25.md; tick the TASKS.md item; update STATE.md current progress.

On finish — generate a handoff anchor by template:

Handoff anchor for your next session

【会话交接锚点】
项目：<project name>（<one-line positioning>）
路径：<project root absolute path>
上次会话结束于：<date>
当前进度：…
下一步（按优先级）：…
开工请先读取：.workflow\STATE.md、TASKS.md、ROADMAP.md

When to trigger

Use this skill in these scenarios:

• When starting or ending a work session, or resuming a project.
• When the project state changes (completing a task / recording a decision / updating the roadmap).
• When you need to leave a self-contained handoff anchor for the next session, or read an existing one.

It is not needed for one-off read-only questions (e.g. "what does this function mean").

Installation

Pick any of the four methods below; the order is the recommended priority. Skill files always come from npm (GitHub can be slow without a proxy; npm supports mirrors).

Method 1: npm one-liner (recommended)

# Optional China mirror: npm config set registry https://registry.npmmirror.com
npx -y @yottameta/yotta-workflow@0.4.3 --agent <agent-name>      # install to the agent's default user-level skills dir
npx -y @yottameta/yotta-workflow@0.4.3 --dir <your-skills-dir>   # point to the skills dir itself (e.g. ~/.codex/skills)

• --agent <name> installs to that agent's default user-level directory; --list shows each agent's default directory.
• --dir <path> installs to the given directory; for agents not in the preset list, point --dir at their skills directory.
• If the mirror has not synced the new package (404): add --registry=https://registry.npmjs.org/ (a proxy may be needed in China), or wait for the mirror cache.

Method 2: git clone (developers / git available)

git clone https://github.com/YottaMeta/yotta-workflow.git <your-skills-dir>/yotta-workflow

Method 3: GitHub Download ZIP (manual / no git)

On the GitHub repository YottaMeta/yotta-workflow, click Code → Download ZIP, unzip it and put the yotta-workflow folder into the agent's skills directory.

Method 4: install.sh (multi-agent one-liner script)

bash install.sh --agent <name>   # install to the agent's default user-level directory
bash install.sh --dir <path>     # install to the given directory
bash install.sh --list           # list agents -> default directories

Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.

Upgrade / uninstall

• Upgrade: reinstall the latest version to overwrite — rerun the install command you used (e.g. npx -y @yottameta/yotta-workflow@0.4.3 --agent <name> or bash install.sh --agent <name>). Old files in the skill directory are replaced; the project state files (.workflow\) are unaffected.
• Uninstall: delete the yotta-workflow folder under the target agent's skills directory (see the table above). Uninstalling does not affect state files already written into a project.

FAQ

• Where is the state directory? Accept an explicitly specified project root first; otherwise walk upward from the cwd to find an existing .workflow\. If neither exists, ask. State always lives at <project root>\.workflow\, not in a source directory or workspace root.
• Multiple agents out of sync? Confirm they point to the same project directory (the same .workflow\). This skill is designed to share one state; if each built its own .workflow, the project directory differs.
• The source directory has .git; should state live there? Not by that signal alone. State belongs under the project-root .workflow; the user decides how source directories are organized.
• Project already has its own handoff mechanism? Keep it, only satisfying the two mandatory points: read state on start, update state and leave an anchor on finish.

Development & checks

Run inside this project: python tools/validate-skill.py yotta-workflow.

References

• references/faq.md
• references/path-model.md
• references/walkthroughs.md
• references/exception-playbook.md

License

MIT © YottaMeta