DEV Community: frcoder

[Harness Programming] Building AI Programming Workflow: Design Principles and Implementation Guidelines

frcoder — Fri, 06 Nov 2026 06:06:55 +0000

This document is for engineers designing and building AI-assisted coding workflows for individuals or teams.
The reference implementation comes from the open-source project Tack Harness and can be adapted as needed. Full source code: GitHub

1. Assessment Before Design

1.1 A Basic Assessment

Coding agents such as Claude Code, Cursor, TRAE, and Codex impose some constraints on large language models, but they still cannot replace harness engineering for software development. A coding workflow tailored to your needs can capture specialized knowledge and personal coding preferences while providing clearer, more visible guidance to the model. The harness directly determines "what the model can see, what it can do, and whether its mistakes can be detected." As model capabilities converge, harness design quality often becomes the deciding factor in system reliability.

A harness must answer five questions: what the model sees at each decision point (context), which actions it may take (tools), which actions are prohibited by default (constraints), how to judge whether the result is correct (verification), and how to recover when an error is found (correction). The system must be able to do the work and be constrained to do it as intended.

You can draw on the design principles of Tack Harness: fixed processes (use scripts for anything scripts can accomplish), extensible capabilities (adding a Markdown file registers a capability), traceable state (status.yaml is the only state-bearing file), isolated changes (worktrees isolate individual requirements), and accumulated experience (automatically codify practices as commands or rules when a task ends).

1.2 Three Boundaries

Before creating directories, clarify these three boundaries:

Primary problem: Identify the most pressing pain point. Common examples include missing project context across sessions, inconsistent development processes, and an inability to reuse past experience.
Decision authority: Specify which operations the model may perform automatically and which require human involvement. Typical human checkpoints include branch merges, releases, task-directory deletion, and writes to a shared knowledge base.
Scope of use: Decide whether the workflow serves an individual or a team. Individual workflows can iterate quickly; team workflows must support upgrades, reviews, and handoffs.

1.3 Controlling Complexity

Start with the simplest solution and add abstractions only when necessary. Every additional layer of indirection creates another blind spot for future debugging. If a few extra lines in a prompt solve the problem, do not introduce a new script. Consider turning a process into a command only after it has repeated more than three times across two tasks.

Follow a minimum viable approach: address the primary pain point first, then expand the modules after two weeks of actual use. Avoid codifying an entire development process before validating any pain points.

2. Directory Skeleton

The workflow's physical structure consists of five directories with distinct responsibilities and one persistent instruction file. The following is the directory layout used by Tack Harness:

my-project/
├── AGENTS.md            # Persistent instructions: command routing + core constraints + data sources
├── tack.yaml            # Space registry: version, projects (keyword/repository mappings), workspace list
├── harness/             # Development process definitions (requirement-independent, customizable, three-way upgrade comparison)
│   ├── README.md        #   Harness usage guide
│   ├── cmd/             #   Commands: discovery, routing, entry and exit criteria
│   ├── agents/          #   Delegatable roles: parallel execution with independent contexts (explorer/architect/reviewer)
│   ├── workflow/        #   Workflows: state machines and command orchestration
│   ├── script/          #   Fixed-process scripts (invoked through the run.ps1 launcher on Windows)
│   │   └── hook/        #   Optional IDE hook acceleration layer (disabled by default, no interception)
│   ├── rule/            #   Business, code, and security rules (excluded from routing, loaded on demand)
│   ├── template/        #   Templates for commands, workflows, documents, and workspaces
│   └── reference/       #   General methodologies and complex standalone capabilities (distributed with the harness, no project-specific knowledge)
├── wiki/                # Shared knowledge: project-isolated wikis
│   └── <project>/       #   Project wiki (indexes + small files)
├── space/               # Workspaces: one directory per piece of work (<YYYYMMDD>-<branch-name>)
├── repo/                # Main code repositories: one copy only, used as a read-only baseline
└── .tack/               # Local framework runtime data (gitignored, not committed, can be cleared at any time)
    ├── log/             #   Logs
    ├── backup/          #   Rollback backups
    ├── tmp/             #   Temporary files
    └── state/           #   Local machine state

Table 2-1 lists each directory's responsibilities and prohibited contents.

Table 2-1. Directory Responsibilities

Directory	Responsibility	Prohibited contents
`AGENTS.md`	Routing entry point, global hard constraints, and pointers to data locations	Structured registries such as project and workspace lists
`tack.yaml`	Structured registry: version, project names, keywords, repository mappings, and workspace list	Free-form prose
`harness/cmd/`	Business-independent command manuals	Business knowledge, code, and task progress
`harness/workflow/`	State-machine definitions and command orchestration	Execution details of individual commands
`harness/agents/`	Delegatable role definitions (parallel execution with independent contexts)	Participation in command routing
`harness/script/`	Deterministic mechanical operations (batch Git operations, state updates, routing scans)	Logic that requires semantic judgment
`harness/rule/`	Coding standards, security boundaries, and read/write discipline	Task-specific content
`harness/template/`	Templates for commands, workflows, and documents	Bodies of specific commands
`harness/reference/`	General methodologies and complex standalone capabilities	Project-specific accumulated knowledge (overwritten during upgrades)
`wiki/<project>/`	Stable knowledge shared across tasks	Frequently changing code logic and one-off task details
`space/`	Artifacts and state for a single task	Knowledge that must be retained across tasks
`repo/`	Read-only code baseline	Direct code modifications
`.tack/`	Framework runtime data	Any manual edits

2.1 Two-Layer Git Boundary

The space root (AGENTS.md, harness/, wiki/, and working documents under space/) and the business code repositories use separate Git repositories. The framework automatically commits changes to the space-root repository at each command stage, so users do not need to operate it. Users perform Git operations such as commits and pushes only inside the workspace code repository at space/<YYYYMMDD>-<branch-name>/repo/. This boundary keeps the workflow's evolution history separate from the business code history.

3. Persistent Instructions in AGENTS.md

This is the first document the model loads in every session, so its length must be tightly controlled. Context-window capacity is scarce: every extra line of rarely used information adds token costs to every session. The persistent layer should contain only three kinds of content: command routing, global hard constraints, and pointers to data locations. A reference structure follows:

# Persistent Project Instructions

## Command Routing
Upon receiving a user request, run `harness/script/scan-routes.sh resolve "<input>"`:
- Single match: read the corresponding command file and follow it
- Multiple matches: list the candidates and wait for the user to choose
- No match: respond directly and suggest creating a command if necessary

## Global Constraints
- Modify code only inside space/<current-workspace>/repo/; never modify repo/ directly
- Prohibit git push --force, git commit --no-verify, and git reset --hard
- Record task progress in space/<workspace>/status.yaml; do not infer it from conversational memory
- Before writing to the wiki, read its existing index; merge into an existing file on the same topic instead of creating fragments

## Data Locations
- Workspaces: space/<YYYYMMDD>-<branch-name>/
- Project knowledge: wiki/<project-name>/
- Command manuals: harness/cmd/
- Status queries: harness/script/work-status.sh

Structured data such as project names, service-to-repository mappings, and workspace lists should be stored in tack.yaml and read on demand through harness/script/project.sh. The criterion is simple: is this information needed at every decision point in every session? If yes, put it in the persistent layer; otherwise, put it in the on-demand layer.

4. A Three-Layer Memory System

4.1 Why Layers Are Necessary

Putting all information into a single instruction file creates three problems: context costs grow linearly with project size; the model struggles to locate key constraints in long text; and information with different lifecycles gets mixed together—temporary state is treated as a long-term rule, while long-term knowledge is treated as a one-off detail.

A better approach is to divide memory into three layers by lifecycle. Each layer has a different information format, read/write frequency, and loading method.

4.2 Layer One: Session Trace

User inputs, model responses, and tool-call results generated within a single session form its execution trace, which is discarded when the session ends. This layer does not require persistence; the model's context window carries it naturally. This workflow adds no further design for this layer.

4.3 Layer Two: Workspace Short-Term Memory

Each task has its own directory, space/<YYYYMMDD>-<branch-name>/, which records the task's process state. Initially, create only two files:

status.yaml: the only state-bearing file, recording the current stage, active tasks, and next steps;
context.md: original requirements (multiple entries may be appended in batches), reference links, and constraints.

Create the remaining directories (story/, doc/, run/, and repo/) on demand when the first file is produced or a worktree is checked out; do not pre-create empty directories. This layer represents "task-level business state": it tells the model "where we are and what to do next," so an interrupted task can resume in a new session without starting from scratch.

Table 4-1 lists recommended fields for status.yaml. Structured fields are preferable to free text because scripts must read and write this data atomically. Task claiming, state transitions, and progress aggregation are all handled by scripts, so the fields must be stable and parseable.

Table 4-1. Recommended status.yaml Fields

Field	Purpose
`status`	Workflow state (initialized / planning / developing / reviewing / merged / blocked, etc.)
`workflow`	Associated workflow (development / testing / bugfix / merge-conflict / branch-op)
`branch`	Git branch name
`project`	Project name, which determines the wiki read/write path
`tasks[]`	Task list: id, title, module, repository, dependencies, acceptance criteria, and status
`deploy[]`	Deployment registry: repository, environment, lane, route, version, and status
`guidance[]`	User guidance records (pending / applied / rejected; see Chapter 8)
`log[]`	Stage-transition log

4.4 Layer Three: Project Long-Term Memory

Stored under wiki/<project-name>/, this layer holds stable knowledge reusable across tasks. Use "paragraph-based documents with sources": explanations of business terms, the background and rationale of technical decisions, and service deployment addresses all need narrative context and should not be split into isolated key-value pairs.

Table 4-2 lists recommended categories. Each category directory has an index.md as its main index.

Table 4-2. Recommended Project Wiki Categories

Category directory	Contents	Corresponding memory type
`biz/`	Business background, terminology, domain responsibilities, and invariants	Semantic memory: business knowledge distilled from specific requirements
`code/`	Repository overviews, mappings from terms to code entry points, mappings from interfaces to business scenarios, and long-term analyses	Semantic memory: stable navigation anchors
`rule/`	Technical decision records, engineering conventions, and preferences	Semantic memory: why decisions were made
`config/`	Service inventory, deployment environments, lanes, gateway addresses, tenant accounts, and ways to obtain credentials	Semantic memory: operational facts outside the code
`history/`	Archived summaries of closed workspaces (summary.md + run/)	Episodic memory: compressed archives of specific events

Note the relationship between categories and memory types: process artifacts under space/ are episodic memory (what happened during this task); knowledge accumulated under wiki/ is semantic memory (what the project's business rules are); and commands and state machines under harness/ are procedural memory (how this kind of work should be done). Keep these separate. Sending episodic memory directly into the long-term knowledge base without distillation contaminates the semantic layer.

4.5 Indexes and Small Files

The long-term knowledge base uses an "index + small files" structure. Each category directory contains an index.md with a table listing files, topics, and coverage. The index is for navigation only and does not duplicate the body text. Split content into small, topic-specific files with high cohesion and low coupling.

The engineering rationale is the limited context window: retrieval should begin with the index to identify the right direction, then read only the relevant sections. One file per topic reduces token costs for each read and keeps files maintainable over time.

4.6 Write Discipline

Follow these rules when writing information to the long-term knowledge base:

Write selectively. Not everything in a conversation deserves long-term retention. Do not store one-off task details, such as "which account was used for this test"; retain only facts reusable across tasks. Before writing, ask: will another task need this information three months from now?
Distill into general principles. A specific user correction during a task ("do not write this function this way") should be distilled into a general rule ("functions of this kind in this project use pattern X") rather than piled up verbatim. A human must confirm this distillation to prevent the model from overgeneralizing.
Include sources for every entry. Each knowledge entry must identify its source: a workspace artifact (with file path and section), a user guidance record, a Git commit hash, or user-provided material. Reject content without a source.
Classify confidence. Entries have four confidence states: confirmed (confirmed by the user or an authoritative source), verified (cross-checked against code), reported (stated by a single source), and candidate (awaiting confirmation). Subsequent tasks load only the first two by default; the latter two serve only as leads.
Preserve evolution when resolving contradictions. When a new fact conflicts with an existing entry, update it in place with the current conclusion and note "previously X, corrected on Y because of Z." When a technical decision is superseded, mark the relationship instead of deleting the old entry. This preserves the evolution of knowledge so later readers can understand why decisions changed.
Never use the knowledge base to update itself. Facts used in knowledge-base updates may come only from original workspace artifacts, code, Git history, and original user-provided material. Existing knowledge-base pages must not serve as factual sources for updates to other pages. This prevents AI-generated content from being amplified through repeated internal references: an unverified statement, once stored, could otherwise be cited repeatedly until it appears to be an authoritative "consensus."

4.7 Retrieval Priority

The model retrieves knowledge in the following order and must continue to lower layers when an upper layer lacks the information:

Project wiki (cross-task consensus) → current task's analysis documents (short-lived conclusions; validate the baseline commit) → direct code inspection (the ultimate source of truth)

If an upper layer is missing or questionable, descend to gather evidence; do not stop because "the knowledge base does not mention it." When knowledge-base content conflicts with code, the code takes precedence. Analysis documents should record a "baseline commit" in their headers. During subsequent retrieval, a script compares it with the current HEAD and warns that conclusions may be outdated if the baseline is several commits behind.

5. Command Representation and Routing

5.1 Command File Structure

Store commands as Markdown files under harness/cmd/ rather than hard-coding them into framework code. A command file is essentially an SOP for the model, specifying prerequisites, input sources, execution steps, and post-execution checks. Its front matter declares routing information:

---
command: spec          # Workflow files use workflow: development
short: sp
triggers: requirements planning, overall design, spec
summary: Produce a requirements specification
---

The front matter has four fields: command is the command name, short is its abbreviation, triggers lists Chinese and English trigger phrases separated by commas, and summary is a one-sentence description. Organize the command body as "prerequisites → input sources → execution steps → post-execution checks."

A workspace may contain multiple development stories. Organize analysis artifacts by story:

space/20261001-user-login/
├── status.yaml
├── context.md
├── story/
│   └── <story>/
│       ├── analysis.md      # Requirements analysis: existing implementation, feasibility, compatibility, open questions
│       ├── spec.md          # Requirements specification (top-level design and shared contracts)
│       └── plan.md          # Development plan (detailed design and implementation blueprint)
├── doc/
│   ├── tech-design.md       # Technical review document (on demand)
│   ├── test.md              # System test plan (on demand)
│   ├── code-review.md       # Code review report (on demand)
│   ├── release-check.md     # Release checklist (on demand)
│   └── analysis/            # Code Q&A and analysis records before requirements are clarified
└── run/                     # Reusable execution instructions (on demand)

5.2 Routing Script

Implement a companion routing script whose core responsibility is to scan all .md files under harness/cmd/ and harness/workflow/, parse their front matter, match trigger phrases against user input, and return matching file paths. Tack Harness defines these scan-routes.sh subcommands:

sh harness/script/scan-routes.sh list       harness   # Workflow table + command table + delegatable role table
sh harness/script/scan-routes.sh workflows  harness   # Workflows only (intent recognition)
sh harness/script/scan-routes.sh commands   harness   # Commands only
sh harness/script/scan-routes.sh agents     harness   # Delegatable roles only (excluded from routing)
sh harness/script/scan-routes.sh resolve    harness "requirements planning"

Behavior:

Single match: output the command file path; the model loads and executes it.
Multiple matches: output a candidate list; the model asks the user to choose.
No match: the model responds directly and suggests creating a command if necessary.

Perform scanning, parsing, and matching within a single script process to avoid forking multiple subprocesses per file on Windows. For English keywords, use word-boundary matching (the match must occur at the beginning of a word or after - / _); for Chinese keywords, use substring matching.

5.3 Tool Interface Design Principles

Commands and scripts are both tools the model can invoke. Tool interface quality directly affects the reliability of model behavior. Two principles deserve emphasis:

Design names and parameters from the model's perspective. Command names should correspond to the way users describe their intent in natural language, and trigger phrases should cover common Chinese and English expressions. A command name that requires reverse engineering to understand is effectively invisible. All Tack Harness commands support Chinese and English trigger phrases and abbreviations, such as the Chinese equivalent of requirements planning, spec, and sp.

Make incorrect usage difficult. High-risk operations, such as deleting task directories, force-pushing, and overwriting the knowledge base, should be disabled by default at the tool level or require an explicit confirmation parameter. Do not rely on prompts telling the model "do not do this." Errors that are structurally impossible are prevented more reliably than errors prohibited only by prompt instructions.

6. State Machines and Task Scheduling

6.1 State-Machine Definitions

A major reason models fail on open-ended tasks is that they lack a clear understanding of the current stage. Define a state machine for each typical development scenario and store it under harness/workflow/. Tack Harness defines five workflows:

Workflow	Trigger phrases	State transitions
development	requirement development / feature development / dev	`initialized → planning → developing → reviewing → merged`; close deregisters the workspace
testing	add tests / testing task / tst	`initialized → test-planning → testing → verifying → completed`
bugfix	fix bug / fix defect / troubleshoot / bug	`initialized → reproducing → diagnosing → fixing → verifying → completed`
merge-conflict	merge conflict / conflict workflow / mc	`initialized → fetching → merging → resolving → verifying → pushing → completed`
branch-op	branch operation / bop	`initialized → preparing → integrating (resolving on conflict) → pushing → completed`

Any blocked stage may enter the blocked state, with the blocking reason recorded in status.yaml. Once unblocked, it returns to the previous state. The main development path is:

flowchart LR
    A["init"] --> B["work requirements"]
    B --> B2["analyze requirements analysis"]
    B2 --> C["spec"]
    C --> D["plan"]
    D --> E["tech-design"]
    E --> F["code"]
    F --> H["fetch"]
    H --> I["commit"]
    I --> J["push"]
    J --> K["merge"]
    K --> L["close"]
    B -. optional before requirements are clarified .-> A1["ask"]
    F -. triggered when requested by the user .-> G["testcode"]
    F -. triggered when requested by the user .-> G2["test"]
    F -. triggered when requested by the user .-> G3["run"]
    C & D & E & F -. deviation detected .-> M["fix"]
    M -. requirements correction loop .-> C
    K -. conflict .-> N["solve"]
    N -.-> K

6.2 Fix the Main Path, Delegate Within Boundaries

The state machine is not intended to prescribe every step the model takes. It safeguards the boundaries of "which stages must be completed." The main path—requirements analysis → solution design → coding → review → merge—is constrained by the state machine, and stages cannot be skipped. Within each state, decisions such as "how to write this code" or "which solution to choose" are entirely up to the model.

This balances workflows with autonomous agents: use state machines to constrain stages that can be decomposed into fixed steps, while preserving model autonomy in stages that require dynamic decisions.

6.3 Task Scheduling

The task list produced during plan is written to tasks[] in status.yaml. Each entry includes id, title, module, repo, deps, acceptance, and status. Scripts must claim and complete tasks atomically to prevent duplicate claims by parallel model instances:

Verify that dependencies are satisfied before setting a task to in progress.
After completing the current task, return the next ready task.
Support transitions among pending / in_progress / done / blocked.

6.4 On-Demand Commands

Commands for testing, code review, and release checks should not be attached to the main path. They do not occupy workflow state slots or block the main process, and the model does not proactively ask whether to execute them. They are triggered only by explicit user requests. Tack Harness includes these on-demand commands: testcode (unit-test-driven review of consistency between requirements and code), test (system test plan), run (reusable script execution), code-review (an independent pre-merge review report), and release-check (release checklist). This avoids forcing heavyweight processes onto simple tasks: a two-line change should not require the full testing and review process.

6.5 Automatic Progression

Provide an auto command that executes all remaining stages of the current workflow until its terminal state. Before starting, collect all missing information and confirm the entire process once. After confirmation, proceed continuously without interruptions, then summarize key decisions and results. By default, stop at merged / completed; optionally include close.

7. Dividing Responsibilities Between Scripts and the Model

The principle is: script all operations that can be performed deterministically; leave stages requiring semantic judgment to the model. Table 7-1 shows typical assignments.

Table 7-1. Responsibility Boundaries Between Scripts and the Model

Operation type	Executor	Rationale
Batch updates to state fields across files	Script	Mechanical, frequent, and precision-sensitive (`work-status.sh`)
Batch Git add / commit / push / worktree management	Script	Frequent, error-prone, and requires atomicity
Command-routing scans	Script	Required in every session and should not consume tokens (`scan-routes.sh`)
Knowledge-base index integrity checks	Script	Machine-verifiable and must serve as a gate
Credential-pattern scanning	Script	High-confidence rules with manageable false positives (`scan-secrets.sh`)
Workspace creation and batch directory registration	Script	Mechanical operations that ensure consistency
Three-way upgrade comparison and baseline management	Script	Requires precise comparison between shipped originals and local changes
Requirements decomposition and story partitioning	Model	Requires semantic judgment
Technical solution selection	Model	Requires context-aware tradeoffs
Defect localization and hypothesis generation	Model	Requires exploration and reasoning
Code review conclusions	Model	Requires function-by-function semantic judgment

The underlying reasoning is that the model should freely combine general exploration capabilities, such as reading and writing files, running commands, and searching code. High-risk or strongly constrained operations, such as adding credentials to a repository, deleting branches, and force-pushing, should be encapsulated in dedicated scripts and disabled by default or require human confirmation. A useful criterion: if a prompt instruction describes a fixed sequence of actions, implement it as a script instead of relying on the model to follow it voluntarily every time.

Scripts must be portable across Linux, macOS, and Windows Git Bash, and should uniformly use POSIX sh. In Tack Harness, lint-shell-portability.sh runs as part of structural checks to detect bare mktemp, GNU-specific options, bashisms, and sed dialect issues.

8. The Experience-Capture Feedback Loop

A workflow without an experience-capture mechanism will degrade into unconstrained conversation within weeks. Establish a three-step loop: "capture → codify → validate."

8.1 Capture

During task execution, whenever the user corrects model behavior or adds a convention, append the original facts to the guidance list in status.yaml. Each record includes the time, stage, scenario description, the user's verbatim statement, and a status of pending (awaiting codification). At this stage, record facts only; do not generalize them or modify any rule files.

8.2 Codify

When the task ends, during the close command, present the pending entries to the user for review. Review criteria: is this reusable across tasks? Is it a long-term rule or a one-off exception? After user confirmation, scan existing command and rule files. Merge into a related entry if one exists; create a new file only when no suitable entry exists. Mark user-rejected entries as rejected; leave undecided entries as pending.

The key is "delayed judgment": record corrections when they occur, rather than immediately changing rules in the heat of the moment. Once the task ends and some distance is available, decide whether each correction belongs in a long-term rule or applies only to this task.

8.3 Validate

After saving the changes, a script verifies that the target file actually exists before marking the corresponding guidance entry as applied. If the path does not exist, block the write and report an error. This prevents accumulated guidance from pointing to nonexistent files.

8.4 Three Additional Paths

In addition to the automatic loop, provide three manual commands:

record (manual knowledge capture): when the user asks to record knowledge, first scan existing commands and try to merge or amend them. Content may be stored in commands, workflows, rules, the wiki, or persistent constraints in AGENTS.md. When creating a command, only command is required; abbreviations and Chinese and English trigger phrases are generated automatically.
evolution (internal review): reconcile the space registry with actual directories, check wiki index integrity, lint framework structure and script signatures, review all instructions, identify candidates for rule/reference/script, and clean up outdated facts.
study (external learning): read the design of an external skill or repository, extract useful practices, and save them to the appropriate harness locations. Present a consolidated preview for confirmation before committing, then automatically run an incremental evolution.

9. Binding Reviews to Evidence

Code reviews and release checks need an evidence-fingerprint mechanism to address the problem of "inputs change after a review, but its conclusions are still reused."

Before a review begins, compute a hash fingerprint of all review inputs, including requirements documents, rule files, repository HEAD, target branch reference, staged diff, unstaged diff, and the contents of untracked files. After completing the review, the reviewer must confirm the conclusion using the token returned by the script. The script recomputes the fingerprint and checks that the token matches before recording the review as complete. Any input change during the review causes a fingerprint mismatch and automatically invalidates the token.

The same mechanism can confirm stages: after the user confirms requirements analysis, solution design, or another stage, store a receipt bound to the document hash. When resuming an interrupted task, reread only stage documents whose fingerprints have changed or which remain unconfirmed, avoiding a full reread.

This mechanism turns the vague statement "I have read and approved it" into a machine-verifiable snapshot of facts.

10. Isolation and Safety Constraints

The following mechanisms provide necessary safety boundaries at relatively low cost. They share one design principle: prevent errors structurally wherever possible, instead of relying on prompt reminders.

Code-change isolation: treat the main repo/ as a read-only baseline and make task code changes in independent worktrees under space/<workspace>/repo/. Multiple tasks can develop different requirements in parallel without interfering with one another. Accidental operations on the main repository are physically impossible.
Dangerous-operation prohibition: explicitly prohibit operations such as push --force, commit --no-verify, reset --hard, and direct modifications to the main repository in harness/rule/.
Space-level mutual exclusion: serialize state writes and automatic commits to the space-root repository using a space lock. If the lock-holding process is killed or interrupted, reclaim the leftover lock automatically by checking whether its PID is alive; a living lock holder continues to block other processes normally.
Credential-scanning gate: run scan-secrets.sh before committing documents to match high-confidence credential patterns, such as private-key headers, cloud-provider access keys, and token prefixes. A match blocks the automatic commit. Placeholder values (your-, example, and <...> templates) and explicit exemption markers do not trigger alerts.
Directory-deletion validation: before deleting a workspace directory, perform three checks: the path must be a single-level directory name (reject separators and ..); its physical path must be confirmed to lie inside space/ (prevent symlink escapes); and no worktrees may remain under repo/.
Branch-cleanup gate: close processes only branches registered in status.yaml and defaults to dry-run. Branches not merged into the main branch, protected branches, branches occupied by worktrees, and entries with an unknown mainline are listed but not deleted. Remote branches are not deleted automatically.
Human approval checkpoints: branch merges, releases, and workspace deletion require explicit user confirmation. Commits are triggered by the user invoking the commit command; invoking it confirms intent, and the commit is made directly after its message is generated automatically.

11. Organizing Reusable Scripts

Organize repeated operations such as testing and data migration into dedicated instruction directories instead of writing temporary scripts each time. A recommended structure follows:

space/20261001-user-login/run/
├── run.md              # Guide: purpose, dependencies, manual-step instructions (identification, indexing, and orchestration only)
├── <instruction-1>/
│   ├── setup.sh        # Implementation scripts
│   ├── load-data.sh
│   └── local/          # Credentials and environment data (gitignored, excluded from version control)
└── <instruction-2>/
    └── ...

run.md handles identification, indexing, and orchestration only. Each instruction has its own directory for scripts, data, and credentials (local/ is excluded from version control). During execution, verify checklist completeness, execute in order, stop on failure, and support explicit resumption and confirmation of manual steps. When the task closes, archive the entire run/ directory under wiki/<project>/history/<workspace>/ so its scripts can be reused directly in later work.

12. Implementation Roadmap

Implement the workflow in stages:

Week one: create only AGENTS.md and the three most frequently used commands (start a task, write code, and commit/wrap up). Maintain the YAML state file manually. Run the full process on one real requirement.

Weeks two through four: add capabilities gradually based on pain points revealed by actual use. For example, write a state-update script if manual status changes are frequent; add indexing rules and an integrity-check script if the knowledge base becomes disorganized; promote a constraint to AGENTS.md if the model repeatedly violates it.

Month two: enable the experience-capture loop. By then, enough user correction records should have accumulated to provide material for codifying rules. Also introduce evidence fingerprints and isolated worktrees to address the reliability of parallel tasks and code reviews.

Do not pursue process completeness before gaining practical experience. Let the workflow grow from real pain points rather than designing it all in advance. Model capabilities continue to evolve: a stage that needs a script safeguard today may become a native model capability tomorrow. Keep the workflow lean and reserve its complexity budget for work the model still cannot handle reliably.

Appendix: Minimum Viable Version

The following structure can be set up in half an hour:

my-project/
├── AGENTS.md                  # Persistent instruction file of about 30 lines
├── tack.yaml                  # Empty project registry
├── harness/
│   ├── cmd/
│   │   ├── work.md            # Create a workspace: create directories, write status.yaml and context.md
│   │   ├── code.md            # Coding: execute the plan
│   │   └── close.md           # Commit and wrap up: archive, capture knowledge, and clean up
│   ├── workflow/
│   │   └── development.md     # State machine for the main path
│   ├── script/
│   │   └── scan-routes.sh     # Command routing (about 100 lines)
│   └── rule/
│       └── security.md        # Three prohibitions
├── wiki/
│   └── <project>/
│       └── index.md
└── space/                     # Workspace directories are created on demand

If you prefer not to start from scratch, adapt TackHarness directly. Full source code: GitHub. After two weeks of use on real tasks, iterate and expand based on the specific problems encountered, until the workflow matches the actual development habits of your individual or team.

Installing TackHarness

Choose either method below.

Let the agent install it (recommended). Enter the following in a coding agent such as Claude Code, Cursor, TRAE, or Codex:

Install this skill: https://github.com/frcoder-lh/tack-harness

Use the one-command installation script. Enter the following in a shell terminal:

curl -fsSL https://raw.githubusercontent.com/frcoder-lh/tack-harness/master/install.sh | sh -s

Using TackHarness

# Initialize a TackHarness space
/tack

# View help
/tack help

For the detailed workflow, see: https://github.com/frcoder-lh/tack-harness#4-usage-workflow

Tack Harness

frcoder — Thu, 15 Oct 2026 12:55:52 +0000

Tack Harness: A Minimalist, Agent-Driven Framework for Disciplined Software Engineering

As software engineers, we often find ourselves drowning in tooling complexity. Modern development frameworks promise to make us faster, yet we spend half our time configuring pipelines, wrangling bloated abstractions, and trying to keep our AI assistants from hallucinating across massive, unstructured codebases.

What if we returned to something lean, restrained, and profoundly disciplined?

Enter Tack Harness—a minimalist programming workflow framework designed to bring absolute clarity, determinism, and robust agent collaboration to software development. Whether you are coding solo or orchestrating specialized AI agents, Tack Harness provides the rails you need to build reliable software without the bloat.

In this post, we will explore why Tack Harness was built, its core architectural principles, how its finite state machine keeps development on track, and how its agent delegation model changes the way we collaborate with AI.

The Philosophy: Lean and Restrained

Tack Harness isn’t trying to do everything for you. Instead, it acts as a lightweight harness that enforces a strict, predictable development rhythm. By keeping the workflow constrained and intentional, it eliminates decision fatigue and ensures that every change is traceable, isolated, and correct.

The framework rests upon 5 Core Principles, affectionately known as the FETID pillars (though much more pleasant to work with than the acronym suggests):

Fixable: Every component and workflow state must be transparent and straightforward to debug. If something breaks, the path to remediation should be immediately obvious.

Extensible: Built with a modular mindset, Tack Harness lets you plug in custom tools, skills, and agents without rewriting core logic.

Traceable: Nothing happens in a black box. Actions, state transitions, and agent decisions leave a clean, auditable trail.

Isolated: Tasks, branches, and execution environments are kept separate to prevent unintended side effects from bleeding across your project.

Distilled: Stripped of unnecessary boilerplate. Every abstraction serves an immediate, practical purpose.

The 5 Core Workflow States

Traditional development often feels chaotic because we jump haphazardly between writing code, fixing tests, resolving conflicts, and managing branches. Tack Harness models the development lifecycle as a deterministic Finite State Machine (FSM) consisting of 5 distinct states:

Development (development): The sandbox where active feature building happens under strict guidelines.

Testing (testing): Rigorous validation to ensure changes meet quality bars before progression.

Bugfix (bugfix): A dedicated, focused state for diagnosing and patching regressions without distraction.

Merge-Conflict (merge-conflict): A systematic protocol for handling divergent changes safely and cleanly.

Branch-Op (branch-op): Standardized handling of branch lifecycles, synchronization, and cleanup.

By enforcing these states, Tack Harness prevents premature merging, sloppy testing, and orphaned branches.

Empowering AI with Skill and AGENTS.md

One of the standout features of Tack Harness is its native support for agent-driven workflows. Instead of treating AI as a generic chat window, Tack Harness treats AI agents as specialized team members governed by explicit context.

The AGENTS.md Contract

Every project using Tack Harness can define an AGENTS.md file. This acts as the constitutional document for AI agents operating within your repository. It outlines project rules, coding standards, architectural boundaries, and behavioral expectations, ensuring that any AI tool working on your codebase respects your conventions from the first line to the last.

Modular Skill System

Skills encapsulate discrete capabilities that agents can load and execute. Whether it is parsing a complex AST, running a specific validation suite, or formatting documentation, skills keep agent logic modular and reusable.

Role Delegation: Meet Your AI Squad

Instead of relying on a single, monolithic prompt to do everything, Tack Harness introduces a clean Role Delegation Model. Different phases of development require different mindsets:

code-explorer: The scout. This agent navigates the codebase, maps dependencies, traces call stacks, and gathers context without altering code. Perfect for onboarding or understanding legacy modules.

code-architect: The planner. Once the landscape is clear, the architect designs the solution, defines interfaces, and outlines step-by-step implementation plans aligned with the project's core principles.

code-reviewer: The gatekeeper. Before any code is finalized, the reviewer inspects the diff against project standards, checks for edge cases, security flaws, and style violations, ensuring high code hygiene.

By separating exploration, architecture, and review, you get significantly higher-quality outputs from your AI tools and a much smoother review process for human maintainers.

Getting Started

Ready to bring discipline and seamless agent collaboration to your workflow?

You can check out the official repository and documentation to explore the reference implementation, configuration templates, and setup guides:

👉 Tack Harness on GitHub

Give it a spin on your next project, embrace the restrained workflow, and let your AI agents work smarter, not harder. Happy coding!