project-tiny-context-harness 0.2.67 → 0.2.69
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +95 -95
- package/assets/README.md +106 -106
- package/assets/skills/normal-long-task/SKILL.md +486 -473
- package/assets/skills/superpowers-long-task/SKILL.md +256 -241
- package/package.json +69 -68
package/README.md
CHANGED
|
@@ -8,15 +8,15 @@
|
|
|
8
8
|
|
|
9
9
|
Translations: [Chinese (Simplified)](https://github.com/Seven128/project-tiny-context-harness/blob/main/README.zh-CN.md)
|
|
10
10
|
|
|
11
|
-
`project-tiny-context-harness` ships the `ty-context` CLI for Project Tiny Context Harness: repo-native project memory for AI coding agents and a repo-native context contract.
|
|
12
|
-
|
|
13
|
-
The default is **Minimal Context Harness**. It maintains a compact `project_context/**` fact source, a short `AGENTS.md` startup router, role Skills, priority guidance for Context/code/evidence, and a `validate-context` gate so fresh agents can recover project intent, constraints, verification entry points and next safe actions quickly.
|
|
11
|
+
`project-tiny-context-harness` ships the `ty-context` CLI for Project Tiny Context Harness: repo-native project memory for AI coding agents and a repo-native context contract.
|
|
12
|
+
|
|
13
|
+
The default is **Minimal Context Harness**. It maintains a compact `project_context/**` fact source, a short `AGENTS.md` startup router, role Skills, priority guidance for Context/code/evidence, and a `validate-context` gate so fresh agents can recover project intent, constraints, verification entry points and next safe actions quickly.
|
|
14
14
|
|
|
15
15
|
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.
|
|
16
16
|
|
|
17
17
|
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.
|
|
18
18
|
|
|
19
|
-
Think of it as durable project memory behind `AGENTS.md`, plus priority rules for Context/code/evidence, not another agent, process framework or task manager.
|
|
19
|
+
Think of it as durable project memory behind `AGENTS.md`, plus priority rules for Context/code/evidence, not another agent, process framework or task manager.
|
|
20
20
|
|
|
21
21
|
Best for:
|
|
22
22
|
|
|
@@ -63,50 +63,50 @@ No-install preview:
|
|
|
63
63
|
|
|
64
64
|
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.
|
|
65
65
|
|
|
66
|
-
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.
|
|
67
|
-
|
|
68
|
-
The concrete failure mode is not only missing file search. In an ABCD module chain where A/B/C are upstream of downstream D, a D feature can expose a missing capability. Without Context, an agent may change upstream A/B to make D pass because current code permits it. Minimal Context adds a repo-owned intent layer: it records whether downstream D may change upstream A/B, whether the gap belongs in C's contract, or whether the task needs a `Context Delta` before implementation continues. Code shows what is possible; it cannot decide whether that is allowed project intent.
|
|
69
|
-
|
|
70
|
-
The core bet is: **keep the memory, drop the ceremony**. Earlier stage-based workflows pushed ordinary software work through explicit phase artifacts and gates. Modern coding agents already internalize much of the understand, design, implement, test and repair loop, so Project Tiny Context Harness keeps the high-density repo context that survives fresh chats without making every task follow Tiny Context-stage choreography.
|
|
71
|
-
|
|
72
|
-
## Current Best Practice
|
|
73
|
-
|
|
74
|
-
For short tasks, use the workflow contract and Context layer directly:
|
|
75
|
-
|
|
76
|
-
```text
|
|
77
|
-
workflow contract + project_context/** -> implementation -> verification -> drift check
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
For long-running tasks, externalize the target first. Use explicit Skill invocation instead of broad keyword triggering:
|
|
81
|
-
|
|
82
|
-
```text
|
|
83
|
-
Web GPT or another external planning model produces a two-document upstream input
|
|
84
|
-
-> /normal-long-task produces the full checklist and optional generic target-mode prompt
|
|
85
|
-
-> /superpowers-long-task produces the Superpowers target-mode prompt when Superpowers execution is needed
|
|
86
|
-
-> Superpowers derives concrete implementation slices
|
|
87
|
-
-> each slice follows the workflow contract + project_context/**
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
For best target-mode results, the two-document upstream input should be a `Development Plan` for execution direction and an `Acceptance and Tests` packet for acceptance authority. The development plan preserves the original requirement source and implementation direction; the acceptance packet supplies ACs, required evidence, tests, real product/core paths, evidence layers, invalid evidence, state-machine rules, local audit requirements and blockers. Source Pack exports are temporary upload material for external planning, not durable Context.
|
|
91
|
-
|
|
92
|
-
The ordinary long-task path uses `/normal-long-task`. It is the non-Superpowers acceptance pass: it can generate or reuse the full acceptance checklist and can produce a generic target-mode prompt.
|
|
93
|
-
|
|
94
|
-
The Superpowers long-task path uses `/superpowers-long-task` only after the full checklist exists. It consumes the complete packet from `/normal-long-task`, emits a Superpowers-specific target-mode prompt and cannot generate or repair the checklist. That prompt is Tiny Context's adapter layer, not a Superpowers official schema.
|
|
95
|
-
|
|
96
|
-
The recommended Superpowers layer is the specific [obra/Superpowers](https://github.com/obra/superpowers) plugin/workflow, not a generic planning substitute. Use `superpowers:writing-plans` when the target-mode prompt or source plan still needs bite-sized implementation tasks, then prefer `superpowers:subagent-driven-development` when subagents are available and `superpowers:executing-plans` otherwise. Behavior changes should use `superpowers:test-driven-development`, and completion claims should use `superpowers:verification-before-completion` against the full checklist and fresh evidence.
|
|
97
|
-
|
|
98
|
-
The reason is drift control. The workflow contract plus Context layer is intentionally a soft constraint. It works well for short tasks, and Context can still capture the expected facts for long tasks, but long execution makes the Context-to-code step drift as the context window grows, work is handed off, subagents split scope or validation loops multiply. A Web GPT plan, explicit long-task Skill invocation, target-mode prompt, full acceptance checklist and optional Superpowers execution layer make the completion target recoverable without restoring a phase-gated workflow.
|
|
99
|
-
|
|
100
|
-
## Positioning
|
|
101
|
-
|
|
102
|
-
| Adjacent tool type | Use it for | Harness stance |
|
|
103
|
-
|---|---|---|
|
|
104
|
-
| Spec-first kits | Turning feature ideas into structured specs and plans. | Complementary; Harness keeps durable repo facts and module boundary intent beyond one feature spec. |
|
|
105
|
-
| BMAD-style workflows and full Tiny Context processes | Coordinated role/process ceremonies on high-risk work. | Lighter default; no phase gates or work-product trees. |
|
|
106
|
-
| Superpowers-style execution | Turning approved requirements into plans, subagent execution, TDD, review and finish discipline. | Complementary; use it to execute while Tiny Context owns durable repo intent and acceptance priority. |
|
|
107
|
-
| Task Master-style planners | Backlog decomposition and task execution state. | Complementary; Harness does not own task state. |
|
|
108
|
-
| Context7/Serena-style retrieval or code-intelligence tools | Pulling external docs, symbols or repository facts on demand. | Complementary; they do not answer whether downstream D may change upstream A/B. Harness stores that local repo truth. |
|
|
109
|
-
| IDE or agent memory | Tool-specific continuity inside one product surface. | Portable fallback; plain files any agent can read. |
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
The concrete failure mode is not only missing file search. In an ABCD module chain where A/B/C are upstream of downstream D, a D feature can expose a missing capability. Without Context, an agent may change upstream A/B to make D pass because current code permits it. Minimal Context adds a repo-owned intent layer: it records whether downstream D may change upstream A/B, whether the gap belongs in C's contract, or whether the task needs a `Context Delta` before implementation continues. Code shows what is possible; it cannot decide whether that is allowed project intent.
|
|
69
|
+
|
|
70
|
+
The core bet is: **keep the memory, drop the ceremony**. Earlier stage-based workflows pushed ordinary software work through explicit phase artifacts and gates. Modern coding agents already internalize much of the understand, design, implement, test and repair loop, so Project Tiny Context Harness keeps the high-density repo context that survives fresh chats without making every task follow Tiny Context-stage choreography.
|
|
71
|
+
|
|
72
|
+
## Current Best Practice
|
|
73
|
+
|
|
74
|
+
For short tasks, use the workflow contract and Context layer directly:
|
|
75
|
+
|
|
76
|
+
```text
|
|
77
|
+
workflow contract + project_context/** -> implementation -> verification -> drift check
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
For long-running tasks, externalize the target first. Use explicit Skill invocation instead of broad keyword triggering:
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
Web GPT or another external planning model produces a two-document upstream input
|
|
84
|
+
-> /normal-long-task produces the full checklist and optional generic target-mode prompt
|
|
85
|
+
-> /superpowers-long-task produces the Superpowers target-mode prompt when Superpowers execution is needed
|
|
86
|
+
-> Superpowers derives concrete implementation slices
|
|
87
|
+
-> each slice follows the workflow contract + project_context/**
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
For best target-mode results, the two-document upstream input should be a `Development Plan` for execution direction and an `Acceptance and Tests` packet for acceptance authority. The development plan preserves the original requirement source and implementation direction; the acceptance packet supplies ACs, required evidence, tests, real product/core paths, evidence layers, invalid evidence, state-machine rules, local audit requirements and blockers. Source Pack exports are temporary upload material for external planning, not durable Context.
|
|
91
|
+
|
|
92
|
+
The ordinary long-task path uses `/normal-long-task`. It is the non-Superpowers acceptance pass: it can generate or reuse the full acceptance checklist and can produce a generic target-mode prompt.
|
|
93
|
+
|
|
94
|
+
The Superpowers long-task path uses `/superpowers-long-task` only after the full checklist exists. It consumes the complete packet from `/normal-long-task`, emits a Superpowers-specific target-mode prompt and cannot generate or repair the checklist. That prompt is Tiny Context's adapter layer, not a Superpowers official schema.
|
|
95
|
+
|
|
96
|
+
The recommended Superpowers layer is the specific [obra/Superpowers](https://github.com/obra/superpowers) plugin/workflow, not a generic planning substitute. Use `superpowers:writing-plans` when the target-mode prompt or source plan still needs bite-sized implementation tasks, then prefer `superpowers:subagent-driven-development` when subagents are available and `superpowers:executing-plans` otherwise. Behavior changes should use `superpowers:test-driven-development`, and completion claims should use `superpowers:verification-before-completion` against the full checklist and fresh evidence.
|
|
97
|
+
|
|
98
|
+
The reason is drift control. The workflow contract plus Context layer is intentionally a soft constraint. It works well for short tasks, and Context can still capture the expected facts for long tasks, but long execution makes the Context-to-code step drift as the context window grows, work is handed off, subagents split scope or validation loops multiply. A Web GPT plan, explicit long-task Skill invocation, target-mode prompt, full acceptance checklist and optional Superpowers execution layer make the completion target recoverable without restoring a phase-gated workflow.
|
|
99
|
+
|
|
100
|
+
## Positioning
|
|
101
|
+
|
|
102
|
+
| Adjacent tool type | Use it for | Harness stance |
|
|
103
|
+
|---|---|---|
|
|
104
|
+
| Spec-first kits | Turning feature ideas into structured specs and plans. | Complementary; Harness keeps durable repo facts and module boundary intent beyond one feature spec. |
|
|
105
|
+
| BMAD-style workflows and full Tiny Context processes | Coordinated role/process ceremonies on high-risk work. | Lighter default; no phase gates or work-product trees. |
|
|
106
|
+
| Superpowers-style execution | Turning approved requirements into plans, subagent execution, TDD, review and finish discipline. | Complementary; use it to execute while Tiny Context owns durable repo intent and acceptance priority. |
|
|
107
|
+
| Task Master-style planners | Backlog decomposition and task execution state. | Complementary; Harness does not own task state. |
|
|
108
|
+
| Context7/Serena-style retrieval or code-intelligence tools | Pulling external docs, symbols or repository facts on demand. | Complementary; they do not answer whether downstream D may change upstream A/B. Harness stores that local repo truth. |
|
|
109
|
+
| IDE or agent memory | Tool-specific continuity inside one product surface. | Portable fallback; plain files any agent can read. |
|
|
110
110
|
|
|
111
111
|
## Try It In 60 Seconds
|
|
112
112
|
|
|
@@ -146,7 +146,7 @@ npm ci
|
|
|
146
146
|
npm run smoke:quickstart
|
|
147
147
|
npm run preview:pack
|
|
148
148
|
cd /path/to/your/test-repo
|
|
149
|
-
npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.
|
|
149
|
+
npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.69.tgz
|
|
150
150
|
npx --no-install ty-context init --adopt
|
|
151
151
|
make validate-context
|
|
152
152
|
```
|
|
@@ -215,7 +215,7 @@ For existing projects:
|
|
|
215
215
|
npx --yes --package project-tiny-context-harness@latest ty-context init --adopt
|
|
216
216
|
```
|
|
217
217
|
|
|
218
|
-
`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 Product Surface Contract Skill, a full-project export Skill, a Harness upgrade Skill, the `/normal-long-task` and `/superpowers-long-task` Skills, managed templates/tools, a Makefile include and `.github/workflows/harness.yml`. The generated workflow runs only the selected Harness gate: `validate-context`, `validate-code-modularity` or the composite `validate-harness`; maintainer-only package tests and source-drift checks are intentionally kept out of consumer projects. It does not create business Product Surface Contract files, stage work-product trees, lifecycle state or stage skills by default.
|
|
218
|
+
`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 Product Surface Contract Skill, a full-project export Skill, a Harness upgrade Skill, the `/normal-long-task` and `/superpowers-long-task` Skills, managed templates/tools, a Makefile include and `.github/workflows/harness.yml`. The generated workflow runs only the selected Harness gate: `validate-context`, `validate-code-modularity` or the composite `validate-harness`; maintainer-only package tests and source-drift checks are intentionally kept out of consumer projects. It does not create business Product Surface Contract files, stage work-product trees, lifecycle state or stage skills by default.
|
|
219
219
|
|
|
220
220
|
## FAQ
|
|
221
221
|
|
|
@@ -258,18 +258,18 @@ Use `npx --no-install ty-context ...` only when you explicitly want the already
|
|
|
258
258
|
| UI/UX design Skill | `<harnessRoot>/skills/context_uiux_design/SKILL.md` | Handles explicit UI/UX design 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. |
|
|
259
259
|
| Development engineer Skill | `<harnessRoot>/skills/context_development_engineer/SKILL.md` | Handles explicit development-engineering requests and writes durable engineering conclusions to `project_context/**`. |
|
|
260
260
|
| Product Surface Contract Skill | `<harnessRoot>/skills/context_surface_contract/SKILL.md` | Handles explicit Product Surface Contract, Screen Contract, surface responsibility and main/drilldown ownership work; it compiles project-owned surface contracts into `project_context/**` without adding a new context role or gate. |
|
|
261
|
-
| Full project context export Skill | `<harnessRoot>/skills/context_full_project_export/SKILL.md` | Handles explicit full-project, project-overall, Source Pack or code-level export requests and uses `export-context --source-pack`, `--code-index`, `--task-context`, `--all`, `--full` or `--code` to create temporary artifacts under `tmp/ty-context/context-exports/**`. |
|
|
261
|
+
| Full project context export Skill | `<harnessRoot>/skills/context_full_project_export/SKILL.md` | Handles explicit full-project, project-overall, Source Pack or code-level export requests and uses `export-context --source-pack`, `--code-index`, `--task-context`, `--all`, `--full` or `--code` to create temporary artifacts under `tmp/ty-context/context-exports/**`. |
|
|
262
262
|
| Harness upgrade Skill | `<harnessRoot>/skills/context_harness_upgrade/SKILL.md` | Handles explicit Tiny Context / Project Tiny Context Harness upgrade requests such as “upgrade Tiny Context” and “use the Tiny Context upgrade skill to upgrade this project”; it runs the canonical `upgrade` path, handles only migration-scoped `manual_required` / `blocked` follow-up, then runs diagnostics. |
|
|
263
|
-
| Ordinary long-task Skill | `<harnessRoot>/skills/normal-long-task/SKILL.md` | Invoke as `/normal-long-task` to turn a referenced plan, RFC, implementation proposal or two-document upstream input into a falsifiable acceptance checklist and optional generic paste-ready goal/target-mode prompt under `tmp/ty-context/plan-acceptance/**`; if the plan already contains an explicit concrete checklist, the Skill reuses it verbatim in the separate full-checklist file; compact summaries are only navigation/priority, but the Skill does not execute the plan or prove completion. |
|
|
264
|
-
| Superpowers long-task Skill | `<harnessRoot>/skills/superpowers-long-task/SKILL.md` | Invoke as `/superpowers-long-task` after the full checklist exists. It consumes the implementation/source plan, full checklist and local audit path, emits a Superpowers-specific prompt with the official workflow skill names, and stops when required input fields are missing. It is not a Superpowers official schema and does not generate the checklist or execute the plan. |
|
|
263
|
+
| Ordinary long-task Skill | `<harnessRoot>/skills/normal-long-task/SKILL.md` | Invoke as `/normal-long-task` to turn a referenced plan, RFC, implementation proposal or two-document upstream input into a falsifiable acceptance checklist and optional generic paste-ready goal/target-mode prompt under `tmp/ty-context/plan-acceptance/**`; if the plan already contains an explicit concrete checklist, the Skill reuses it verbatim in the separate full-checklist file; compact summaries are only navigation/priority, but the Skill does not execute the plan or prove completion. |
|
|
264
|
+
| Superpowers long-task Skill | `<harnessRoot>/skills/superpowers-long-task/SKILL.md` | Invoke as `/superpowers-long-task` after the full checklist exists. It consumes the implementation/source plan, full checklist and local audit path, emits a Superpowers-specific prompt with the official workflow skill names, and stops when required input fields are missing. It is not a Superpowers official schema and does not generate the checklist or execute the plan. |
|
|
265
265
|
| 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. |
|
|
266
266
|
| Managed file sync | `make ty-context-sync` or `npx --yes --package project-tiny-context-harness@latest ty-context sync` | Refreshes package-managed guidance, default Skills, Makefile include, context templates, tools and workflow YAML. It does not run migrations or perform semantic Context generation; it may block only direct asset-refresh safety issues such as invalid managed blocks or deprecated managed Skill overrides. |
|
|
267
|
-
| Upgrade | `make ty-context-upgrade` or `npx --yes --package project-tiny-context-harness@latest ty-context upgrade` | Use for releases marked `upgrade-required` or `manual-required`. Builds an upgrade plan, stops before writes when `blocked` items exist, otherwise applies `safe_pending` migrations, runs `sync` and `doctor`, and exits non-zero when manual follow-up or diagnostics remain. |
|
|
268
|
-
| Upgrade check | `npx --yes --package project-tiny-context-harness@latest ty-context upgrade --check [--json]` | Checks the upgrade plan without writing files. Reports `safe_pending`, `manual_required` and `blocked`; exits non-zero when any work remains. |
|
|
269
|
-
| Source Pack export | `npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack [--check]` | Creates a bounded Source Pack under `tmp/ty-context/context-exports/latest/` with upload-ready Context, code index and optional bundles, removing old timestamped rounds. |
|
|
270
|
-
| Code index export | `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code-index [--check]` | Creates a temporary implementation navigation index and manifest without complete source bodies. |
|
|
271
|
-
| Task context export | `npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context <name> [--profile <id>] [--check]` | Creates a bounded focused task handoff pack from profile or explicit include selectors. |
|
|
272
|
-
| Combined project export | `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all [--check]` | Creates both default temporary exports under `tmp/ty-context/context-exports/**`. |
|
|
267
|
+
| Upgrade | `make ty-context-upgrade` or `npx --yes --package project-tiny-context-harness@latest ty-context upgrade` | Use for releases marked `upgrade-required` or `manual-required`. Builds an upgrade plan, stops before writes when `blocked` items exist, otherwise applies `safe_pending` migrations, runs `sync` and `doctor`, and exits non-zero when manual follow-up or diagnostics remain. |
|
|
268
|
+
| Upgrade check | `npx --yes --package project-tiny-context-harness@latest ty-context upgrade --check [--json]` | Checks the upgrade plan without writing files. Reports `safe_pending`, `manual_required` and `blocked`; exits non-zero when any work remains. |
|
|
269
|
+
| Source Pack export | `npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack [--check]` | Creates a bounded Source Pack under `tmp/ty-context/context-exports/latest/` with upload-ready Context, code index and optional bundles, removing old timestamped rounds. |
|
|
270
|
+
| Code index export | `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code-index [--check]` | Creates a temporary implementation navigation index and manifest without complete source bodies. |
|
|
271
|
+
| Task context export | `npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context <name> [--profile <id>] [--check]` | Creates a bounded focused task handoff pack from profile or explicit include selectors. |
|
|
272
|
+
| Combined project export | `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all [--check]` | Creates both default temporary exports under `tmp/ty-context/context-exports/**`. |
|
|
273
273
|
| Project Context export | `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full [--output tmp/ty-context/context-exports/name.md] [--check]` | Creates a temporary Context summary artifact. It is not Context and must not be registered in `project_context/context.toml`. |
|
|
274
274
|
| Code implementation export | `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code [--output tmp/ty-context/context-exports/name.md] [--check]` | Creates a temporary single-file code implementation artifact. It is not Context and must not be registered in `project_context/context.toml`. |
|
|
275
275
|
| Modularity check | `npx --yes --package project-tiny-context-harness@latest ty-context check-modularity --touched [--limit 300] [--fail-on-warning]` | Reports selected handwritten source files over the physical line-count limit; `--file <path>` and `--base <ref>` select explicit files or branch changes, and config waivers are reported distinctly. |
|
|
@@ -283,9 +283,9 @@ For high-risk product, UI/UX and engineering tasks that affect durable architect
|
|
|
283
283
|
|
|
284
284
|
Technical architecture support is a Minimal Context capability: use restrained `architecture.md`, area Module Design Capsules and existing `contract` / `decision-rationale` roles when durable architecture or rationale matters. Do not invent rationale; store stable reasons, rejected alternatives or tradeoffs only in the smallest durable Context surface when they will affect future implementation or verification choices.
|
|
285
285
|
|
|
286
|
-
For long-running plans, RFCs or implementation proposals, invoke `/normal-long-task` to turn a plan plus relevant Context into a falsifiable acceptance checklist and an optional generic paste-ready goal/target-mode prompt. It also supports a two-document upstream input from Web GPT or another external planner: `Development Plan` for execution direction and `Acceptance and Tests` for target-mode acceptance input. If the plan already contains an explicit concrete acceptance checklist, the Skill copies that checklist verbatim into a separate full-checklist file instead of generating a competing checklist. The two-document packet path is strict mode: when required fields cannot be fully parsed from both documents, the Skill preserves the inputs, reports the missing fields, and stops without generating a checklist or goal/target-mode prompt. It is one pre-execution acceptance pass, not a task planner or workflow engine: it stores temporary inputs under `tmp/ty-context/plan-acceptance/**`, asks for confirmation when durable assumptions are unclear, and leaves execution evidence to the future executor, tests, CI, review or human acceptance. The generated prompt may require a local audit under the same temporary directory so future sessions can recover acceptance progress; that audit is not Context, not a quality proof and not a replacement for the project's Tiny Context workflow contract. When the prompt references a full checklist, that checklist is the acceptance authority; compact prompt text is only navigation, priority and recovery guidance.
|
|
287
|
-
|
|
288
|
-
When the next step explicitly needs Superpowers, invoke `/superpowers-long-task` on the completed packet from `/normal-long-task`. It emits the `Superpowers input packet` and execution binding so the future executor sees which inputs feed `superpowers:writing-plans`, `superpowers:subagent-driven-development`, `superpowers:executing-plans`, TDD, `superpowers:verification-before-completion` and local audit. This is Tiny Context's adapter layer, not a Superpowers official schema, and it cannot replace `/normal-long-task` for missing checklist fields.
|
|
286
|
+
For long-running plans, RFCs or implementation proposals, invoke `/normal-long-task` to turn a plan plus relevant Context into a falsifiable acceptance checklist and an optional generic paste-ready goal/target-mode prompt. It also supports a two-document upstream input from Web GPT or another external planner: `Development Plan` for execution direction and `Acceptance and Tests` for target-mode acceptance input. If the plan already contains an explicit concrete acceptance checklist, the Skill copies that checklist verbatim into a separate full-checklist file instead of generating a competing checklist. The two-document packet path is strict mode: when required fields cannot be fully parsed from both documents, the Skill preserves the inputs, reports the missing fields, and stops without generating a checklist or goal/target-mode prompt. It is one pre-execution acceptance pass, not a task planner or workflow engine: it stores temporary inputs under `tmp/ty-context/plan-acceptance/**`, asks for confirmation when durable assumptions are unclear, and leaves execution evidence to the future executor, tests, CI, review or human acceptance. The generated prompt may require a local audit under the same temporary directory so future sessions can recover acceptance progress; that audit is not Context, not a quality proof and not a replacement for the project's Tiny Context workflow contract. When the prompt references a full checklist, that checklist is the acceptance authority; compact prompt text is only navigation, priority and recovery guidance.
|
|
287
|
+
|
|
288
|
+
When the next step explicitly needs Superpowers, invoke `/superpowers-long-task` on the completed packet from `/normal-long-task`. It emits the `Superpowers input packet` and execution binding so the future executor sees which inputs feed `superpowers:writing-plans`, `superpowers:subagent-driven-development`, `superpowers:executing-plans`, TDD, `superpowers:verification-before-completion` and local audit. This is Tiny Context's adapter layer, not a Superpowers official schema, and it cannot replace `/normal-long-task` for missing checklist fields.
|
|
289
289
|
|
|
290
290
|
For Product Surface work, `context_surface_contract` turns broad product/page/UI principles into project-owned surface responsibilities. A Product Surface can be a Web page, mobile screen, desktop window, game UI/HUD/menu, CLI/TUI output, extension UI or embedded/device interface. Cross-surface contracts use the existing `contract` role; area-owned screen facts stay in `area` or `subdomain`; repeatable validation paths use `verification`. The Harness does not add a new surface-specific role, does not create business surface contracts during `init` or `upgrade`, and does not turn surface conformance into a validator gate. Projects that want mandatory task blocks should add a separate project-local Skill, while `product-surface-contract.md` is only a compact managed template for optional Context authoring.
|
|
291
291
|
|
|
@@ -395,37 +395,37 @@ When authoring, migrating or cleaning up `project_context/areas/**`, run a soft
|
|
|
395
395
|
|
|
396
396
|
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.
|
|
397
397
|
|
|
398
|
-
## Temporary Project Exports
|
|
399
|
-
|
|
400
|
-
`export-context --source-pack` is the recommended external LLM / Web GPT planning path:
|
|
401
|
-
|
|
402
|
-
```sh
|
|
403
|
-
npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack
|
|
404
|
-
npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack --check
|
|
405
|
-
```
|
|
406
|
-
|
|
407
|
-
It writes `tmp/ty-context/context-exports/latest/` as ordinary files/directories and removes old timestamped export rounds. A standard Source Pack is capped at 5 files: `source-pack-manifest.json`, `full-project-context.md`, `code-index.md`, and at most `code-bundle-core.md` plus `code-bundle-extended.md`; small projects may omit bundles. The `source-pack-v1` manifest uses repo-relative artifact paths and hashes, aggregates warnings and omitted files, and recommends upload sets for daily planning, cross-module review and full fallback.
|
|
408
|
-
|
|
409
|
-
`export-context --code-index` creates the navigation index and manifest without complete source bodies:
|
|
410
|
-
|
|
411
|
-
```sh
|
|
412
|
-
npx --yes --package project-tiny-context-harness@latest ty-context export-context --code-index
|
|
413
|
-
```
|
|
414
|
-
|
|
415
|
-
`code-index.md` includes export metadata, repository shape, Context area mapping, entry/API/UI/CLI-worker/test/oversized indexes and a Source File Index with path, type, lines, characters, SHA256, deterministic summary, bundle and tags.
|
|
416
|
-
|
|
417
|
-
`export-context --task-context <name>` creates a focused handoff pack, also capped at 5 files:
|
|
418
|
-
|
|
419
|
-
```sh
|
|
420
|
-
npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context apex-trend-map --profile apex-trend-map
|
|
421
|
-
npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context demo --include-context project_context/areas/main.md --include-code 'src/demo/**'
|
|
422
|
-
```
|
|
423
|
-
|
|
424
|
-
Profiles live in `<harnessRoot>/config.yaml` under `source_packs`; they are export selectors only, not durable facts, and their `verification` entries are listed without being executed. Source Pack modes keep secret redaction enabled across indexes, bundles, task contexts and manifests. `--redaction-strict` exits non-zero if redaction was required, `--max-pack-files` defaults to 5 and cannot exceed 5, and `--prune <count>` is accepted for older scripts while latest-only retention is applied by default.
|
|
425
|
-
|
|
426
|
-
Legacy exports remain for compatibility and full fallback.
|
|
427
|
-
|
|
428
|
-
`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:
|
|
398
|
+
## Temporary Project Exports
|
|
399
|
+
|
|
400
|
+
`export-context --source-pack` is the recommended external LLM / Web GPT planning path:
|
|
401
|
+
|
|
402
|
+
```sh
|
|
403
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack
|
|
404
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack --check
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
It writes `tmp/ty-context/context-exports/latest/` as ordinary files/directories and removes old timestamped export rounds. A standard Source Pack is capped at 5 files: `source-pack-manifest.json`, `full-project-context.md`, `code-index.md`, and at most `code-bundle-core.md` plus `code-bundle-extended.md`; small projects may omit bundles. The `source-pack-v1` manifest uses repo-relative artifact paths and hashes, aggregates warnings and omitted files, and recommends upload sets for daily planning, cross-module review and full fallback.
|
|
408
|
+
|
|
409
|
+
`export-context --code-index` creates the navigation index and manifest without complete source bodies:
|
|
410
|
+
|
|
411
|
+
```sh
|
|
412
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --code-index
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
`code-index.md` includes export metadata, repository shape, Context area mapping, entry/API/UI/CLI-worker/test/oversized indexes and a Source File Index with path, type, lines, characters, SHA256, deterministic summary, bundle and tags.
|
|
416
|
+
|
|
417
|
+
`export-context --task-context <name>` creates a focused handoff pack, also capped at 5 files:
|
|
418
|
+
|
|
419
|
+
```sh
|
|
420
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context apex-trend-map --profile apex-trend-map
|
|
421
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context demo --include-context project_context/areas/main.md --include-code 'src/demo/**'
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
Profiles live in `<harnessRoot>/config.yaml` under `source_packs`; they are export selectors only, not durable facts, and their `verification` entries are listed without being executed. Source Pack modes keep secret redaction enabled across indexes, bundles, task contexts and manifests. `--redaction-strict` exits non-zero if redaction was required, `--max-pack-files` defaults to 5 and cannot exceed 5, and `--prune <count>` is accepted for older scripts while latest-only retention is applied by default.
|
|
425
|
+
|
|
426
|
+
Legacy exports remain for compatibility and full fallback.
|
|
427
|
+
|
|
428
|
+
`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:
|
|
429
429
|
|
|
430
430
|
```sh
|
|
431
431
|
npx --yes --package project-tiny-context-harness@latest ty-context export-context --all
|
|
@@ -456,7 +456,7 @@ npx --yes --package project-tiny-context-harness@latest ty-context export-contex
|
|
|
456
456
|
|
|
457
457
|
The default output is `tmp/ty-context/context-exports/code-level-implementation-<timestamp>/code-level-implementation.md`. The file title is `# Code-Level Implementation Export`. 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.
|
|
458
458
|
|
|
459
|
-
All export modes refuse `project_context/**` and non-temporary output paths. `validate-context` also rejects obvious export artifact names such as `code-level-implementation`, `full-project-context`, legacy Chinese export names, `project-overview`, `context-bundle`, `context-summary` or `context-export` if they are registered in `project_context/context.toml`.
|
|
459
|
+
All export modes refuse `project_context/**` and non-temporary output paths. `validate-context` also rejects obvious export artifact names such as `code-level-implementation`, `full-project-context`, legacy Chinese export names, `project-overview`, `context-bundle`, `context-summary` or `context-export` if they are registered in `project_context/context.toml`.
|
|
460
460
|
|
|
461
461
|
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.
|
|
462
462
|
|
|
@@ -497,7 +497,7 @@ $EDITOR <harnessRoot>/skills/uiux_design/SKILL.md
|
|
|
497
497
|
|
|
498
498
|
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>/ty-context-managed/override_skills/*.md` files should be migrated into standalone project-local Skills before running `sync`.
|
|
499
499
|
|
|
500
|
-
Do not customize the package-managed Surface Contract, Harness upgrade, `/normal-long-task` or `/superpowers-long-task` Skills directly. Project-specific surface responsibilities, upgrade facts and acceptance semantics belong in `project_context/**`; recurring project-local procedures belong in separate project-local Skills.
|
|
500
|
+
Do not customize the package-managed Surface Contract, Harness upgrade, `/normal-long-task` or `/superpowers-long-task` Skills directly. Project-specific surface responsibilities, upgrade facts and acceptance semantics belong in `project_context/**`; recurring project-local procedures belong in separate project-local Skills.
|
|
501
501
|
|
|
502
502
|
## Sync And Upgrade Boundary
|
|
503
503
|
|