jg-plans 0.1.0 → 0.1.2
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/CHANGELOG.md +10 -0
- package/README.md +6 -6
- package/api/README.md +1 -1
- package/cli/README.md +1 -1
- package/docs/getting-started.md +2 -2
- package/docs/integrations.md +24 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.2 — documentation and examples
|
|
4
|
+
|
|
5
|
+
- Complete the canonical documentation and consumer integration recipes alongside the visual example explorer, original-source downloads, and verified package availability presentation.
|
|
6
|
+
- Keep protocol 0.1 provisional and the reference library/CLI behavior unchanged.
|
|
7
|
+
|
|
8
|
+
## 0.1.1 — trusted publishing validation
|
|
9
|
+
|
|
10
|
+
- Prepare the first automated release after the manual 0.1.0 bootstrap, using the qualified archive and registry/provenance verification workflow.
|
|
11
|
+
- Keep protocol 0.1 and the reference API/CLI behavior from the initial preview.
|
|
12
|
+
|
|
3
13
|
## 0.1.0 — development preview
|
|
4
14
|
|
|
5
15
|
- Introduce provisional protocol 0.1 for Markdown plans with optional milestones, extensible metadata, and ordinary user edits/deletion.
|
package/README.md
CHANGED
|
@@ -2,15 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
A compact planning protocol for people and coding agents. Keep the plan in Markdown, add milestones when they help, and let projects choose their workflows.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Protocol 0.1 is provisional. The [website](https://jg-plans.jesusgraterol.dev) presents the specification, documentation, and examples, with package availability verified independently of the protocol draft.
|
|
6
6
|
|
|
7
7
|
- [Protocol 0.1](protocol/0.1/README.md)
|
|
8
8
|
- [Examples](examples/README.md)
|
|
9
9
|
- [Getting started](docs/getting-started.md)
|
|
10
10
|
- [Library API](api/README.md) and [CLI](cli/README.md)
|
|
11
11
|
- [Consumer integration](docs/integrations.md)
|
|
12
|
-
- [Development](https://github.com/jesusgraterol/jg-plans/blob/
|
|
13
|
-
- [Website development and visual checks](https://github.com/jesusgraterol/jg-plans/blob/
|
|
12
|
+
- [Development](https://github.com/jesusgraterol/jg-plans/blob/main/docs/development.md)
|
|
13
|
+
- [Website development and visual checks](https://github.com/jesusgraterol/jg-plans/blob/main/website/README.md)
|
|
14
14
|
|
|
15
15
|
## Project blueprint
|
|
16
16
|
|
|
@@ -19,12 +19,12 @@ A compact planning protocol for people and coding agents. Keep the plan in Markd
|
|
|
19
19
|
| protocol/ | Normative versioned specification and version index. |
|
|
20
20
|
| examples/ | Invented public documents and independently described expected observations. |
|
|
21
21
|
| docs/ | Concise durable concepts and operating guides; API and HTTP/error references stay outside docs/. |
|
|
22
|
-
| Root package |
|
|
22
|
+
| Root package | Public reference library and thin CLI. |
|
|
23
23
|
| src/ | Protocol schemas, tolerant parsers, selected-directory reads, targeted metadata/marker edits, and CLI. |
|
|
24
24
|
| api/, cli/, errors/ | Canonical public API, automation, and error references. |
|
|
25
25
|
| scripts/package/ | Build, local archive creation, and isolated installed-consumer verification. |
|
|
26
26
|
| scripts/release/, .github/workflows/ | Source/checksum receipts, registry/provenance verification, and qualified delivery. |
|
|
27
|
-
| website/ | Private Astro/Tailwind workspace
|
|
27
|
+
| website/ | Private Astro/Tailwind workspace for canonical docs, parsed examples, and verified release presentation. |
|
|
28
28
|
| .agents/skills/jg-plans-maintenance/ | Shared project maintenance skill; Claude discovers the same source through its repository symlink. |
|
|
29
29
|
|
|
30
30
|
Users own their documents and can edit or delete them. No history store, metadata field, CLI, or website is required to read Markdown. Optional conformance checks do not authorize execution or become a prerequisite to inspection.
|
|
@@ -42,7 +42,7 @@ pnpm check:package
|
|
|
42
42
|
pnpm check
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
The [development guide](https://github.com/jesusgraterol/jg-plans/blob/
|
|
45
|
+
The [development guide](https://github.com/jesusgraterol/jg-plans/blob/main/docs/development.md) owns checks and package/site boundaries. Root tests build first, exercise public compiled exports, and install the actual tarball in an isolated consumer. Website tests verify production output in both themes and narrow layouts.
|
|
46
46
|
|
|
47
47
|
The [runnable library example](examples/library.mjs) creates, inspects, updates, and checks documents in an owned temporary directory. Mutations preserve unrelated bytes and require callers to serialize edits to each document; unsupported edits fail without rewriting it. The [API](api/README.md) describes the exact preservation and concurrency limits.
|
|
48
48
|
|
package/api/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Library API
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Protocol 0.1 is provisional. These operations describe the implemented reference library. Check the [website's availability label](https://jg-plans.jesusgraterol.dev/docs/api/) before choosing a published package version.
|
|
4
4
|
|
|
5
5
|
The ESM root exports compiled JavaScript and TypeScript declarations. Node.js 24.15.0 is the runtime floor. Importing jg-plans does not inspect files, log output, or start a process. The only public import path is `jg-plans`.
|
|
6
6
|
|
package/cli/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The executable is tested from the packed archive. Check the [website's availability label](https://jg-plans.jesusgraterol.dev/docs/cli/) for published-package availability, or run the built executable from a checkout.
|
|
4
4
|
|
|
5
5
|
```sh
|
|
6
6
|
jg-plans inspect --directory ./jg-plans/example
|
package/docs/getting-started.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Getting started
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The protocol and examples are usable directly. The reference library and CLI are optional; the [website's availability label](https://jg-plans.jesusgraterol.dev/docs/) identifies a verified published version. The checkout commands below work independently of npm publication.
|
|
4
4
|
|
|
5
5
|
Start with an ordinary [small plan](../examples/small/plan.md). It contains five core metadata fields and a short Markdown body. Add [milestones](../examples/with-milestones/milestones.md) only when separate units help review the work. Users can edit, move, or delete these files.
|
|
6
6
|
|
|
@@ -33,4 +33,4 @@ Serialize each document's complete read/edit/write operation. Unsupported YAML/a
|
|
|
33
33
|
|
|
34
34
|
## Contributing
|
|
35
35
|
|
|
36
|
-
The [development guide](https://github.com/jesusgraterol/jg-plans/blob/
|
|
36
|
+
The [development guide](https://github.com/jesusgraterol/jg-plans/blob/main/docs/development.md) owns checks and package/site boundaries. Tests exercise built root exports and an isolated installation of the actual tarball. The protocol remains provisional until separately approved skill and HQ integrations exercise it.
|
package/docs/integrations.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Consumer integration
|
|
2
2
|
|
|
3
|
-
Use [protocol 0.1](../protocol/0.1/README.md) as the compact shared format. A project can read Markdown itself or use the
|
|
3
|
+
Use [protocol 0.1](../protocol/0.1/README.md) as the compact shared format. A project can read Markdown itself or use the reference library/CLI. The [website](https://jg-plans.jesusgraterol.dev) identifies verified package availability. The protocol is usable without installing a tool or calling a website.
|
|
4
4
|
|
|
5
5
|
## Keep policy with the consumer
|
|
6
6
|
|
|
@@ -24,4 +24,26 @@ The selected directory and ancestors are trusted caller choices. The library rej
|
|
|
24
24
|
|
|
25
25
|
## Adoption boundary
|
|
26
26
|
|
|
27
|
-
Adopting this protocol in jg-skills or an HQ project is separately scoped work.
|
|
27
|
+
Adopting this protocol in jg-skills or an HQ project is separately scoped work. Protocol 0.1 stays provisional until jg-skills and at least one HQ consumer have exercised it. Those integrations are not prerequisites for using this project, and no downstream adoption is claimed here.
|
|
28
|
+
|
|
29
|
+
## Skills: one shared section, distinct responsibilities
|
|
30
|
+
|
|
31
|
+
Keep installed skills self-contained. Copy the compact writer/reader rules into one identically maintained section stamped **jg-plans protocol 0.1**. During the skills build, compare that section across every generated skill that includes it and fail on drift. Do not make loading or using a skill depend on the website, a network request, or running the jg-plans CLI.
|
|
32
|
+
|
|
33
|
+
Keep role-specific instructions outside that common section:
|
|
34
|
+
|
|
35
|
+
- **jg-plan:** write identity, creation/update timestamps, revision, and status; explain the intent and revision summary in Markdown. Revising a plan preserves existing milestones and progress unless the user asks to change or remove them. Avoid creating redundant companion files for a small task.
|
|
36
|
+
- **jg-breakdown:** add optional milestones when they help. Place status immediately after the milestone heading; place an optional UUID ID on the next line. Preserve established identities and progress while revising the breakdown. Treat any overview as derived information.
|
|
37
|
+
- **jg-execute:** read the selected documents and the user's actual authorization. Existing status markers describe progress; missing metadata, removed files, and checker findings do not create or revoke permission.
|
|
38
|
+
- **jg-review and jg-review-session:** assess the relevant work against available evidence and the selected plan. Name missing evidence without inventing history or treating a deleted document as completion. The status line remains authoritative over an overview row.
|
|
39
|
+
- **Publication/discovery skills:** recognize both coding-agent-planning/ and jg-plans/, as well as explicitly configured roots. Exclude planning files from broad publication unless the user deliberately includes them. Report a selected planning directory that is not ignored; do not silently change ignore rules or move documents.
|
|
40
|
+
|
|
41
|
+
For root selection, honor an explicit path first. Otherwise keep the project's configured or established root, including an existing coding-agent-planning/ directory, before introducing jg-plans/ as a new default. When multiple roots are present, resolve the intended scope through the integration's configuration or the user's selection. A root name never grants permission to read unrelated old plans.
|
|
42
|
+
|
|
43
|
+
Use the CLI only during development to validate documents produced by skill behavior evaluations. Include small plans, custom metadata/statuses, revisions with existing done milestones, edited marker placement, deleted metadata, and deleted companion files. Verify that skills preserve existing progress and obey their role, beyond checking preferred writer conformance. A development evaluation failure is feedback for the skill author; runtime document inspection and user edits remain available.
|
|
44
|
+
|
|
45
|
+
## HQ consumers: depend on the reference implementation
|
|
46
|
+
|
|
47
|
+
Use jg-plans for generic parsing and explicit document operations rather than maintaining another interpretation. Preserve a supported public consumer API with the smallest necessary wrapper, or make a documented breaking release when moving to the new dependency changes its contract. Test against that consumer's established documents and public API before migration.
|
|
48
|
+
|
|
49
|
+
Keep approval digests, authorization, strict project frontmatter, resource schemas, execution, coordination, serialization, and reconciliation inside HQ. A stricter local profile may reject a document for a project-specific action; that does not make the document unreadable under the protocol. Avoid automatic repair, restoration of deleted plans, or silent rewriting to satisfy a closed project schema.
|