AI SDLC Harness

agent-project-sdlc ships the sdlc-harness CLI: a minimal project-memory harness for AI coding agents.

The default is Minimal Context Harness. It maintains a compact project_context/** fact source, a short AGENTS.md startup router, role Skills and a validate-context gate so fresh agents can recover project intent, constraints, verification entry points and next safe actions quickly.

It does not default to lifecycle phases, plan tasks, stage skills, stage documents or phase gates. Harness maintains context quality; your project tests, CI, review process and human acceptance remain responsible for product quality.

Use it when coding agents repeatedly lose project intent across new chats, handoffs, RFC/debug turns or tool changes. The intended tradeoff is: keep durable intent and recovery paths; leave execution evidence to code, tests and review.

Why It Exists

Coding agents can move quickly inside one thread and still drift when a new chat, model, tool, reviewer or debugging session loses the project-specific facts that were never encoded anywhere stable.

Minimal Context Harness creates a small, explicit recovery path: project goal, boundaries, architecture context, validation entry points and durable task conclusions. It is designed to sit beside specs, tests, issues, docs and code intelligence tools instead of replacing them.

Positioning

| Adjacent tool type | Use it for | Harness stance | |---|---|---| | Spec-first kits | Turning feature ideas into structured specs and plans. | Complementary; Harness keeps durable project facts, not a required spec chain. | | BMAD-style workflows and full SDLC processes | Coordinated role/process ceremonies on high-risk work. | Lighter default; no phase gates or work-product trees. | | Task Master-style planners | Backlog decomposition and task execution state. | Complementary; Harness does not own task state. | | Context7/Serena-style retrieval or code-intelligence tools | Pulling external docs, symbols or repository facts on demand. | Complementary; Harness stores local repo truth. | | IDE or agent memory | Tool-specific continuity inside one product surface. | Portable fallback; plain files any agent can read. |

Try It In 60 Seconds

mkdir ai-sdlc-harness-demo
cd ai-sdlc-harness-demo
git init
npm init -y
npm install -D agent-project-sdlc@latest
npx --yes --package agent-project-sdlc@latest sdlc-harness init
make validate-context

Then open AGENTS.md, project_context/global.md and project_context/architecture.md. Those files are the small recovery surface a fresh agent should read before changing the project.

Expected result:

AGENTS.md
project_context/
  context.toml
  global.md
  architecture.md
  areas/main.md
  areas/main/verification.md

Fresh-agent test prompt:

Read AGENTS.md and project_context/** first. Summarize the project goal, non-goals, architecture boundaries, validation entry points and next safe action before proposing code changes.

If the agent can answer that without rediscovering the repo from scratch, the Harness is doing its job.

Install

npm install -D agent-project-sdlc@latest
npx --yes --package agent-project-sdlc@latest sdlc-harness init

For existing projects:

npx --yes --package agent-project-sdlc@latest sdlc-harness init --adopt

init creates project_context/context.toml, project_context/global.md, project_context/architecture.md, project_context/areas/main.md, project_context/areas/main/verification.md, agent guidance, Context authoring Skills, a full-project export Skill, managed templates/tools, a Makefile include and .github/workflows/harness.yml. The generated workflow runs only the selected Harness gate, validate-context or validate-harness; maintainer-only package tests and source-drift checks are intentionally kept out of consumer projects. It does not create stage work-product trees, lifecycle state or stage skills by default.

FAQ

Why not just write a better README?

README is for humans and broad orientation. Minimal Context is a smaller machine-readable recovery path for fresh agents: durable intent, non-goals, boundaries, validation commands and context drift notes.

Is this only for Codex?

No. The generated files are plain repository assets. Codex, Claude Code, Cursor, Gemini CLI, Cline, Roo or a human reviewer can read the same facts.

Does validate-context prove the project works?

No. It checks that recovery facts exist and avoids fake test-result claims. Product quality still belongs to tests, CI, review and human acceptance.

Will this create documentation burden?

It should stay smaller than a full process. Ordinary bug fixes and local refactors do not update Context unless they produce durable product, architecture, API, state or validation facts.

CLI Entry Safety

The canonical npm package is agent-project-sdlc; sdlc-harness is the bin name. Prefer package-qualified npx commands for ad hoc use because bare npx sdlc-harness can resolve an older package name or a stale local install. After init, the managed Makefile wrapper uses the canonical latest CLI by default and can be overridden with SDLC_HARNESS=... when a project intentionally pins a local package.

Use npx --no-install sdlc-harness ... only when you explicitly want the already installed local package, such as release smoke tests against a packed tarball.

Capabilities

| Capability | Entry Point | Description | |---|---|---| | Project initialization | npx --yes --package agent-project-sdlc@latest sdlc-harness init | Creates project_context/context.toml, project_context/global.md, project_context/architecture.md, project_context/areas/main.md, project_context/areas/main/verification.md, AGENTS.md, minimal managed assets and a Makefile include. | | Existing project adoption | npx --yes --package agent-project-sdlc@latest sdlc-harness init --adopt | Adds Minimal Context Harness non-destructively to an existing repository. | | Configurable Harness root | --harness-folder, package.json#sdlcHarness.harnessFolderName, sdlc-harness.config.json | Supports Codex .codex, Claude .claude, Cursor .cursor, Cline .cline, Roo .roo, Gemini .gemini or a custom folder. | | Product planning Skill | <harnessRoot>/skills/context_product_plan/SKILL.md | Triggers on “产品方案 / 产品经理 / 产品专家” style requests and writes durable product conclusions to project_context/**. | | UI/UX design Skill | <harnessRoot>/skills/context_uiux_design/SKILL.md | Triggers on “设计稿 / UI/UX 设计方案 / 视觉专家” style requests, writes screen/interaction conclusions to project_context/**, updates root DESIGN.md visual tokens with Google @google/design.md, and includes compact visual-quality calibration for product/page positioning, user needs, information density, brand/product UI and common AI-design anti-patterns. | | Development engineer Skill | <harnessRoot>/skills/context_development_engineer/SKILL.md | Triggers on “开发工程师 / 技术方案 / 开发方案 / 实现 / 实现方案 / 实施计划 / 技术专家 / 多开agent / subagent” style requests and writes durable engineering conclusions to project_context/**. | | Full project context export Skill | <harnessRoot>/skills/context_full_project_export/SKILL.md | Triggers on “导出尽可能详细的项目全量上下文 / 全量上下文导出 / full project context export / 当前项目代码实现 / 代码级实现导出” style requests and uses export-context --all, --full or --code to create temporary artifacts under tmp/sdlc/context-exports/**. | | Project-local Skills | <harnessRoot>/skills/<role>/SKILL.md | Optional local product/design/development Skills created by the project, such as product_plan, uiux_design or development_engineer. They supersede package-managed default Skills when more specific, are not overwritten by sync, and should keep front matter trigger keywords aligned with the project AGENTS.md role-trigger rule. | | Managed file sync | make sdlc-sync or npx --yes --package agent-project-sdlc@latest sdlc-harness sync | Refreshes package-managed guidance, default Skills, Makefile include, context templates, tools and workflow YAML. It does not perform semantic Context generation. | | Upgrade | make sdlc-upgrade or npx --yes --package agent-project-sdlc@latest sdlc-harness upgrade | Runs safe migrations and sync, including Schema v4 Context graph manifest creation when missing. | | Combined project export | npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --all [--check] | Creates both default temporary exports with one timestamp: 当前项目context-<timestamp>.md and 当前项目代码实现.md. | | Project Context export | npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --full [--output tmp/sdlc/context-exports/name.md] [--check] | Creates a temporary Context summary artifact named 当前项目context-<timestamp>.md by default. It is not Context and must not be registered in project_context/context.toml. | | Code implementation export | npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --code [--output tmp/sdlc/context-exports/name.md] [--check] | Creates a temporary single-file code implementation artifact named 当前项目代码实现.md by default. It is not Context and must not be registered in project_context/context.toml. | | Context validation | npx --yes --package agent-project-sdlc@latest sdlc-harness validate-context, make validate-context | Checks required project recovery fields, Context graph metadata, declared paths/roles and fake test-execution claims. | | Diagnostics | make sdlc-doctor or npx --yes --package agent-project-sdlc@latest sdlc-harness doctor | Reports Harness root, package version, schema version and required Minimal Context paths. | | Package source checks | sdlc-harness package sync-source, sdlc-harness package check-source | Maintainer-only commands for keeping package canonical assets aligned with the source workspace. |

For product, UI/UX and engineering tasks that touch design intent, API/Schema, state/runtime behavior, architecture boundaries or verification design, the default Skills compile a short current-task contract before implementation. The contract starts with Context Delta: none|required; required preserves context-first behavior, while none means the task can proceed against existing Context. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, validator or gate surfaces.

For complex task-contract work, agents may use plan.md or an equivalent temporary plan surface as scratch space for Context Delta, Task Contract, implementation steps and Conformance notes. It is execution cache only: durable facts must be extracted into project_context/** or DESIGN.md, and temporary plans are not Context, not registered in context.toml and not default project assets.

For Web pages, frontend layout, UI/UX, product module boundaries or decisions about where information belongs, agents should run a lightweight page product-positioning check before deciding whether the change is context-first. The check asks what judgment the user needs to make on the page, what information/actions/feedback the product must provide, what should not be persistent, what belongs in downstream consumption, ops, detail or another page, and whether layout and information density match the page task. If ownership is unclear, inspect the relevant pages and Context first. The check is input to change classification: it does not by itself require a Context update, new document chain or validator gate.

The expected Context Priority Ladder is: read Context first, run the page product-positioning check when applicable, classify durable-fact impact or use Context Delta inside task-contract scenarios, choose context-first or code-first, then perform Contract Conformance when applicable and Context drift check before handoff. This is prompt-level guidance, not an edit-order validator.

Managed AGENTS.md guidance is intentionally a startup router, not a full manual. It should contain fact-source entry points, hard boundaries, key triggers and shortest validation commands; package consumers default long design reasoning to Context unless they already have a local spec/design convention. The source repository keeps stable Harness workflow rationale in PROJECT_SPEC.md. Role procedures belong in Skills and human usage guidance in README. The recommended 40-70 line range is a soft budget, not a validator gate.

Minimal Context Contract

project_context/global.md should contain:

• project goal
• non-goals / boundaries
• background
• design rationale
• architecture context link
• product / delivery brief
• UX / screen brief
• short verification context pointers
• current state
• next safe action
• context index

project_context/architecture.md should contain restrained architecture facts:

• system boundary
• component map
• data / control flow
• design rationale
• constraints and tradeoffs
• verification implications
• open risks

project_context/context.toml is the Schema v4 Context graph manifest. init creates a default main product/domain area for ordinary projects and registers project_context/areas/main/verification.md as its default verification role Context. upgrade creates a conservative baseline manifest for existing projects by registering current project_context/areas/**/*.md files as areas, except obvious verification.md and deployment.md role files. Larger projects can add [[areas]] and [[context]] entries with role, trigger/read policy, default children and monorepo boundary metadata such as forbidden_runtime_dependencies.

project_context/areas/<unit>.md should contain product/domain ownership context by default. Complex projects can freely nest context nodes under areas/, such as areas/<area>/README.md, areas/<area>/contracts/*.md, areas/<area>/foundation/*.md, areas/<area>/verification.md, areas/<area>/deployment.md or other durable context files:

• responsibility
• user / system contract
• core data / API / state
• key constraints
• code entry points
• related role context pointers
• open risks

Other context files under project_context/** can declare context_role in front matter or receive a role from context.toml. Roles are semantic labels for agent reading and authoring behavior; validate-context checks graph structure, paths and field shapes instead of enforcing a writing template for every role. Supported roles are global, architecture, area, domain, subdomain, contract, foundation, verification, deployment, archive, implementation-index and decision-rationale.

When authoring, migrating or cleaning up project_context/areas/**, run a soft role placement scan before registering every Markdown file as an [[areas]] entry. Keep area / domain for product ownership, use subdomain only for a smaller owned product context, move interface semantics into contract, stable theory or vocabulary into foundation, repeatable test/deploy execution paths into verification / deployment, code maps into implementation-index, design reasons into decision-rationale, and non-default historical or external material into archive. This is prompt-level guidance, not a validator gate.

Automatic migration moves legacy project_context/modules/**/*.md files into project_context/areas/**/*.md, creates a usable graph baseline and does not infer deep semantic roles. If an existing deep area file is really a foundation, contract, archive or implementation index, a later agent should update context.toml explicitly. Boundary rules are metadata only; Harness does not scan source imports or build a runtime dependency graph.

Temporary Project Exports

export-context --all creates both temporary Markdown artifacts for copying into an external tool, archiving an ad hoc discussion or handing context to a one-off collaborator:

npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --all
npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --all --check

This generates both default artifacts with the same timestamp: tmp/sdlc/context-exports/当前项目context-<timestamp>.md and tmp/sdlc/context-exports/code-level-implementation-<timestamp>/当前项目代码实现.md. --all does not accept --output; use --full or --code for custom single-artifact paths.

export-context --full creates only the temporary Markdown Context bundle:

npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --full
npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --full --output tmp/sdlc/context-exports/my-export.md
npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --full --check

The default output is tmp/sdlc/context-exports/当前项目context-<timestamp>.md. The file title is # 当前项目context. --check reports the planned output path, source count, source file list and warnings without writing a file. The artifact header always says Export artifact. Do not reference from project_context/context.toml.

The exporter includes Context files, key README / AGENTS / DESIGN documents, managed Skill guidance, Makefile verification-entry summaries, a directory tree summary and Context code-entry indexes. It excludes .env*, secret/token/cookie-oriented files, raw captures, licensed payload dumps, node_modules, build output, caches, coverage, test reports and existing export artifacts; obvious sensitive assignment values are redacted and reported as warnings.

export-context --code creates one temporary Markdown file for handing the current implementation state to an external model:

npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --code
npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --code --output tmp/sdlc/context-exports/my-code-export.md
npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --code --check

The default output is tmp/sdlc/context-exports/code-level-implementation-<timestamp>/当前项目代码实现.md. The file title is # 当前项目代码实现. It scans main source and engineering configuration files, adds each file path, type, line count, character count, SHA256, a heuristic one-sentence summary and a fenced redacted code block. It does not split output into multiple Markdown files.

Both export modes refuse project_context/** and non-temporary output paths. validate-context also rejects obvious export artifact names such as 当前项目代码实现, 当前项目context, code-level-implementation, full-project-context, project-overview, context-bundle, context-summary or context-export if they are registered in project_context/context.toml.

The Context should be dense, durable and short. Former ADR content belongs in Design Rationale when it still affects future changes. Implementation details that are obvious from code should stay in code and tests; only non-obvious constraints belong in Context.

Verification and deployment role Context are allowed only when a test, smoke, CI, deployment, bootstrap or runtime path has durable recovery value. Record minimal preparation, the shortest command/path, expected stage or signal, acceptable warnings and dead ends already ruled out. Do not record one-off logs, full output, temporary JSON, CI artifacts, release ledgers, reports, secrets, tokens, cookies, device ids or raw payloads. Put execution details in the owning area's verification or deployment role Context; use project-level references only for truly cross-domain paths.

project_context/** is authoritative for intended responsibility, ownership, product intent, architecture boundaries, integration direction, allowed or forbidden dependencies and verification/deployment entry paths. Source code is authoritative for current implementation state. If code shape, keyword search results or nearby implementations disagree with Context, agents should call out implementation drift, missing work or stale Context instead of overriding Context-declared ownership or intent.

Before the first code edit, agents should classify the change instead of relying on a fixed timer. Long-term fact changes include product ownership or plans, module responsibilities, information architecture, API / Schema, state-machine or scheduler semantics, cross-area boundaries and verification/deployment entry paths. If a task hits one of these categories, Context-first is the default path and the first update should be the relevant project_context/** entry with enough durable context to guide implementation, without a fixed line-count limit:

context -> implementation -> verification -> context drift check

Code-first is a controlled exception for ordinary bug fixes, local styling changes, local implementation-drift repairs, test fixes and exploratory spikes; those should not update Context unless they produce a durable fact. Once code discovery produces one, the agent should update Context before final alignment or handoff:

implementation discovery -> context update if long-term fact changed -> implementation alignment -> verification

This ordering is guidance, not a new validator gate. validate-context checks recoverability and fake verification claims; it does not infer whether Context or code was edited first. Automation may warn about possible context-first drift, but should not block work. Handoffs should report only a lightweight status such as Context: updated ... or Context: no durable fact change.

The product planning, UI/UX and development engineer Skills are Context authoring helpers. They may shape product plans, screen flows, design handoff, implementation plans or technical decisions, but they do not create a default PRD/UIUX/tech-plan document chain. Their descriptions intentionally avoid broad generic triggers such as “产品”, “设计” or “开发” alone. For visual systems, init creates root DESIGN.md as the durable source for colors, typography, spacing, shapes and component tokens; upgrade creates it for existing Harness projects when missing. The generated file starts as a neutral starter baseline with visual tokens, background/color logic, typography, spacing, component states and do/don't guidance; user-authored design rules take precedence once present. Validate it with npx @google/design.md lint DESIGN.md. The product/design Skills keep compact calibration for product/page positioning, user needs, information density, content/action placement, true empty/error/loading states, layout stability, register choice, design-system continuity and common AI-design anti-patterns.

Harness installs Impeccable as a default package dependency. For design drafts, redesigns, visual polish, frontend redesign/styling or existing-UI review work, agents should run Impeccable by default when there is a scan target such as UI source, page files, build output or a local/remote URL:

npx impeccable detect src/

Impeccable is a default design-review step when a scan target exists, but it is not a validate-context gate. If there is no suitable target or the command cannot run, the agent should say why and continue. Its findings are design-review signals, not a replacement for screenshots, project tests or human review.

Project-specific Skill rules can be added as separate project-local Skills. Do not edit package-managed context_* Skills directly; sync overwrites them:

mkdir -p <harnessRoot>/skills/uiux_design
$EDITOR <harnessRoot>/skills/uiux_design/SKILL.md

When a project-local Skill and a package-managed default Skill both apply, agents should use the more specific project-local Skill first. The local Skill should keep durable conclusions in project_context/** and DESIGN.md. Its front matter description should stay aligned with the matching default context_* Skill and the project AGENTS.md role-trigger rule; update both the local Skill and agent guidance when adding or narrowing product/design/development trigger terms. sync does not merge Skill overrides and does not overwrite separate project-local Skills. Existing <harnessRoot>/pjsdlc_managed/override_skills/*.md files should be migrated into standalone project-local Skills before running sync.

Sync And Upgrade Boundary

sync is intentionally narrow. It refreshes managed files and never generates project semantics.

upgrade performs safe package migrations and sync. The former migration command has been removed because existing users have completed migration.

Common Commands

npx --yes --package agent-project-sdlc@latest sdlc-harness init
npx --yes --package agent-project-sdlc@latest sdlc-harness init --adopt
npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --all
npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --full
npx --yes --package agent-project-sdlc@latest sdlc-harness export-context --code
make sdlc-sync
make sdlc-upgrade
npx --yes --package agent-project-sdlc@latest sdlc-harness validate-context
npx --yes --package agent-project-sdlc@latest sdlc-harness doctor
make sdlc-doctor
make validate-context
make validate-harness

make validate-harness is a compatibility alias for validate-context in vNext projects.

Current Boundary

The former stage-based SDLC Harness is no longer shipped as a runnable default, compatibility layer or migration command.

The package direction is now smaller: keep the minimum durable facts that help agents recover context and continue safely.