Minimal Context Sample Project

July 30, 2026 · View on GitHub

This sample shows what a small project can look like after adopting Project Tiny Context Harness. It is not a benchmark, template requirement or product-quality proof. It is a concrete shape for the recovery surface a fresh coding agent should read first.

For a file-by-file version with tiny source code, tests and validate-context, browse examples/minimal-context-sample/.

Scenario

Imagine a small issue-labeling service:

  • It reads incoming GitHub issues.
  • It proposes labels for a maintainer.
  • It must not auto-apply labels without review.
  • Most agent mistakes happen when a fresh chat forgets that boundary and edits the wrong workflow path.

The project does not need a full Tiny Context process. It needs a small durable memory surface.

Files

After ty-context init, the important files are:

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

AGENTS.md

Keep this file as a startup router, not a full manual:

# Minimal Context Harness Protocol

This project uses Minimal Context Harness.

## Fact Sources

- Project context: `project_context/global.md`
- Architecture context: `project_context/architecture.md`
- Context graph: `project_context/context.toml`
- Product area context: `project_context/areas/**/*.md`

## Work Rule

Read the relevant Context before changing code. If a change creates a durable product, architecture, API, state or validation fact, update `project_context/**`.

## Verification

- `make validate-context`
- `npm test -- label-routing`

The real generated AGENTS.md contains more guardrails, but the important product shape is that it points the agent to the fact sources and validation entry points.

project_context/global.md

Keep only durable project-level facts:

# Project / Delivery Context

## Project Goal

- Suggest labels for new GitHub issues so maintainers can triage faster.

## Non-goals / Boundaries

- Do not auto-apply labels without maintainer review.
- Do not store GitHub tokens in Context files.
- Do not turn label suggestions into issue-priority decisions.

## Background

- Fresh agent chats often rediscover the review boundary and accidentally inspect deployment automation first.

## Verification Entry Points

- `npm test -- label-routing`
- `make validate-context`

## Current State

- Label suggestions are produced by the label-routing module.
- GitHub webhook parsing is a separate boundary.

## Next Safe Action

- Inspect label-routing tests before changing suggestion behavior.

project_context/architecture.md

Keep architecture facts short:

# Architecture Context

## System Boundary

- The service proposes labels; maintainers decide whether to apply them.
- GitHub API writes belong only to the reviewed-apply workflow.

## Component Map

- `src/webhook/**`: receives GitHub issue events.
- `src/label-routing/**`: maps issue text to suggested labels.
- `src/review-ui/**`: shows suggestions to maintainers.

## Constraints And Tradeoffs

- Label-routing must not import reviewed-apply code.
- Tests should cover no-write behavior for suggestion-only paths.

## Verification Implications

- `npm test -- label-routing`
- `npm test -- webhook`

project_context/areas/main.md

Use area Context for ownership and local constraints:

# Main Area Context

## Responsibility

- Own label suggestion behavior for GitHub issue triage.

## User / System Contract

- Input: GitHub issue title and body.
- Output: suggested labels with a short reason.
- The output is advisory until a maintainer approves it.

## Key Constraints

- Do not mutate GitHub issue labels in suggestion code.
- Keep label taxonomy changes explicit in tests.

## Code Entry Points

- `src/label-routing/suggest-labels.ts`
- `tests/label-routing.test.ts`

Sparse Context Workspace / Monorepo Variant

Keep Context centralized and add a workspace directory only when that implementation workspace owns durable non-code facts:

project_context/
  areas/
    repository.md
    shared-service.md
  workspaces/
    mobile/
      areas/
        product.md
        verification.md
    miniapp/
      areas/
        product.md

Use the existing manifest fields to map each represented Context workspace to one repository-relative code root:

[[areas]]
id = "repository"
root = "."
context = "project_context/areas/repository.md"
kind = "repository"
default = true

[[areas]]
id = "mobile-product"
root = "apps/mobile"
context = "project_context/workspaces/mobile/areas/product.md"
kind = "app"

[[context]]
path = "project_context/workspaces/mobile/areas/verification.md"
role = "verification"
read_policy = "on-demand"
triggers = ["mobile test", "mobile verification"]

[[areas]]
id = "miniapp-product"
root = "apps/miniapp"
context = "project_context/workspaces/miniapp/areas/product.md"
kind = "app"

[[areas]]
id = "shared-service"
root = "packages/service"
context = "project_context/areas/shared-service.md"
kind = "service"

The small top-level repository Area owns only the common default recovery facts. The mobile and miniapp Context workspaces each refer to exactly one code root and remain on-demand; more workspace-local Area/role Context can live below the same directory when that root has several durable semantic responsibilities. shared-service.md stays top-level because it is cross-workspace. A code workspace such as packages/eslint-config may exist without any Context directory or manifest entry when it owns no durable non-code facts. Package-manager/build configuration—not Context—remains the complete workspace inventory.

The default Area, read_policy, triggers and bounded search choose the initial Context working set only. A miniapp task may read shared-service or mobile contract Context when necessary, but those reads do not authorize mobile edits. Resolve intended workspace(s) from user/product/path/repository facts; if “change the homepage” still identifies several sibling clients, clarify the target before product edits. A cross-client request names every intended workspace and any supporting/shared scope.

If the repository has a project-specific changed-path scope verifier, index its stable command in verification Context and run it on task-attributable paths. Otherwise review the final diff against Context/code ownership during Conformance. Root DESIGN.md remains the shared Design Authority. This layout adds no [[workspaces]] schema, empty-directory requirement, automatic topology scan, read ACL, full-Context default or persisted target declaration.

project_context/areas/main/verification.md

Use verification role Context for repeatable validation paths, not one-off logs:

# Main Verification Context

## Critical Paths

- Label-routing behavior: `npm test -- label-routing`
- Webhook parsing: `npm test -- webhook`
- Context recovery: `make validate-context`

## Expected Signals

- Label-routing tests should include an advisory-only case.
- `validate-context` should pass without storing test-result claims in Context.

## Known Dead Ends

- Running only the webhook tests does not cover label taxonomy changes.

Fresh-Agent Prompt

Start a new coding-agent chat with:

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.

A useful answer should recover:

  • The service suggests labels but does not auto-apply them.
  • Label routing, webhook parsing and reviewed apply are separate boundaries.
  • The focused validation path starts with npm test -- label-routing.
  • Context files should not store tokens, logs or fake "tests passed" claims.

What To Copy

Copy the shape, not the domain:

  • Keep AGENTS.md short and directive.
  • Put durable project intent in global.md.
  • Put stable system boundaries in architecture.md.
  • Put owned product/module facts in areas/**.
  • Put repeatable validation paths in verification role Context.
  • Leave execution evidence in tests, CI and review.

What Not To Copy

  • Do not create phase gates or task state just because the project uses agents.
  • Do not paste code, logs or release reports into Context.
  • Do not claim benchmark speedups from this sample.
  • Do not replace tests or human review with validate-context.