project-tiny-context-harness 0.2.60 → 0.2.61
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 +50 -19
- package/assets/README.md +57 -19
- package/assets/agents/AGENTS_CORE.md +8 -5
- package/assets/skills/context_full_project_export/SKILL.md +42 -27
- package/assets/skills/plan_acceptance_checklist_compiler/SKILL.md +99 -58
- package/dist/commands/export-context-args.d.ts +21 -0
- package/dist/commands/export-context-args.js +149 -0
- package/dist/commands/export-context.js +55 -87
- package/dist/commands/index.js +2 -2
- package/dist/lib/source-pack-classify.d.ts +10 -0
- package/dist/lib/source-pack-classify.js +142 -0
- package/dist/lib/source-pack-config.d.ts +7 -0
- package/dist/lib/source-pack-config.js +93 -0
- package/dist/lib/source-pack-export.d.ts +2 -0
- package/dist/lib/source-pack-export.js +223 -0
- package/dist/lib/source-pack-manifest.d.ts +25 -0
- package/dist/lib/source-pack-manifest.js +93 -0
- package/dist/lib/source-pack-records.d.ts +11 -0
- package/dist/lib/source-pack-records.js +161 -0
- package/dist/lib/source-pack-render.d.ts +12 -0
- package/dist/lib/source-pack-render.js +235 -0
- package/dist/lib/source-pack-types.d.ts +77 -0
- package/dist/lib/source-pack-types.js +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -115,7 +115,7 @@ npm ci
|
|
|
115
115
|
npm run smoke:quickstart
|
|
116
116
|
npm run preview:pack
|
|
117
117
|
cd /path/to/your/test-repo
|
|
118
|
-
npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.
|
|
118
|
+
npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.61.tgz
|
|
119
119
|
npx --no-install ty-context init --adopt
|
|
120
120
|
make validate-context
|
|
121
121
|
```
|
|
@@ -227,14 +227,17 @@ Use `npx --no-install ty-context ...` only when you explicitly want the already
|
|
|
227
227
|
| 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. |
|
|
228
228
|
| Development engineer Skill | `<harnessRoot>/skills/context_development_engineer/SKILL.md` | Handles explicit development-engineering requests and writes durable engineering conclusions to `project_context/**`. |
|
|
229
229
|
| 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. |
|
|
230
|
-
| Full project context export Skill | `<harnessRoot>/skills/context_full_project_export/SKILL.md` | Handles explicit full-project or code-level export requests and uses `export-context --all`, `--full` or `--code` to create temporary artifacts under `tmp/ty-context/context-exports/**`. |
|
|
230
|
+
| Full project context export Skill | `<harnessRoot>/skills/context_full_project_export/SKILL.md` | Handles explicit full-project, 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/**`. |
|
|
231
231
|
| 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. |
|
|
232
|
-
| Plan acceptance checklist Skill | `<harnessRoot>/skills/plan_acceptance_checklist_compiler/SKILL.md` | Handles explicit requests to turn a referenced plan, RFC or implementation proposal into a falsifiable acceptance checklist and paste-ready goal/target-mode prompt under `tmp/ty-context/plan-acceptance/**`; generated prompts may
|
|
232
|
+
| Plan acceptance checklist Skill | `<harnessRoot>/skills/plan_acceptance_checklist_compiler/SKILL.md` | Handles explicit requests to turn a referenced plan, RFC or implementation proposal into a falsifiable acceptance checklist and paste-ready goal/target-mode prompt under `tmp/ty-context/plan-acceptance/**`; generated prompts may reference a full checklist as the authoritative acceptance standard and use compact summaries only for navigation/priority, but the Skill does not execute the plan or prove completion. |
|
|
233
233
|
| 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. |
|
|
234
234
|
| 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. |
|
|
235
|
-
| 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. |
|
|
236
|
-
| 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. |
|
|
237
|
-
|
|
|
235
|
+
| 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. |
|
|
236
|
+
| 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. |
|
|
237
|
+
| 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/<timestamp>/` and rewrites `latest/` with upload-ready Context, code index and optional bundles. |
|
|
238
|
+
| 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. |
|
|
239
|
+
| 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. |
|
|
240
|
+
| 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/**`. |
|
|
238
241
|
| 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`. |
|
|
239
242
|
| 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`. |
|
|
240
243
|
| 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. |
|
|
@@ -244,11 +247,11 @@ Use `npx --no-install ty-context ...` only when you explicitly want the already
|
|
|
244
247
|
| Diagnostics | `make ty-context-doctor` or `npx --yes --package project-tiny-context-harness@latest ty-context doctor` | Reports Harness root, package version, schema version and required Minimal Context paths. |
|
|
245
248
|
| Package source checks | `ty-context package sync-source`, `ty-context package check-source` | Maintainer-only commands for keeping package canonical assets aligned with the source workspace. |
|
|
246
249
|
|
|
247
|
-
For high-risk product, UI/UX and engineering tasks that affect durable architecture or module ownership, API/Schema/data contracts, state/runtime behavior, dependency direction, verification/deployment semantics or design-rationale tradeoffs, 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. It can name `Architecture Context Hit` and `Decision Rationale Hit: existing|required|none` so agents explicitly check the controlling Context and rationale state. When module design principles are relevant, the same contract still uses `Applicable Module Design` for the principles, design logic and rationale controlling the current choice. For engineering, RFC and implementation work, the existing Task Contract still includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning without becoming an architecture gate. Ordinary bug fixes, local styling, small refactors, package/release chores, test repairs and spikes are not forced into architecture/rationale ceremony unless they produce durable facts. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, ADR, implementation-document, validator or gate surfaces.
|
|
248
|
-
|
|
249
|
-
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.
|
|
250
|
+
For high-risk product, UI/UX and engineering tasks that affect durable architecture or module ownership, API/Schema/data contracts, state/runtime behavior, dependency direction, verification/deployment semantics or design-rationale tradeoffs, 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. It can name `Architecture Context Hit` and `Decision Rationale Hit: existing|required|none` so agents explicitly check the controlling Context and rationale state. When module design principles are relevant, the same contract still uses `Applicable Module Design` for the principles, design logic and rationale controlling the current choice. For engineering, RFC and implementation work, the existing Task Contract still includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning without becoming an architecture gate. Ordinary bug fixes, local styling, small refactors, package/release chores, test repairs and spikes are not forced into architecture/rationale ceremony unless they produce durable facts. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, ADR, implementation-document, validator or gate surfaces.
|
|
251
|
+
|
|
252
|
+
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.
|
|
250
253
|
|
|
251
|
-
For long-running plans, RFCs or implementation proposals, the plan acceptance checklist Skill can turn a plan plus relevant Context into a falsifiable acceptance checklist and a paste-ready 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.
|
|
254
|
+
For long-running plans, RFCs or implementation proposals, the plan acceptance checklist Skill can turn a plan plus relevant Context into a falsifiable acceptance checklist and a paste-ready 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.
|
|
252
255
|
|
|
253
256
|
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.
|
|
254
257
|
|
|
@@ -312,7 +315,7 @@ Managed `AGENTS.md` guidance is intentionally a startup router, not a full manua
|
|
|
312
315
|
- project goal
|
|
313
316
|
- non-goals / boundaries
|
|
314
317
|
- background
|
|
315
|
-
- project-wide design rationale, including rejected alternatives and tradeoffs that still matter
|
|
318
|
+
- project-wide design rationale, including rejected alternatives and tradeoffs that still matter
|
|
316
319
|
- architecture context link
|
|
317
320
|
- product / delivery brief
|
|
318
321
|
- UX / screen brief
|
|
@@ -326,7 +329,7 @@ Managed `AGENTS.md` guidance is intentionally a startup router, not a full manua
|
|
|
326
329
|
- system boundary
|
|
327
330
|
- component map
|
|
328
331
|
- data / control flow
|
|
329
|
-
- architecture-level design rationale, rejected alternatives and tradeoffs
|
|
332
|
+
- architecture-level design rationale, rejected alternatives and tradeoffs
|
|
330
333
|
- constraints and tradeoffs
|
|
331
334
|
- verification implications
|
|
332
335
|
- open risks
|
|
@@ -344,9 +347,9 @@ Managed `AGENTS.md` guidance is intentionally a startup router, not a full manua
|
|
|
344
347
|
- related role context pointers
|
|
345
348
|
- open risks
|
|
346
349
|
|
|
347
|
-
A module design capsule should stay small and decision-shaped: `Principles` are stable execution constraints, `Design Logic` is the minimum choose/reject/degrade/compose logic, and `Design Rationale` keeps only reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions. Current thresholds, commands and probe parameters belong in the relevant contract or verification Context as execution instances, not as permanent principles.
|
|
348
|
-
|
|
349
|
-
Use the smallest durable rationale surface: project-wide tradeoffs in `global.md#Design Rationale`, architecture choices in `architecture.md#Design Rationale`, module reasons in an area Module Design Capsule, cross-domain interface rationale in `contract` role Context, larger cross-cutting reasons in `decision-rationale`, and visual identity or token rationale in `DESIGN.md`. Do not record implementation summaries, PR notes, command output, test-passed claims, screenshot review notes, debug history, agent reasoning or rationale inferred only from current code shape.
|
|
350
|
+
A module design capsule should stay small and decision-shaped: `Principles` are stable execution constraints, `Design Logic` is the minimum choose/reject/degrade/compose logic, and `Design Rationale` keeps only reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions. Current thresholds, commands and probe parameters belong in the relevant contract or verification Context as execution instances, not as permanent principles.
|
|
351
|
+
|
|
352
|
+
Use the smallest durable rationale surface: project-wide tradeoffs in `global.md#Design Rationale`, architecture choices in `architecture.md#Design Rationale`, module reasons in an area Module Design Capsule, cross-domain interface rationale in `contract` role Context, larger cross-cutting reasons in `decision-rationale`, and visual identity or token rationale in `DESIGN.md`. Do not record implementation summaries, PR notes, command output, test-passed claims, screenshot review notes, debug history, agent reasoning or rationale inferred only from current code shape.
|
|
350
353
|
|
|
351
354
|
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`.
|
|
352
355
|
|
|
@@ -358,9 +361,37 @@ When authoring, migrating or cleaning up `project_context/areas/**`, run a soft
|
|
|
358
361
|
|
|
359
362
|
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.
|
|
360
363
|
|
|
361
|
-
## Temporary Project Exports
|
|
362
|
-
|
|
363
|
-
`export-context --
|
|
364
|
+
## Temporary Project Exports
|
|
365
|
+
|
|
366
|
+
`export-context --source-pack` is the recommended external LLM / Web GPT planning path:
|
|
367
|
+
|
|
368
|
+
```sh
|
|
369
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack
|
|
370
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack --check
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
It writes `tmp/ty-context/context-exports/<timestamp>/` and rewrites `tmp/ty-context/context-exports/latest/` as ordinary files/directories. 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.
|
|
374
|
+
|
|
375
|
+
`export-context --code-index` creates the navigation index and manifest without complete source bodies:
|
|
376
|
+
|
|
377
|
+
```sh
|
|
378
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --code-index
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
`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.
|
|
382
|
+
|
|
383
|
+
`export-context --task-context <name>` creates a focused handoff pack, also capped at 5 files:
|
|
384
|
+
|
|
385
|
+
```sh
|
|
386
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context apex-trend-map --profile apex-trend-map
|
|
387
|
+
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/**'
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
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>` keeps `latest/` while removing older timestamped rounds beyond the requested retention count.
|
|
391
|
+
|
|
392
|
+
Legacy exports remain for compatibility and full fallback.
|
|
393
|
+
|
|
394
|
+
`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:
|
|
364
395
|
|
|
365
396
|
```sh
|
|
366
397
|
npx --yes --package project-tiny-context-harness@latest ty-context export-context --all
|
|
@@ -391,7 +422,7 @@ npx --yes --package project-tiny-context-harness@latest ty-context export-contex
|
|
|
391
422
|
|
|
392
423
|
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.
|
|
393
424
|
|
|
394
|
-
|
|
425
|
+
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`.
|
|
395
426
|
|
|
396
427
|
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.
|
|
397
428
|
|
package/assets/README.md
CHANGED
|
@@ -94,7 +94,7 @@ That smoke packs the local workspace, installs it into a disposable repo, runs `
|
|
|
94
94
|
```sh
|
|
95
95
|
npm run preview:pack
|
|
96
96
|
cd /path/to/your/test-repo
|
|
97
|
-
npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.
|
|
97
|
+
npm install -D /path/to/project-tiny-context-harness/tmp/ty-context/source-preview/package/project-tiny-context-harness-0.2.61.tgz
|
|
98
98
|
npx --no-install ty-context init --adopt
|
|
99
99
|
make validate-context
|
|
100
100
|
```
|
|
@@ -266,15 +266,15 @@ No. It checks that recovery facts exist and avoids fake test-result claims. Prod
|
|
|
266
266
|
|
|
267
267
|
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.
|
|
268
268
|
|
|
269
|
-
The default Skills are Minimal Context helpers for explicit product-planning, UI/UX-design, development-engineering, Product Surface Contract, full-project-export, Tiny Context upgrade and plan-acceptance-checklist requests. Product, screen-flow, surface responsibility and durable engineering conclusions go to `project_context/**`; visual identity and design tokens go to root `DESIGN.md`. Export artifacts are temporary files under `tmp/ty-context/context-exports/**`, not Context. Plan acceptance artifacts are temporary files under `tmp/ty-context/plan-acceptance/**`; they define completion criteria for a referenced plan but do not execute it or prove acceptance. The Harness upgrade Skill handles requests such as “upgrade Tiny Context” and “use the Tiny Context upgrade skill to upgrade this project” by following the release update mode, using `upgrade` for migration-bearing releases, and limiting manual cleanup to migration-scoped follow-up.
|
|
269
|
+
The default Skills are Minimal Context helpers for explicit product-planning, UI/UX-design, development-engineering, Product Surface Contract, full-project-export, Tiny Context upgrade and plan-acceptance-checklist requests. Product, screen-flow, surface responsibility and durable engineering conclusions go to `project_context/**`; visual identity and design tokens go to root `DESIGN.md`. Export artifacts are temporary files under `tmp/ty-context/context-exports/**`, not Context. Plan acceptance artifacts are temporary files under `tmp/ty-context/plan-acceptance/**`; they define completion criteria for a referenced plan but do not execute it or prove acceptance. When a generated prompt references a full checklist, that checklist is the authoritative acceptance standard; the compact prompt summary is only navigation and priority guidance. The Harness upgrade Skill handles requests such as “upgrade Tiny Context” and “use the Tiny Context upgrade skill to upgrade this project” by following the release update mode, using `upgrade` for migration-bearing releases, and limiting manual cleanup to migration-scoped follow-up.
|
|
270
270
|
|
|
271
271
|
Multilingual trigger phrases are compatibility details. Public README, npm and launch copy stay English-first, and public/package-managed surfaces must remain English-complete; literal non-English examples are documented only where they explain generated Skill matching and must not be the sole activation path.
|
|
272
272
|
|
|
273
|
-
For high-risk product, UI/UX and engineering tasks that affect durable architecture or module ownership, API/Schema/data contracts, state/runtime behavior, dependency direction, verification/deployment semantics or design-rationale tradeoffs, 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. It can name `Architecture Context Hit` and `Decision Rationale Hit: existing|required|none` so agents explicitly check the controlling Context and rationale state. When module design principles are relevant, the same contract still uses `Applicable Module Design` for the principles, design logic and rationale controlling the current choice. For engineering, RFC and implementation work, the existing Task Contract still includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning without becoming an architecture gate. Ordinary bug fixes, local styling, small refactors, package/release chores, test repairs and spikes are not forced into architecture/rationale ceremony unless they produce durable facts. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, ADR, implementation-document, validator or gate surfaces.
|
|
274
|
-
|
|
275
|
-
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.
|
|
273
|
+
For high-risk product, UI/UX and engineering tasks that affect durable architecture or module ownership, API/Schema/data contracts, state/runtime behavior, dependency direction, verification/deployment semantics or design-rationale tradeoffs, 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. It can name `Architecture Context Hit` and `Decision Rationale Hit: existing|required|none` so agents explicitly check the controlling Context and rationale state. When module design principles are relevant, the same contract still uses `Applicable Module Design` for the principles, design logic and rationale controlling the current choice. For engineering, RFC and implementation work, the existing Task Contract still includes `Modularity Check: none|required|exception` so oversized touched files trigger split-or-exception reasoning without becoming an architecture gate. Ordinary bug fixes, local styling, small refactors, package/release chores, test repairs and spikes are not forced into architecture/rationale ceremony unless they produce durable facts. The task contract and Contract Conformance are handoff evidence, not new PRD, tech-plan, ADR, implementation-document, validator or gate surfaces.
|
|
274
|
+
|
|
275
|
+
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.
|
|
276
276
|
|
|
277
|
-
For long-running plans, RFCs or implementation proposals, the plan acceptance checklist compiler can turn a plan plus relevant Context into a falsifiable acceptance checklist and a paste-ready goal/target-mode prompt. This 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.
|
|
277
|
+
For long-running plans, RFCs or implementation proposals, the plan acceptance checklist compiler can turn a plan plus relevant Context into a falsifiable acceptance checklist and a paste-ready goal/target-mode prompt. This 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. The full checklist is the acceptance authority, while any compact prompt summary exists for navigation, priority and recovery after context compaction.
|
|
278
278
|
|
|
279
279
|
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.
|
|
280
280
|
|
|
@@ -342,10 +342,13 @@ Use `npx --no-install ty-context ...` only when you explicitly want the already
|
|
|
342
342
|
| `npx --yes --package project-tiny-context-harness@latest ty-context init` | Non-destructively installs Minimal Context Harness into the current project. |
|
|
343
343
|
| `make ty-context-sync` or `npx --yes --package project-tiny-context-harness@latest ty-context sync` | Refreshes managed guidance, default Skills, Makefile include, tools and templates. It does not run migrations or generate project semantics; it may block only direct asset-refresh safety issues such as invalid managed blocks or deprecated managed Skill overrides. |
|
|
344
344
|
| `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. |
|
|
345
|
-
| `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. |
|
|
346
|
-
| `npx --yes --package project-tiny-context-harness@latest ty-context export-context --
|
|
347
|
-
| `npx --yes --package project-tiny-context-harness@latest ty-context export-context --
|
|
348
|
-
| `npx --yes --package project-tiny-context-harness@latest ty-context export-context --
|
|
345
|
+
| `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. |
|
|
346
|
+
| `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/<timestamp>/` and rewrites `latest/` with upload-ready Context, code index and optional bundles. |
|
|
347
|
+
| `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code-index [--check]` | Creates a temporary implementation navigation index and manifest without full source bodies. |
|
|
348
|
+
| `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. |
|
|
349
|
+
| `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/**`. |
|
|
350
|
+
| `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 project Context summary Markdown artifact. |
|
|
351
|
+
| `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 Markdown artifact. |
|
|
349
352
|
| `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. |
|
|
350
353
|
| `npx --yes --package project-tiny-context-harness@latest ty-context validate-context` | Checks minimum project recovery fields, Context graph metadata, declared paths/roles and fake test-execution claims. |
|
|
351
354
|
| `make validate-context` | Makefile wrapper for `validate-context`. |
|
|
@@ -404,7 +407,7 @@ Examples:
|
|
|
404
407
|
- project goal
|
|
405
408
|
- non-goals / boundaries
|
|
406
409
|
- background
|
|
407
|
-
- project-wide design rationale, including former ADR-level decisions, rejected alternatives and tradeoffs that still matter
|
|
410
|
+
- project-wide design rationale, including former ADR-level decisions, rejected alternatives and tradeoffs that still matter
|
|
408
411
|
- architecture context link
|
|
409
412
|
- product / delivery brief for durable product goals, users, flows and acceptance signals
|
|
410
413
|
- UX / screen brief for durable screen, interaction, responsive and accessibility facts
|
|
@@ -418,7 +421,7 @@ Examples:
|
|
|
418
421
|
- system boundary
|
|
419
422
|
- component map
|
|
420
423
|
- data / control flow
|
|
421
|
-
- architecture-level design rationale, rejected alternatives and tradeoffs
|
|
424
|
+
- architecture-level design rationale, rejected alternatives and tradeoffs
|
|
422
425
|
- constraints and tradeoffs
|
|
423
426
|
- verification implications
|
|
424
427
|
- open risks
|
|
@@ -436,9 +439,9 @@ Examples:
|
|
|
436
439
|
- related role context pointers
|
|
437
440
|
- open risks
|
|
438
441
|
|
|
439
|
-
A module design capsule should stay small and decision-shaped: `Principles` are stable execution constraints, `Design Logic` is the minimum choose/reject/degrade/compose logic, and `Design Rationale` keeps only reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions. Current thresholds, commands and probe parameters belong in the relevant contract or verification Context as execution instances, not as permanent principles.
|
|
440
|
-
|
|
441
|
-
Use the smallest durable rationale surface: project-wide tradeoffs in `global.md#Design Rationale`, architecture choices in `architecture.md#Design Rationale`, module reasons in an area Module Design Capsule, cross-domain interface rationale in `contract` role Context, larger cross-cutting reasons in `decision-rationale`, and visual identity or token rationale in `DESIGN.md`. Do not record implementation summaries, PR notes, command output, test-passed claims, screenshot review notes, debug history, agent reasoning or rationale inferred only from current code shape.
|
|
442
|
+
A module design capsule should stay small and decision-shaped: `Principles` are stable execution constraints, `Design Logic` is the minimum choose/reject/degrade/compose logic, and `Design Rationale` keeps only reasons, rejected alternatives and tradeoffs that change later implementation or verification decisions. Current thresholds, commands and probe parameters belong in the relevant contract or verification Context as execution instances, not as permanent principles.
|
|
443
|
+
|
|
444
|
+
Use the smallest durable rationale surface: project-wide tradeoffs in `global.md#Design Rationale`, architecture choices in `architecture.md#Design Rationale`, module reasons in an area Module Design Capsule, cross-domain interface rationale in `contract` role Context, larger cross-cutting reasons in `decision-rationale`, and visual identity or token rationale in `DESIGN.md`. Do not record implementation summaries, PR notes, command output, test-passed claims, screenshot review notes, debug history, agent reasoning or rationale inferred only from current code shape.
|
|
442
445
|
|
|
443
446
|
Additional Markdown context files under `project_context/**` can declare `context_role` in front matter or receive a role from `context.toml`. Roles are semantic labels that help agents choose when and how to read context; `validate-context` checks graph structure, paths and field shapes rather than enforcing a writing template for each role:
|
|
444
447
|
|
|
@@ -463,9 +466,44 @@ When authoring, migrating or cleaning up `project_context/areas/**`, run a soft
|
|
|
463
466
|
|
|
464
467
|
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.
|
|
465
468
|
|
|
466
|
-
## Temporary Project Exports
|
|
467
|
-
|
|
468
|
-
Use `export-context --
|
|
469
|
+
## Temporary Project Exports
|
|
470
|
+
|
|
471
|
+
Use `export-context --source-pack` as the default external LLM / Web GPT planning path:
|
|
472
|
+
|
|
473
|
+
```sh
|
|
474
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack
|
|
475
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack --check
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
This writes a timestamped directory and rewrites `tmp/ty-context/context-exports/latest/` as ordinary files/directories for Windows compatibility. 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 bundle files. The manifest schema is `source-pack-v1`, uses repo-relative artifact paths and hashes, records warnings/omitted files, and recommends upload sets.
|
|
479
|
+
|
|
480
|
+
Recommended upload sets:
|
|
481
|
+
|
|
482
|
+
- Daily planning: `full-project-context.md`, `code-index.md`.
|
|
483
|
+
- Cross-module review: daily planning files plus `code-bundle-core.md` and, if needed, `code-bundle-extended.md`.
|
|
484
|
+
- Focused task handoff: `full-project-context.md`, `code-index.md`, `task-contexts/task-context-<name>.md`.
|
|
485
|
+
- Full fallback: daily planning files plus legacy `code-level-implementation.md` from `--code`.
|
|
486
|
+
|
|
487
|
+
Use `export-context --code-index` when implementation navigation is enough and full source bodies are not needed:
|
|
488
|
+
|
|
489
|
+
```sh
|
|
490
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --code-index
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
`code-index.md` includes export metadata, repository shape, Context 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. It does not include complete source bodies.
|
|
494
|
+
|
|
495
|
+
Use `export-context --task-context <name>` for focused handoff. 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:
|
|
496
|
+
|
|
497
|
+
```sh
|
|
498
|
+
npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context apex-trend-map --profile apex-trend-map
|
|
499
|
+
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/**'
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
Source Pack modes always keep secret redaction enabled. `--redaction-strict` exits non-zero if any secret/token/cookie/password/api_key/credential/bearer/authorization assignment required redaction. `--max-pack-files` defaults to 5 and cannot exceed 5 for Source Pack or task packs. `--prune <count>` keeps `latest/` and removes old timestamped export rounds beyond the requested retention count.
|
|
503
|
+
|
|
504
|
+
Legacy exports remain for compatibility and full fallback.
|
|
505
|
+
|
|
506
|
+
Use `export-context --all` when you want both one-off project exports for copying into an external tool or discussion:
|
|
469
507
|
|
|
470
508
|
```sh
|
|
471
509
|
npx --yes --package project-tiny-context-harness@latest ty-context export-context --all
|
|
@@ -494,7 +532,7 @@ npx --yes --package project-tiny-context-harness@latest ty-context export-contex
|
|
|
494
532
|
|
|
495
533
|
The default code artifact path 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.
|
|
496
534
|
|
|
497
|
-
|
|
535
|
+
All export modes exclude `.env*` except safe examples such as `.env.example`, secret/token/cookie-oriented files, raw captures, licensed payload dumps, `node_modules`, build output, caches, coverage, test reports, logs and existing export artifacts; obvious sensitive assignment values are redacted and reported as warnings.
|
|
498
536
|
|
|
499
537
|
Exports are not long-lived fact sources. The CLI refuses `project_context/**` and non-temporary output paths, and `validate-context` 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 someone tries to register them in `project_context/context.toml`.
|
|
500
538
|
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
1. 先读 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`,再按 graph 读取相关 area / context unit。
|
|
14
14
|
2. 若任务涉及 Product Surface work(Web UI、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面)、前端布局、UI/UX、产品模块边界或信息放置,先做产品/页面定位检查;若改变 durable surface responsibility、主层/下钻归属、长任务状态或信息架构,使用 `context_surface_contract` Skill 应用 Surface Contract workflow:`project_context/**` 是 durable surface truth,repo-local Skills 可强制项目 task block,`DESIGN.md` 只放视觉 token/rationale,代码/截图只是实现证据;不新增 surface-specific context role,跨 surface 用现有 `contract` role。
|
|
15
15
|
3. 若任务新增、迁移或整理 Context 文件,先做 role placement scan:area 只代表产品域归属;contract / foundation / subdomain / verification / deployment / implementation-index / decision-rationale 等按读取目的拆成 role Context。
|
|
16
|
-
4. 对影响架构边界、模块 ownership、API / Schema / 数据契约、状态或运行语义、依赖方向、验证 / 部署语义或 durable rationale / tradeoff 的高风险产品、UI/UX、系统设计和工程任务,先把相关 Context 编译进当前任务契约;契约第一段用 `Context Delta: none|required` 作为唯一长期事实判断点,并包含 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none`;工程 / RFC / 实现类 Task Contract 同时包含 `Modularity Check: none|required|exception`。
|
|
16
|
+
4. 对影响架构边界、模块 ownership、API / Schema / 数据契约、状态或运行语义、依赖方向、验证 / 部署语义或 durable rationale / tradeoff 的高风险产品、UI/UX、系统设计和工程任务,先把相关 Context 编译进当前任务契约;契约第一段用 `Context Delta: none|required` 作为唯一长期事实判断点,并包含 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none`;工程 / RFC / 实现类 Task Contract 同时包含 `Modularity Check: none|required|exception`。
|
|
17
17
|
5. `Context Delta: required` 则 context-first;普通 bug fix、局部样式、局部漂移修复、测试修复或 spike 默认 code-first,但一旦产生长期结论必须回写 Context。
|
|
18
18
|
6. 收尾做 Contract Conformance 和 Context drift check,只报告 `Context: 已更新 ...` 或 `Context: 本次无长期事实变化`;不要把一次性证据、任务契约或实现摘要写入 Context。
|
|
19
19
|
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
|
|
30
30
|
1. 新会话或继续工作时,先读取 `project_context/global.md`、`project_context/architecture.md` 和 `project_context/context.toml`;按其中 default area 和触发条件读取相关 context。
|
|
31
31
|
2. 第一处代码编辑前先做轻量变更分类,不按固定时长计时。若任务涉及 Product Surface work(Web UI、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面)、前端布局、UI/UX、产品模块边界或信息应该放在哪个 surface / 页面 / 模块,先做产品/页面定位检查,再完成变更分类:用户在这个 surface 要完成什么判断,产品必须提供哪些信息 / 动作 / 反馈,哪些信息不应常驻,哪些属于主层、下钻、运维、诊断、详情或其他页面,当前布局和信息密度是否匹配 surface 任务。若 UI 改动涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态,按产品/UIUX Skill 的控件任务框架做轻量检查,识别既有 Context 或 Product Surface Contract 是否适用以及是否缺少长期 surface/控件契约;职责不清或需要治理时使用 `context_surface_contract`。多 surface、多页面或多模块归属不清时,先审查相关信息架构,再收窄到代码模块实现。该检查是判断是否需要 context-first 的输入,不等于必须更新 Context,也不要求独立文档、新角色或新的 gate。
|
|
32
|
-
3. 对产品方案、UI/UX、系统设计、架构边界、模块 ownership、API / Schema / 数据契约、状态机或运行语义、依赖方向、验证 / 部署语义或 durable rationale / tradeoff 等高风险任务,第一处代码编辑前先编译当前任务契约:用 `Context Delta: none|required` 作为唯一正式长期事实判断点,再写本次 Task Contract,并把 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none`、命中的模块设计上下文、它控制的当前选择、首选路径和 fallback / degraded path 条件写入任务契约;工程 / RFC / 实现类 Task Contract 还应包含 `Modularity Check: none|required|exception`。普通 bug fix、局部样式、小重构、局部漂移修复、package/release 处理、测试修复或 spike 不强制编译任务契约。
|
|
32
|
+
3. 对产品方案、UI/UX、系统设计、架构边界、模块 ownership、API / Schema / 数据契约、状态机或运行语义、依赖方向、验证 / 部署语义或 durable rationale / tradeoff 等高风险任务,第一处代码编辑前先编译当前任务契约:用 `Context Delta: none|required` 作为唯一正式长期事实判断点,再写本次 Task Contract,并把 `Architecture Context Hit`、`Decision Rationale Hit: existing|required|none`、命中的模块设计上下文、它控制的当前选择、首选路径和 fallback / degraded path 条件写入任务契约;工程 / RFC / 实现类 Task Contract 还应包含 `Modularity Check: none|required|exception`。普通 bug fix、局部样式、小重构、局部漂移修复、package/release 处理、测试修复或 spike 不强制编译任务契约。
|
|
33
33
|
4. 当新增、迁移或整理 `project_context/areas/**` 时,做 role placement scan(软约束,不做 gate):`area` / `domain` 保留产品域归属,`subdomain` 用于产品域内较小 ownership,`contract` 用于 API / schema / event / 跨域接口语义,`foundation` 用于稳定理论 / 词汇 / 背景材料,`verification` / `deployment` 用于可复用执行路径,`implementation-index` 只做代码导航索引,`decision-rationale` 记录稳定设计原因,`archive` 用于非默认读取的历史或外部材料。
|
|
34
34
|
5. 若任务契约声明 `Context Delta: required`,默认走 context-first:第一处代码编辑前先更新相关 `project_context/**`,写入必要且足以指导实现的长期结论,再按 Context 和 Task Contract 对齐实现、验证和收尾。
|
|
35
35
|
6. 普通 bug fix、局部样式、局部实现漂移修复、测试修复或探索性 spike 不更新 Context,可先改代码;一旦形成长期结论,继续对齐或交付前必须回写 `project_context/**`。
|
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
9. 每个有意义的方案或实现变更收尾时做 Contract Conformance 和 Context drift check:对照 Task Contract 区分实现偏差、契约遗漏或长期事实缺失;实现偏差修实现,契约遗漏回 Task Contract,长期事实缺失回 `Context Delta` 并先更新 Context。交付说明只报告轻量状态:`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`;Conformance 证据属于本次交付,不写入 `project_context/**`。
|
|
39
39
|
10. 长期事实只写入 `project_context/**`;不要默认创建 PRD、tech plan、ADR、implementation doc、review/test/release 文档。
|
|
40
40
|
11. 用户明确要求“产品方案 / 产品经理 / 产品专家 / product plan / product manager / product spec”、“设计稿 / UI/UX 设计方案 / 视觉专家 / UX designer / UI designer / visual polish / design system spec”或“开发工程师 / 技术方案 / 开发方案 / 实现 / 实现方案 / 实施计划 / 技术专家 / software engineer / development plan / technical implementation plan / 多开agent / subagent”这类角色或强产物名时,使用对应 Context authoring Skill,把长期结论写回 `project_context/**`。
|
|
41
|
-
12. 用户明确要求“导出尽可能详细的项目全量上下文 / 全量上下文导出 / full project context export / export full project context / 当前项目代码实现 / 代码级实现导出 / code-level implementation export”时,使用 `context_full_project_export` Skill;默认优先运行 `ty-context export-context --
|
|
41
|
+
12. 用户明确要求“导出尽可能详细的项目全量上下文 / 全量上下文导出 / full project context export / export full project context / project context export / 当前项目代码实现 / 代码级实现导出 / code-level implementation export / Source Pack export / source-pack export / task context export / code index export”时,使用 `context_full_project_export` Skill;默认优先运行 `ty-context export-context --source-pack` 生成最多 5 个临时上传文件;只需要导航索引用 `--code-index`,聚焦交接用 `--task-context <name>`,需要 legacy 单文件完整代码快照时再用 `--code`,需要 legacy Context+代码双导出时可用 `--all`;导出产物只放 `tmp/ty-context/context-exports/**`,不得放入或注册到 `project_context/**` / `project_context/context.toml`。用户明确要求“upgrade Tiny Context / update Tiny Context / Project Tiny Context Harness upgrade / 用 Tiny Context upgrade skill 升级这个项目 / 升级 tiny context”时,使用 `context_harness_upgrade` Skill,先走 `upgrade`,不要先单独运行 `sync`。
|
|
42
42
|
13. 用户提供或引用某份方案 / 计划 / RFC / implementation plan / milestone plan,并明确要求生成验收清单、完成定义、goal-mode prompt 或 target-mode prompt 时,使用 `plan_acceptance_checklist_compiler` Skill;输出只放 `tmp/ty-context/plan-acceptance/**`,它只定义验收标准,不执行计划、不证明完成、不把结果注册到 `project_context/**` / `project_context/context.toml`。
|
|
43
43
|
14. 当任务涉及设计稿、重做设计、视觉方案、设计系统、visual polish、frontend redesign 或 frontend styling,且存在可扫描的 UI 代码、页面文件、构建产物目录或本地/远程 URL 时,默认运行 `npx impeccable detect <target>` 做 Impeccable 视觉审查;没有可扫描目标、命令不可用或扫描失败时,说明原因并继续。Impeccable 不是 `validate-context` gate,也不替代截图检查、项目测试或人工判断。
|
|
44
44
|
15. Tiny Context / Harness managed surfaces 是生成资产:`AGENTS.md` managed block、`.agent/ty-context-managed/**`、`.agent/skills/context_product_plan/**`、`.agent/skills/context_uiux_design/**`、`.agent/skills/context_development_engineer/**`、`.agent/skills/context_surface_contract/**`、`.agent/skills/context_full_project_export/**`、`.agent/skills/context_harness_upgrade/**` 和 `.agent/skills/plan_acceptance_checklist_compiler/**` 禁止承载项目特定规则;直接编辑会在 `sync` 时被覆盖或产生漂移。项目本地产品 / UIUX / 开发 / surface contract 规则必须新建独立 Skill,例如 `.agent/skills/product_plan/SKILL.md`、`.agent/skills/uiux_design/SKILL.md`、`.agent/skills/development_engineer/SKILL.md` 或 `.agent/skills/surface_contract/SKILL.md`;当项目本地 Skill 与默认 Skill 同时适用时,优先使用更具体的项目本地 Skill。项目本地 Skill 的 front matter `description` 触发词应与本文件中的角色触发规则和对应默认 `context_*` Skill 保持一致;新增或收窄关键词时,同步更新本地 Skill 描述和项目级 agent 指引,避免 Skill 触发条件与 Tiny Context 工作规则漂移。
|
|
@@ -52,8 +52,11 @@
|
|
|
52
52
|
## 常用命令
|
|
53
53
|
|
|
54
54
|
- `make validate-context`:检查 `project_context/**` 是否足够支持 agent 恢复上下文。
|
|
55
|
-
- `make ty-context-sync`:刷新 managed guidance、Context template、默认 Skill 和工具。
|
|
56
|
-
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --
|
|
55
|
+
- `make ty-context-sync`:刷新 managed guidance、Context template、默认 Skill 和工具。
|
|
56
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack`:导出最多 5 个临时 Source Pack 上传文件到 `tmp/ty-context/context-exports/**`,并刷新 `latest/`。
|
|
57
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code-index`:导出不含完整源码正文的临时代码索引和 manifest。
|
|
58
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context <name>`:导出最多 5 个临时聚焦任务交接文件。
|
|
59
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all`:同时导出临时项目级 Context 汇总和代码级实现 Markdown 到 `tmp/ty-context/context-exports/**`。
|
|
57
60
|
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full`:导出临时项目级 Context 汇总 Markdown 到 `tmp/ty-context/context-exports/**`。
|
|
58
61
|
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code`:导出临时代码级实现 Markdown 到 `tmp/ty-context/context-exports/**`。
|
|
59
62
|
- `npx --yes --package project-tiny-context-harness@latest ty-context doctor`:临时诊断 canonical Tiny Context CLI;避免裸 `npx ty-context` 解析到旧包名或旧本地缓存。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: context_full_project_export
|
|
3
|
-
description: Use when the user explicitly asks to 导出尽可能详细的项目全量上下文, 全量上下文导出, 项目上下文全量导出, full project context export, export full project context, project context export, 当前项目代码实现, 代码级实现导出, or code-level implementation export in a Minimal Context Harness project.
|
|
2
|
+
name: context_full_project_export
|
|
3
|
+
description: Use when the user explicitly asks to 导出尽可能详细的项目全量上下文, 全量上下文导出, 项目上下文全量导出, full project context export, export full project context, project context export, Source Pack export, source-pack export, code index export, task context export, 当前项目代码实现, 代码级实现导出, or code-level implementation export in a Minimal Context Harness project.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Context Full Project Export
|
|
@@ -13,40 +13,55 @@ This Skill creates a temporary export artifact only. It does not author durable
|
|
|
13
13
|
|
|
14
14
|
## Purpose
|
|
15
15
|
|
|
16
|
-
When the user needs a full project context export, create
|
|
17
|
-
|
|
18
|
-
When the user needs a code-level implementation export, create one temporary Markdown snapshot of current source and engineering configuration files for upload to Web GPT or another external model.
|
|
19
|
-
|
|
20
|
-
## Workflow
|
|
21
|
-
|
|
22
|
-
1. Prefer the
|
|
23
|
-
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --
|
|
24
|
-
2. Use `--
|
|
25
|
-
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --
|
|
26
|
-
3. Use `--
|
|
27
|
-
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --
|
|
31
|
-
5. Use
|
|
32
|
-
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --
|
|
33
|
-
|
|
34
|
-
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code
|
|
35
|
-
|
|
16
|
+
When the user needs a full project context export or external LLM handoff, create temporary export artifacts that collect project Context, key agent guidance, architecture/module facts, code navigation and bounded source support for copying into an external tool or one-off discussion.
|
|
17
|
+
|
|
18
|
+
When the user needs a code-level implementation export, create one temporary Markdown snapshot of current source and engineering configuration files for upload to Web GPT or another external model.
|
|
19
|
+
|
|
20
|
+
## Workflow
|
|
21
|
+
|
|
22
|
+
1. Prefer the bounded Source Pack for external LLM / Web GPT planning. It writes at most 5 files plus a manifest under `tmp/ty-context/context-exports/<timestamp>/` and rewrites `latest/`:
|
|
23
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack`
|
|
24
|
+
2. Use `--code-index` when implementation navigation is enough and full source bodies are not needed:
|
|
25
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code-index`
|
|
26
|
+
3. Use `--task-context <name>` for focused handoff, preferably with a profile or explicit include selectors:
|
|
27
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context <name> --profile <profile-id>`
|
|
28
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context <name> --include-context project_context/areas/main.md --include-code 'src/example/**'`
|
|
29
|
+
4. Use legacy `--all` when the user explicitly wants both old temporary artifacts in one command. Do not hand-write tracked export documents:
|
|
30
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all`
|
|
31
|
+
5. Use legacy `--full` when only the project Context bundle is needed:
|
|
32
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full`
|
|
33
|
+
6. Use legacy `--code` when only the full code-level implementation snapshot is needed. It generates one Markdown file by default and is the full fallback when Source Pack bundles are not enough:
|
|
34
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code`
|
|
35
|
+
7. Custom output paths are allowed only for legacy single-artifact modes and must stay under the temporary export directory. `--all` and Source Pack modes do not accept `--output`:
|
|
36
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full --output tmp/ty-context/context-exports/my-export.md`
|
|
37
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code --output tmp/ty-context/context-exports/my-code-export.md`
|
|
38
|
+
8. Use dry-run mode to inspect planned sources before writing:
|
|
39
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --source-pack --check`
|
|
40
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code-index --check`
|
|
41
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --task-context <name> --check`
|
|
42
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --all --check`
|
|
43
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --full --check`
|
|
44
|
+
- `npx --yes --package project-tiny-context-harness@latest ty-context export-context --code --check`
|
|
45
|
+
9. After exporting, report artifact paths, source counts, recommended upload sets and warnings to the user. Do not summarize export contents back into Context.
|
|
36
46
|
|
|
37
47
|
## Output Boundaries
|
|
38
48
|
|
|
39
|
-
- Export artifacts must remain temporary export artifacts, not Context.
|
|
40
|
-
- `--
|
|
41
|
-
- `--
|
|
49
|
+
- Export artifacts must remain temporary export artifacts, not Context.
|
|
50
|
+
- `--source-pack` defaults to `tmp/ty-context/context-exports/<timestamp>/` and `latest/`, with `source-pack-manifest.json`, `full-project-context.md`, `code-index.md` and optional `code-bundle-core.md` / `code-bundle-extended.md`.
|
|
51
|
+
- `--source-pack` and `--task-context` are capped at 5 output files. `--max-pack-files` cannot exceed 5.
|
|
52
|
+
- `--code-index` creates a navigation index and manifest without complete source bodies.
|
|
53
|
+
- `--task-context <name>` creates `task-contexts/task-context-<name>.md` plus optional support bundle; profile verification entries are listed, not executed.
|
|
54
|
+
- `--full` defaults to `tmp/ty-context/context-exports/full-project-context-<timestamp>.md`.
|
|
55
|
+
- `--code` defaults to `tmp/ty-context/context-exports/code-level-implementation-<timestamp>/code-level-implementation.md`.
|
|
42
56
|
- `--all` generates both default artifacts with the same timestamp.
|
|
43
57
|
- `--all` does not accept `--output`; custom filenames are supported only for `--full` or `--code`.
|
|
44
58
|
- `--code` creates one Markdown file, not shards or `all.md`.
|
|
45
59
|
- Do not output to `project_context/**`.
|
|
46
60
|
- Do not modify `project_context/context.toml`.
|
|
47
61
|
- Do not register export artifacts as `[[context]]`, `implementation-index` or any Context graph node.
|
|
48
|
-
- Do not write tracked docs; if the user asks for an ordinary docs path, redirect to `tmp/ty-context/context-exports/**`.
|
|
49
|
-
- Export contents may include redaction warnings; do not bypass secret/token/cookie/password/api_key filtering.
|
|
62
|
+
- Do not write tracked docs; if the user asks for an ordinary docs path, redirect to `tmp/ty-context/context-exports/**`.
|
|
63
|
+
- Export contents may include redaction warnings; do not bypass secret/token/cookie/password/api_key/credential/bearer/authorization filtering. Use `--redaction-strict` when the user wants the command to fail if any redaction occurred.
|
|
64
|
+
- Profiles under `<harnessRoot>/config.yaml` are export selectors only. They must not become durable Context facts or execute verification commands.
|
|
50
65
|
|
|
51
66
|
## Handoff
|
|
52
67
|
|