@aprchell/agent-workflow

English | 中文

Install a project-owned agent coding workflow into an existing repository.

This project distills a reusable agent coding engineering workflow from DeepSeek Harness. It keeps the portable rules, skills, and Agent Note protocols while removing source-repository history and decisions. After installation, all files belong to the target project.

Agent Coding Workflow

The installed workflow guides an agent through a repeatable loop:

flowchart LR
    A[Receive task] --> B[Inspect project and rules]
    B --> C[Plan the smallest change]
    C --> D[Implement]
    D --> E[Run relevant checks]
    E --> F{Complete?}
F -- No --> B
F -- Yes --> G[Record an Agent Note when needed]

Loading

pnpm dlx @apr01chell/agent-workflow init
npx @apr01chell/agent-workflow init

The installer prompts for English, Chinese, or bilingual assets. Non-interactive usage supplies the language explicitly:

agent-workflow init --language en --conflict abort
agent-workflow init --language zh --conflict skip
agent-workflow init --language bilingual --conflict overwrite
agent-workflow upgrade --conflict abort

The default conflict policy is abort. overwrite is transactional and restores replaced files if installation or upgrade verification fails. upgrade uses .agents/workflow.json and per-file hashes to preserve local edits. Installed files are copied into .agents/ and the workflow-owned docs/ protocol files; they belong to the target project and do not depend on this package at runtime.

CLI and GitHub skill discovery

This repository exposes two independent entry points. Use the CLI when you want to install the complete project-owned workflow, including notes, documentation protocols, scripts, and localized assets. Use the top-level skills/ directory when an Agent application can discover skills from a local directory or GitHub repository path; each skill uses the standard skills/<name>/SKILL.md shape.

To test GitHub discovery before publishing, build the public catalog and enter this repository's absolute path in the Agent application:

pnpm run sync:skills
# Enter /absolute/path/to/aprchell-dev-pipeline or its skills/ subdirectory in the application.

After publishing, enter aprchell/agent-workflow, its GitHub URL, or the repository's local checkout according to the application's importer. Discovery behavior is application-specific: tools that scan skills/<name>/SKILL.md are supported by this catalog, while tools requiring another vendor-specific directory need an adapter and are not assumed to work automatically. This repository does not provide a Claude Code plugin layout.

Most public skill directories contain only SKILL.md plus required agents/ or references/ files. record-browser-gif also carries its required local encoder under scripts/; unrelated workflow scripts remain in the CLI template.

Start with skills/aprchell-agent-coding-workflow/SKILL.md when you want one coordination entry point. It classifies the task and links to only the specialist skills that apply; the other catalog directories remain independently discoverable.

Agent software importer	Compatibility
Scans a GitHub repository's skills/<name>/SKILL.md tree	Supported
Scans a local checkout's skills/<name>/SKILL.md tree	Supported after pnpm run sync:skills
Requires a vendor-specific directory or plugin manifest	Not provided by this repository

Installed Layout

init installs the workflow assets below. Empty Agent Note lifecycle and class directories are created later, when the project first needs them.

.
├── .agents/
│   ├── NOTICE.md                         # upstream attribution
│   ├── workflow.json                     # template version and per-file hashes
│   ├── notes/                            # agent-facing decisions and proposals
│   │   ├── README.md                     # lifecycle, naming, and file format
│   │   ├── AGENTS.md                     # rules for this subtree
│   │   ├── implemented/AGENTS.md         # shipped-decision rules
│   │   └── archived/AGENTS.md            # frozen-record rules
│   ├── skills/                           # reusable agent workflows
│   └── scripts/                          # opt-in checks and workflow helpers
└── docs/
    ├── AGENTS.md                         # human-facing documentation standard
    ├── postmortem/README.md              # incident write-up protocol
    └── i18n/                             # bilingual documentation protocol
        ├── README.md                     # pairing contract and scope
        ├── translation-rules.md          # translation structure and fidelity rules
        └── terminology.md                # portable terminology baseline

The installer does not copy historical decision records from DeepSeek Harness. It also never creates or edits the target project's root AGENTS.md.

The repository's own template sources make language explicit in filenames such as README.en.md, README.zh.md, SKILL.en.md, and SKILL.zh.md. Installed projects keep standard discovery names (README.md, AGENTS.md, and SKILL.md); bilingual installs add .zh.md companions and fresh .i18n.json pairing records.

Included Skills

Skills are reusable procedures under .agents/skills/<skill>/SKILL.md. An agent chooses the skill that matches the current change; skills do not replace the project's own build and test commands.

Skill	Purpose
aprchell-agent-coding-workflow	Coordinate the workflow and route each task to the smallest applicable specialist skill.
archive-agent-notes	Freeze completed implemented notes and seal archived records.
code-review	Review changes for correctness, regressions, security, and missing tests.
doc-site-sync	Keep documentation source, generated pages, navigation, and validation aligned.
doc-standards	Apply the repository's documentation structure and writing rules.
find-simplifications	Identify unnecessary complexity and smaller designs before implementation.
merging-stacked-prs	Safely integrate dependent or stacked changes.
pre-push-checks	Discover and run the smallest relevant checks before pushing.
prose-standard	Improve durable technical prose, terminology, and readability.
translate-docs	Translate documentation while preserving protocol tokens and links.
trim-cot-leakage	Remove internal reasoning traces from user-facing or durable documents.
record-browser-gif	Capture browser workflows as GIF evidence when a project needs it.

Each skill may include agents/openai.yaml, references, or helper scripts. These files are local project assets after installation.

The shared scripts include workflow-lib.mjs for workflow-owned file discovery, opt-in validators for Agent Note trees and formats, archived records, Markdown links, skill metadata, bilingual translation pairs, and documentation word-count budgets. Git-internal scope helpers are intentionally excluded; these scripts are not a replacement for the target project's own tests.

Agent Notes

.agents/notes/ is for the agent and maintainers making decisions. It is not a user documentation area. An Agent Note records a non-trivial decision: the problem, chosen direction, alternatives, consequences, and verification. Mechanical edits do not need a note.

Notes use this path and filename format:

<lifecycle>/<class>/yyyy-mm-dd-topic-title.md

The available classes are feature, bug-fix, simplification, architecture, process, and testing. The lifecycle directories form the state machine:

stateDiagram-v2
    [*] --> proposed: new decision
    proposed --> implemented: shipped
    proposed --> rejected: declined
    implemented --> archived: rationale no longer active
    rejected --> [*]: delete when no longer useful
    archived --> archived: frozen forever

Loading

• proposed/ contains reviewed proposals that are not fully shipped.
• implemented/ contains current shipped decisions and is the active authority.
• rejected/ preserves a declined proposal only while its rationale prevents a likely mistake.
• archived/ contains frozen implemented records. Archived files are not current authority and must not be edited.

When a proposal ships, rewrite it as a present-tense implemented decision and update its Status: line in the same change. When a decision is reversed, create a new note and link the old and new owners; do not silently rewrite history.

Documentation For People

docs/ is for human readers. Its AGENTS.md defines the documentation standard; it does not contain Agent Note decisions. Human-facing documents should have one authoritative home, describe current behavior, and be written as either:

• Tutorials, which lead a reader through an ordered task and introduce prerequisites as needed.
• References, which describe current behavior for lookup without pretending to be a tutorial.

Put decision rationale in .agents/notes/, reusable procedures in .agents/skills/, and human explanations in docs/. Link to the authoritative document instead of copying the same fact into multiple places.

Updating The Workflow

After installation, the files are owned by the target project and may be edited freely. agent-workflow upgrade compares .agents/workflow.json with the current template using per-file hashes: unchanged local files can receive template updates, locally modified files are preserved or reported as conflicts, and removed template files are retained rather than deleted automatically.

The installer never creates or edits the target project's root AGENTS.md. After installation it prints an optional snippet that the project owner can add manually to activate the workflow as standing repository guidance.

See specs/agent-workflow-installer for the accepted requirements, design, and implementation plan.