npm package: @kamishino/kamiflow-core
Description: Standalone Kami Flow Core Codex skill with a minimal installer.
Latest version: 0.8.7

# Kami Flow Core

This repository is the source of truth for one standalone Codex skill: `kamiflow-core`.

## Install From npm

```bash
npx --package @kamishino/kamiflow-core kamiflow-core install --project .
```

Use this in a client repo to install the skill, generate `.local/project.md`, bootstrap `.local/plans/`, and create a local-only `AGENTS.md` when the repo does not already have one.

## Source Repo Dogfood

For Codex to discover that skill inside this repo, the repo also needs a generated runtime install under `.agents/skills/kamiflow-core/`.

## GitHub Release To npm

This repo now publishes `@kamishino/kamiflow-core` to npm from GitHub Releases through [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml).

The release contract is:

1. prepare the functional change and merge it
2. run `node .agents/skills/kamiflow-core/scripts/version-closeout.mjs --project .` when the SemVer release commit and tag are due
3. create the release-only commit and `vX.Y.Z` tag locally
4. push the commit and tag to GitHub
5. publish a GitHub Release from that tag
6. let GitHub Actions run validation and `npm publish`

The workflow is intentionally triggered only by `release.published`, not by every push to `main`.

### Trusted Publishing Setup

Recommended: configure npm Trusted Publishing for `@kamishino/kamiflow-core` instead of relying on a long-lived npm token.

In npm package settings, add a trusted publisher with:

- organization or user: `kamishino`
- repository: `kamiflow-codex-starter`
- workflow filename: `publish-npm.yml`
- runner: GitHub-hosted Actions

Enter only the workflow filename on npm, not the full `.github/workflows/...` path. Keep that filename stable after npm is configured, because npm validates the exact repository and workflow filename.

The workflow already includes:

- `permissions.id-token: write` for GitHub OIDC
- Node.js `22.14.0` and npm CLI `11.5.1` to meet npm Trusted Publishing requirements
- validation before publish with `npm ci` and `npm run validate`
- a release-tag check that requires the GitHub Release tag to match `package.json`
- `npm pack` as a publishable tarball smoke check
- `npm publish --provenance --access public`

### Fallback `NPM_TOKEN`

If Trusted Publishing is unavailable or temporarily misconfigured, add the repository secret `NPM_TOKEN`. The workflow still exports `NODE_AUTH_TOKEN` for npm's token fallback path, but keep that path as fallback-only and prefer fixing Trusted Publishing first.

### Troubleshooting `ENEEDAUTH`

If the publish workflow fails with `npm ERR! code ENEEDAUTH`, check these items in order:

1. confirm the npm Trusted Publisher uses:
   - organization or user `kamishino`
   - repository `kamiflow-codex-starter`
   - workflow filename `publish-npm.yml`
   - GitHub-hosted Actions
2. confirm the workflow still has `permissions.id-token: write`
3. confirm the GitHub Release was published after the Trusted Publisher settings were saved
4. if Trusted Publishing is not ready yet, add or rotate `NPM_TOKEN` as the fallback secret

If a tag is pushed but npm stays unchanged, that is expected until the matching GitHub Release is published. Tags alone do not trigger npm publish in this repo.

## Legacy KFC Line

If you need the pre-pivot KFC repository shape, use:

- branch: `codex/legacy-kfc-main`
- tag: `legacy-kfc-main-2026-03-23`

## Use In This Repo

```bash
npm run skill:sync
npm run skill:doctor
```

`npm run skill:sync` installs the current SSOT skill into this repo's `.agents/skills/kamiflow-core/` runtime path. It keeps this tracked root `AGENTS.md` untouched and creates this repo's dogfood `.local/project.md` only when that runtime file is missing. `npm run skill:doctor` verifies the runtime copy exists, the repo-role-aware contract is present, `.local/plans/` is bootstrapped, and the installed runtime contents still match `resources/skills/kamiflow-core/`.
It also rewrites `.agents/skills/kamiflow-core/install-meta.json` so the runtime stays explicitly marked as the dogfood source-repo sync profile.

If Codex is already open in this repo, start a new session or reload the workspace after `npm run skill:sync` so the skill inventory refreshes.

## Install Into Any Codex Project

That command copies the canonical skill into `.agents/skills/kamiflow-core/` and bootstraps `.local/plans/` for project-local workflow state.
In a normal client repo it treats the repo as the default target, writes `.agents/skills/kamiflow-core/install-meta.json`, creates a local-only `AGENTS.md` only when one does not already exist, adds that generated file to `.git/info/exclude` when the target is a git repo, and creates `.local/project.md` only when that human-facing project brief does not already exist. Rerunning the same command refreshes the skill runtime and install metadata while preserving existing `AGENTS.md` and `.local/project.md`.

Install and recovery stay conservative: missing runtime files may be created, but existing `AGENTS.md` and `.local/project.md` are treated as curated repo memory and are only reported as needing attention when they look structurally thin, placeholder-heavy, or incompatible with helper expectations.

## What Gets Installed

- `.agents/skills/kamiflow-core/SKILL.md`
- `.agents/skills/kamiflow-core/agents/openai.yaml`
- `.agents/skills/kamiflow-core/references/*`
- `.agents/skills/kamiflow-core/scripts/*`
- `.agents/skills/kamiflow-core/assets/*`
- `.agents/skills/kamiflow-core/install-meta.json`
- `AGENTS.md` when the target is a client repo and the file is missing
- `.local/project.md`
- `.local/plans/`
- `.local/plans/done/`

The installer does not generate `.kfc/`, `.codex/rules/`, or any repo-specific scaffold. In this source repo, `npm run skill:sync` reuses the tracked root `AGENTS.md` instead of generating a new one, and `npm run skill:doctor` trusts the runtime metadata to decide whether it should verify a lean client runtime or the full dogfood source sync.

## First Commands After Install

```bash
node .agents/skills/kamiflow-core/scripts/ensure-plan.mjs --project .
node .agents/skills/kamiflow-core/scripts/ready-check.mjs --project .
node .agents/skills/kamiflow-core/scripts/plan-snapshot.mjs --project . --format text
```

Read `AGENTS.md` first for repo rules. Keep `.local/project.md` current as the human-facing project brief. The active plan stays in `.local/plans/*.md`. Direct markdown mutation is the normal workflow. The helper scripts are deterministic recovery commands for plan bootstrap, repo-contract repair, project-brief repair, readiness checks, archive closeout, and lightweight read-only status views.

## Optional Plan View

For a compact status summary in the terminal:

```bash
node .agents/skills/kamiflow-core/scripts/plan-snapshot.mjs --project . --format text
node .agents/skills/kamiflow-core/scripts/plan-snapshot.mjs --project . --format markdown
node .agents/skills/kamiflow-core/scripts/plan-snapshot.mjs --project . --format json
```

For suggestion-only next-slice guidance when no active plan exists:

```bash
node .agents/skills/kamiflow-core/scripts/next-plan.mjs --project . --format text
node .agents/skills/kamiflow-core/scripts/next-plan.mjs --project . --format markdown
node .agents/skills/kamiflow-core/scripts/next-plan.mjs --project . --format json
```

This helper stays read-only. It may suggest a next slice from current priorities, open questions, release state, and plan hygiene, but it does not create a new plan or rewrite repo memory files.

For a lightweight live browser view of the active plan:

```bash
node .agents/skills/kamiflow-core/scripts/plan-view.mjs --project . --open
node .agents/skills/kamiflow-core/scripts/plan-view.mjs --project . --stop
```

This view stays read-only, serves only on localhost, reuses a healthy existing server when possible, and keeps `.local/plans/*.md` as the source of truth. Runtime reuse is tracked only through `.local/plan-view/runtime.json`.

## Optional SemVer Workflow

Client repos can opt into SemVer closeout by adding this block to `AGENTS.md`:

```md
## Release Policy
- SemVer Workflow: enabled
- Version Files: package.json, package-lock.json
- Pre-1.0 Policy: strict
- Release History: separate-release-commit-and-tag
```

This first slice supports root single-package Node/npm repos only. In opted-in repos, active plans gain a `## Release Impact` section, PASS archive requires that section to be resolved, and `node .agents/skills/kamiflow-core/scripts/version-closeout.mjs --project .` prepares the later release-only step. Release level is computed from the full unreleased PASS-plan window since the latest reachable `vX.Y.Z` tag, with highest impact winning across that window. Repos that leave the workflow disabled keep the current behavior.

For assistant-guided closeout, the finish model is:

- `commit please`
  - functional commit only
- `release please`
  - release closeout only
- `finish please`
  - inspect `node .agents/skills/kamiflow-core/scripts/finish-status.mjs --project .` and choose the right final action from repo state

## Repo Structure

- `resources/skills/kamiflow-core/`: canonical skill source.
- `bin/`: minimal published binary for `kamiflow-core install`.
- `scripts/`: installer, validator, doctor, and forward-test utilities for the published package and repo-local self-dogfooding.

## Design Rubric

Use this rubric when deciding whether `kamiflow-core` should gain a new helper or workflow feature.

- `single-job clarity`
  - every helper should do one obvious job
- `inspect before mutate`
  - prefer read-only helpers first and keep mutation explicit
- `client-repo-first`
  - default UX should optimize for normal client repos, not this source repo
- `small local state`
  - keep the contract centered on `AGENTS.md`, `.local/project.md`, `.local/plans/*.md`, and `.local/plans/done/**/*.md`
- `evidence-backed output`
  - prefer compact, stable summaries with counts, blockers, readiness, recommendations, and paths
- `no orchestration theater`
  - avoid role simulation, framework growth, or extra workflow layers
- `portable by default`
  - avoid unnecessary runtime stacks, OS coupling, or dashboard dependence

Before adding a helper, write down:

1. the problem it solves
2. why an existing helper is insufficient
3. the exact input/output shape
4. why it stays lightweight

Keep the current helper surface grouped into three buckets:

- `bootstrap/recovery`
  - `ensure-plan`, `ready-check`
- `hygiene/closeout`
  - `archive-plan`, `cleanup-plans`, `finish-status`, `version-closeout`
- `read models`
  - `plan-history`, `plan-snapshot`, `plan-view`

Do not add helpers that blur these buckets unless the overlap is clearly worth the complexity.

## Maintainer Commands

```bash
npm run validate
npm run skill:sync
npm run skill:doctor
npm run forward-test
npm run forward-test -- --mode full
node .agents/skills/kamiflow-core/scripts/finish-status.mjs --project .
npm pack
```

`npm run validate` checks the standalone skill contract without mutating the runtime copy. `npm run skill:sync` refreshes this repo's `.agents/skills/kamiflow-core/` runtime install, preserves the tracked root `AGENTS.md`, and creates the dogfood `.local/project.md` here if it is missing. `npm run skill:doctor` proves whether this repo is Codex-ready or stale and prints the exact recovery command when it is not. `npm run forward-test` is the faster smoke lane and now includes a non-Codex repo-role smoke for client vs source-repo runtime shape. `npm run forward-test -- --mode full` keeps the full serial behavioral suite and takes longer because it launches multiple real `codex exec` sessions against fresh temp projects from a packed tarball. `node .agents/skills/kamiflow-core/scripts/finish-status.mjs --project .` reports whether the current end-of-slice action should be commit-only, release-only, or commit-and-release. Forward-test artifacts live under `.local/forward-tests/` and now include timing breakdowns. `npm pack` builds the publishable tarball for local smoke tests or release workflows.

This source repo also opts into the SemVer workflow. After one or more PASS plans with unreleased `patch`, `minor`, or `major` impact since the latest release tag, use this sequence:

1. check the helper-backed finish recommendation:

```bash
node .agents/skills/kamiflow-core/scripts/finish-status.mjs --project .
```

2. if the helper says `commit-only` or `commit-and-release`, commit the functional changes with a normal scanner-friendly subject
3. if the helper says release is still pending, run:

```bash
node .agents/skills/kamiflow-core/scripts/version-closeout.mjs --project .
```

That helper blocks on a dirty worktree, aggregates the unreleased PASS-plan window since the latest release tag, updates `package.json`, updates `package-lock.json` when present, and prints:

- the exact release-only commit command for `release: vX.Y.Z`
- the exact tag command for `vX.Y.Z`

It does not auto-commit, auto-tag, or publish.

After you push the release commit and tag, publish the GitHub Release for that `vX.Y.Z` tag. GitHub Actions then performs the npm publish automatically through [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml), using npm Trusted Publishing by default and falling back to `NPM_TOKEN` only if needed. Pushing the tag by itself does not publish to npm.

## Next Improvements

Use the rubric above to prioritize the next changes in this order:

1. sharpen helper output contracts so they return more stable machine-readable summaries
2. tighten read-model consistency across `plan-snapshot`, `finish-status`, `cleanup-plans`, and `plan-history`
3. add short usage examples for each helper so the intended loop is obvious
4. reduce route ambiguity only where real prompts still misroute
5. keep `plan-view` constrained as a read-only helper, not a dashboard product

## Clean `main` Cutover

Use `npm run cutover:main` as the guarded maintainer dry run for replacing `main` with the standalone skill snapshot. It does not touch `main` by default. It verifies the legacy safety refs, checks for the required full forward-test run id, prints the current local and remote `main` refs, and emits the exact execute command for the later cutover window.

The live cutover remains blocked until `npm run forward-test -- --mode full` passes on the source commit you want to publish. After that, run the exact execute command printed by `npm run cutover:main` with:

- `--full-run-id <run-id>` from the passing full run
- `--expected-local-main <sha>` matching the current local `main`
- `--expected-remote-main <sha>` matching the current `origin/main`

In execute mode, the script reruns `validate`, `skill:sync`, `skill:doctor`, `forward-test`, and a tarball install smoke, then creates the clean root commit on `codex/main-skill-clean`. It only updates local `main` or remote `main` when you pass `--update-local-main` and `--push-main` explicitly.