project-tiny-context-harness

Purpose

project-tiny-context-harness is a minimalist project memory and validation tool for AI coding agents. It helps coding agents find project-specific requirements within a project and lets agents maintain those requirements without being forced into an engineering workflow.

The tool installs a short development contract into AGENTS.md and preserves persistent project facts. The source code version is 0.12.1, the configuration schema version is 5, and a schema-4 installation requires upgrading in update mode upgrade-required.

Main capabilities

• Installs AGENTS.md as a managed startup entry point.
• Installs project context files in the project_context/ directory.
• Provides Role Skills.
• Provides a validate-context gate for checking structure.
• Preserves persistent project facts, such as goals and non-goals, ownership and dependency boundaries, confirmed decisions and their reasons, project constraints, and repeatable operations/source entry points.
• References exact values from real sources instead of copying code.
• By default does not install architecture, Areas, design systems, Role Skills, Hooks, Makefile, the tools directory, or CI workflows.
• Uses context-mutation-journal-v3 to record Context changes, with compatible reading of context-mutation-journal-v2.
• Provides an optional design-resource Skill that uses Stitch for visual generation and design revisions.

Usage

Requires Node.js 24 or later. Install the package version you intend to use, then run its local CLI.

A normal init only creates AGENTS.md, .agent/config.yaml, project_context/global.md, and project_context/context.toml. It preserves existing files and leaves project facts as TODO until they are known. Temporary file-maintenance locks may create tmp/ty-context; they are not task state. Use --adopt for existing projects. Explicitly specifying --harness-folder .codex stores that optional location in package.json; changing the root directory of an existing installation requires a separate migration.

For unpublished source checkouts, build and install its actual tarball rather than assuming the published package contains those changes.

AGENTS.md is the managed startup entry point. A root-level AGENTS.override.md can shadow it; doctor will report that observable condition. Host and nested instruction scopes may differ: file installation does not prove that the current model has loaded or follows the contract. Global host settings will not be modified.

Read the defaults, then read the relevant owners. The new defaults include project_context/global.md as well as explicit project selections. In schema 5, architecture.md has no special default status. context.toml is routing metadata, not default body content. Queries will show paths, reasons, diagnostics, and whether the set is complete. An invalid manifest returns a non-success status; partial results will never be a complete empty set.

The CLI is optional for reads. When offline, read global.md and use the direct default_files in the manifest, the default Area, and the read_policy = "default" node together with its transitive default_children. Direct files and the default Area themselves do not seed traversal. Child edges retain their existing semantics, including referenced never-default nodes. The legacy always, optional, and never-default names do not imply the new selection behavior; diagnostics will explain legacy metadata. When the set is known and unchanged, do not reinstall the CLI or repeat queries.

Applicable Scenarios

Applicable to projects that use Codex, Claude Code, Cursor, Gemini CLI, OpenCode, or similar AI coding agents and want to restore project intent, boundaries, and verification paths across multiple new sessions.

Applicable to projects that need to preserve long-term project facts, confirmed decisions, and dependency boundaries.

Applicable to projects that need optional resource creation and adoption capabilities (design-resource Skill), which uses Stitch for visual generation and design revision, prioritizing the official MCP, and using the authenticated official Stitch website when MCP is unavailable.

Applicable to scenarios where the resource Skill has already been composed into a project, preserving the project entry point and composing and packaging capabilitiesforce. Project entry points can add target platform handling, reference conventions, export/integration processes, and project-specific checks.

Limitations

• Requires Node.js 24 or later.
• The default init does not install architecture, Areas, design systems, role Skills, Hooks, a Makefile, a tools directory, or CI workflows.
• There are no mandatory headings, task progress fields, stable Fact IDs, or source line limits.
• TODOs and historical test records are allowed.
• Temporary exports and optional handoff notes are not another long-term source of truth.
• Replacing multiple filesystems is not an atomic transaction; do not overwrite conflicting files just to make recovery pass.
• Sync only replaces the managed startup block and preserves surrounding user text. Schema mismatches, incomplete upgrade/Context transactions, and conflicting writes stop the related maintenance.
• Structural success proves neither adoption, agent review, aesthetics, nor production correctness.
• Resource availability and runtime checks are explicit task work.
• Existing declaration checks repository-relative local UTF-8 entry points; it does not recursively check linked assets or declarations within that entry point, does not load images, does not access external links, and does not add resources to the default Context.
• Duplicate declarations of the same target are diagnosed, even within the same domain.
• Skills do not install servers, obtain credentials, or edit global settings. Copying or reading a Skill itself does not make its MCP available.
• Project Skills and copied Skills are owned by the project: init, sync, and upgrade will not install or update them.
• Design directories or resource templates are not created automatically.
• If a referenced package is unavailable, the missing foundation should be reported rather than pretending it has been read.
• No specific billing, pricing, or platform support scope details are provided.