Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agentic/ONRAMP.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ The CI-gated release checklist. Your job is to land a `chore: release vX.Y.Z` PR
| Current task you're working | `.agentic/tasks/*.json` (manually mirrored from GH) | Exercised by `agentic task next` as part of the dogfood |
| Durable non-obvious facts | `.agentic/memory/*.json` | "Why" that isn't in the code |
| Values and in-turn orientation | `.agentic/personas/spores-maintainer.md` | What you prioritize while wearing the hat |
| Release procedure | `.agentic/skills/release-check/skill.md` + `.agentic/workflows/spores-release.json` | CI-gated via `.github/workflows/publish.yml` (OIDC) |
| Release procedure | `.agentic/skills/release-check/skill.md` + `.agentic/workflows/agentic-release.json` | CI-gated via `.github/workflows/publish.yml` (OIDC) |

When two sources disagree, trust git and GitHub. Update the dogfood to match — that's the "dogfood as operational workspace, not curated fixture" stance.

Expand All @@ -54,7 +54,7 @@ This section is a living punch list. If you fix something, delete the bullet.

- **`tasks/` sync with GitHub issues is manual.** When you add a ready issue, seed a matching task file. When you close a GH issue, mark the task done. This is a bandaid — the real fix is a TaskAdapter that reads from GitHub issues directly (filed as a v0.2+ issue). Until then, keep them in hand-sync.

- **The persona's task filter is not applied by any CLI verb.** This is the known v0.2 composition-object seam from tnezdev/spores#16. `task next` returns the highest-ULID ready task regardless of the maintainer persona's `task_filter: { tags: [spores] }`. It's the exact design signal #16 was filed to track. Don't work around it in CLI code.
- **The persona's task filter is not applied by any CLI verb.** This is the known v0.2 composition-object seam from tnezdev/agentic#16. `task next` returns the highest-ULID ready task regardless of the maintainer persona's `task_filter: { tags: [spores] }`. It's the exact design signal #16 was filed to track. Don't work around it in CLI code.

## How to treat this doc

Expand Down
10 changes: 5 additions & 5 deletions .agentic/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# .agentic/ — dogfood example

This directory is the **v0.1 release-gate smoke test** (#10). If we can't use agentic to build agentic, v0.1 isn't ready to ship.
This directory is the project dogfood workspace. If we can't use Agentic to build Agentic, the primitive shape needs work.

Every file here is exercised by the agentic CLI itself. Think of it as both the self-use and the working example that ships with the repo.

Expand All @@ -11,9 +11,9 @@ Every file here is exercised by the agentic CLI itself. Think of it as both the
| `config.toml` | (all) | Agentic config — `adapter = "filesystem"`, dirs for each primitive |
| `personas/spores-maintainer.md` | persona | The hat to wear when working on this codebase. Real principles, real activation triggers, real situational tokens |
| `skills/release-check/skill.md` | skill | The pre-release checklist. Piped into the agent before cutting a new version |
| `workflows/spores-release.json` | workflow | 9-node release graph: verify-clean → run-tests → typecheck → dep-audit → pack-dry-run → version-bump → tag-push → publish → verify-published |
| `workflows/agentic-release.json` | workflow | CI-gated release graph: release PR → sync main → push tag → watch publish.yml → verify registry/provenance |
| `memory/*.json` | memory | Durable facts about this repo (npm package name, zero-deps rule, v0.1 runtime-scoping decision) |
| `tasks/*.json` | task | Real v0.1 tasks — dogfood verification, release cut, v0.2 composition design |
| `tasks/*.json` | task | Real mirrored tasks — dogfood verification, release cut, v0.2 composition design |
| `runs/` | workflow | Ephemeral per-run state. **gitignored.** |

## How to use
Expand All @@ -37,7 +37,7 @@ bun src/cli/main.ts skill run release-check
bun src/cli/main.ts task next

# Kick off a release run
bun src/cli/main.ts workflow run spores-release --name "0.1.0-cut"
bun src/cli/main.ts workflow run agentic-release --name "0.5.0-cut"

# Query memories when you need the "why"
bun src/cli/main.ts memory recall "runtime scope"
Expand All @@ -50,7 +50,7 @@ bun src/cli/main.ts memory recall "runtime scope"
- **The persona reads like something a human would actually write for themselves.** Not a label, not a role — a set of non-negotiables and a "before you start" checklist. If it feels forced, the primitive isn't pulling its weight.
- **Skills are agent-facing work product.** `release-check` is not documentation *about* releasing — it's the actual pipeline an agent follows, with verification commands inline.
- **Memories are non-obvious durable facts**, not restatements of what `git log` already tells you. "Zero production dependencies is a hard rule" is worth remembering because the code alone doesn't say why.
- **Tasks are the real backlog**, not fake examples. The three seeded here are the literal next moves on the v0.1 milestone.
- **Tasks are the real backlog**, not fake examples. Keep them in sync with GitHub ready issues when dogfooding exposes drift.
- **The workflow is a real process**, not a toy DAG. Every node corresponds to a command someone actually runs at release time.

## What this dogfood validated
Expand Down
13 changes: 13 additions & 0 deletions .agentic/memory/agentic-trusted-publishing-configured.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{
"key": "agentic-trusted-publishing-configured",
"content": "npm Trusted Publishing is configured for @tnezdev/agentic against tnezdev/agentic and .github/workflows/publish.yml as of 2026-06-04. First tagged Agentic publish has not run yet, so verify provenance after the first release.",
"weight": 0.5,
"confidence": 1,
"tier": "L1",
"tags": [
"spores",
"npm-publishing",
"release"
],
"timestamp": "2026-06-04T15:33:30.806Z"
}
14 changes: 7 additions & 7 deletions .agentic/personas/spores-maintainer.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,12 @@ skills: [release-check]
task_filter:
tags: [spores]
status: ready
workflow: spores-release
workflow: agentic-release
effort: high
reasoning: high
---

# Spores maintainer
# Agentic maintainer

You are working on `@tnezdev/agentic` — a TypeScript library + CLI on Bun that ships agent in-loop primitives. Currently shipping: Memory, Workflow, Skills, Tasks, Persona, Source (pluggable loader abstraction), and Dispatch (foundation types for the universal inbound message primitive). Runtime concerns (transport, scheduling, handler execution) stay with the caller.

Expand All @@ -25,14 +25,14 @@ The time is `{{timestamp}}`.
- **Adapter pattern.** Every primitive has an `adapter.ts` interface and a `filesystem.ts` implementation. New storage backends implement the same interface.
- **No `console.log` in library code.** CLI output goes through `output(ctx, data, formatter)` re-exported from `src/cli/main.ts`.
- **Test files colocated.** `src/foo/filesystem.test.ts` next to `src/foo/filesystem.ts`. Inline fixtures, no separate fixtures directory.
- **Identity lives outside spores.** Spores ships primitives — not sessions, not attribution, not `observed_by`. If you're tempted to add an identity field, stop.
- **Identity lives outside Agentic.** Agentic ships primitives — not sessions, not attribution, not `observed_by`. If you're tempted to add an identity field, stop.

## Before picking up work

1. Check current state from authoritative sources: `git log -10 --oneline` and `gh pr list --author @me`
2. Check ready work on this repo: `gh issue list --repo tnezdev/agentic --state open --label ready`
3. Run `spores task next` to see the top locally-mirrored ready task
4. If GitHub ready-issues and `.spores/tasks/` disagree, trust GitHub and update the local task files — see `.spores/ONRAMP.md` "Known drift"
3. Run `agentic task next` to see the top locally-mirrored ready task
4. If GitHub ready-issues and `.agentic/tasks/` disagree, trust GitHub and update the local task files — see `.agentic/ONRAMP.md` "Known drift"
5. If a task has no `ready` label yet, it's either a design issue or unclear scope — raise the question on the issue before starting

## Before opening a PR
Expand All @@ -45,6 +45,6 @@ The time is `{{timestamp}}`.

## Durable context

The `persona.activated` hook at `.spores/hooks/persona.activated` recalls memories tagged with this persona's `memory_tags` and appends them below this body at activation time. Read those recalled memories for the current shape of durable non-obvious facts (runtime scope, publish path, v0.1 decisions) — they are the source of truth, not this body.
The `persona.activated` hook at `.agentic/hooks/persona.activated` recalls memories tagged with this persona's `memory_tags` and appends them below this body at activation time. Read those recalled memories for the current shape of durable non-obvious facts (runtime scope, publish path, v0.1 decisions) — they are the source of truth, not this body.

The job of this body is rules and rhythms that do not change per session: the principles above, the "before picking up work" checklist, the "before opening a PR" list. Situational facts live in memory and get auto-recalled. If a durable fact isn't showing up when you need it, `spores memory remember` it with the right tag and the next activation will surface it automatically.
The job of this body is rules and rhythms that do not change per session: the principles above, the "before picking up work" checklist, the "before opening a PR" list. Situational facts live in memory and get auto-recalled. If a durable fact isn't showing up when you need it, `agentic memory remember` it with the right tag and the next activation will surface it automatically.
18 changes: 9 additions & 9 deletions .agentic/skills/post-publish-check/skill.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
name: post-publish-check
description: Activate after publishing a new release — installs the package from the npm registry and verifies all exports load under Bun
tags: [spores, release, npm, testing]
description: Activate after publishing a new release — installs the package from the npm registry and verifies all exports load under Bun and Node
tags: [agentic, release, npm, testing]
---

# Post-publish check

Validates that `@tnezdev/agentic` is consumable when installed from the npm registry. This is the safety net that catches registry-specific issues (missing files, bad `exports` map, propagation problems) that the pre-publish smoke test can't.
Validates that `@tnezdev/agentic` is consumable when installed from the npm registry. This is the safety net that catches registry-specific issues (missing files, bad `exports` map, propagation problems) that the pre-publish smoke tests can't.

## Run it

Expand All @@ -19,16 +19,16 @@ bash scripts/post-publish-check.sh [version]

## What it does

1. Creates a temp consumer project
2. Installs `@tnezdev/agentic@<version>` from the npm registry via `bun add`
3. Prints the installed version
4. Runs `scripts/smoke-consumer.ts` — the same export checks used by the pre-publish smoke test
1. Creates temp Bun and Node consumer projects
2. Installs `@tnezdev/agentic@<version>` from the npm registry via `bun add` and `npm install`
3. Prints the installed versions
4. Runs `scripts/smoke-consumer.mjs` under Bun and Node — the same export checks used by the pre-publish smoke tests

## When to run

- After every release, as the final step of the `spores-release` workflow (step 5: verify-registry)
- After every release, as the final step of the `agentic-release` workflow (step 5: verify-registry)
- When investigating consumer reports of import failures

## Relation to smoke-test

`smoke-test` validates the `npm pack` tarball *before* publish. `post-publish-check` validates the registry package *after* publish. They share the same consumer script (`scripts/smoke-consumer.ts`).
`smoke-test` and `smoke-test-node` validate the `npm pack` tarball *before* publish. `post-publish-check` validates the registry package *after* publish. They share the same consumer script (`scripts/smoke-consumer.mjs`).
11 changes: 7 additions & 4 deletions .agentic/skills/release-check/skill.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: release-check
description: Activate when cutting a new @tnezdev/agentic release — the CI-gated checklist for landing a version bump and triggering the tag publish
tags: [spores, release, npm, ci]
tags: [agentic, release, npm, ci]
---

# Release check — @tnezdev/agentic
Expand All @@ -12,6 +12,8 @@ Releases are **CI-gated**. You don't run `npm publish`; you push a `vX.Y.Z` tag

**First Agentic publish gate:** before the first CI-published `@tnezdev/agentic` release, verify npm Trusted Publishing is configured for `@tnezdev/agentic` against this repo and `.github/workflows/publish.yml`. The old `@tnezdev/spores` trusted publisher registration does not automatically cover the new package name. If npm requires a one-time local bootstrap publish before Trusted Publishing can be configured, publish without provenance; CI adds provenance explicitly after the trusted publisher exists.

Do this before the release PR or tag, not while a publish run is failing. The package page must trust `tnezdev/agentic`, workflow `.github/workflows/publish.yml`, and the tag ref pattern used by this workflow.

## 1. Land the version bump on main

Open a `chore: release vX.Y.Z` PR that:
Expand Down Expand Up @@ -52,8 +54,9 @@ What the workflow does (for context when reading logs):

1. Checkout + Bun + `bun install --frozen-lockfile`
2. `bun run typecheck` and `bun test` (re-gate, cheap)
3. Bootstraps npm 11 via direct tarball download (the runner's bundled npm has historically been corrupt on fresh `ubuntu-latest` images — don't "simplify" this step)
4. `npm publish --provenance --access public` using OIDC — no token, no secret
3. Builds `dist/` and smoke-tests the packed tarball under both Bun and Node
4. Bootstraps npm 11 via direct tarball download (the runner's bundled npm has historically been corrupt on fresh `ubuntu-latest` images — don't "simplify" this step)
5. `npm publish --provenance --access public` using OIDC — no token, no secret

If the workflow fails:

Expand All @@ -70,7 +73,7 @@ bash scripts/post-publish-check.sh X.Y.Z

`npm view` should print the version you just tagged. If it lags, wait 30 seconds and retry — npm registry propagation.

Then run the post-publish check — it installs the package from the registry in a temp dir and verifies all public API exports load under Bun. Pass the explicit version since `latest` may not have propagated yet.
Then run the post-publish check — it installs the package from the registry in a temp dir and verifies all public API exports load. Pass the explicit version since `latest` may not have propagated yet.

Also spot-check provenance on https://www.npmjs.com/package/@tnezdev/agentic — the published version should show a "Built and signed on GitHub Actions" badge linking back to the workflow run. That badge is the whole point of OIDC; its absence means provenance attestation didn't attach and is worth investigating.

Expand Down
12 changes: 6 additions & 6 deletions .agentic/skills/smoke-test/skill.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,34 @@
---
name: smoke-test
description: Activate when you need to validate the package is consumable before a release — runs npm pack, installs the tarball, and verifies exports under Bun
tags: [spores, release, npm, testing]
description: Activate when you need to validate the package is consumable before a release — runs npm pack, installs the tarball, and verifies exports under Bun and Node
tags: [agentic, release, npm, testing]
---

# Pre-publish smoke test

Validates that `@tnezdev/agentic` is consumable from an `npm pack` tarball under Bun. This catches packaging issues (missing files, broken imports, wrong entry point) before a release tag is pushed.
Validates that `@tnezdev/agentic` is consumable from an `npm pack` tarball under Bun and Node. This catches packaging issues (missing files, broken imports, wrong entry point) before a release tag is pushed.

## Run it

```bash
bash scripts/smoke-test.sh
bash scripts/smoke-test-node.sh
```

## What it does

1. `npm pack` in the repo root — produces the exact tarball that `npm publish` would upload
2. Creates a temp consumer project and installs the tarball via `bun add`
3. Runs `scripts/smoke-consumer.ts` which imports the public API and checks that all value exports are present and constructable
3. Runs `scripts/smoke-consumer.mjs` which imports the public API and checks that all value exports are present and constructable

## When to run

- Before pushing a release tag (`vX.Y.Z`)
- After changing `package.json` fields (`files`, `main`, `exports`)
- After adding or removing public exports from `src/index.ts`

CI runs this automatically in `.github/workflows/publish.yml` between the test step and the publish step.
CI runs these automatically in `.github/workflows/ci.yml` and `.github/workflows/publish.yml` between the test step and the publish step.

## Current scope

- **Bun only.** Node.js consumption is not validated (see tnezdev/spores#32).
- Checks value exports exist with the right type (`function` for classes and functions). Does not exercise runtime behavior beyond import resolution.
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"id": "spores-release",
"id": "agentic-release",
"name": "Agentic release cut",
"description": "CI-gated release flow for @tnezdev/agentic — land version bump on main, push tag, let publish.yml ship via OIDC trusted publishing",
"version": "2.0",
"version": "1.0",
"nodes": [
{
"id": "version-bump-pr",
Expand All @@ -25,7 +25,7 @@
{
"id": "watch-publish-ci",
"label": "Watch publish.yml run",
"description": "gh run watch --exit-status — publish.yml runs typecheck+test, bootstraps npm 11 via tarball, publishes with OIDC + provenance. No local publish.",
"description": "gh run watch --exit-status — publish.yml runs typecheck, tests, Bun and Node smoke tests, then publishes with OIDC + provenance. No local publish.",
"artifact_type": "ci-run"
},
{
Expand Down
97 changes: 0 additions & 97 deletions .agentic/workflows/spores-release.source.json

This file was deleted.

Loading
Loading