agentflight 0.2.0 → 0.3.1

package/docs/development/release.md

@@ -0,0 +1,66 @@
+# Release Process
+
+AgentFlight releases use npm Trusted Publishing from GitHub Actions.
+
+## Why Tags, Not Every Push
+
+npm versions are immutable. Publishing on every push would either fail whenever the version is unchanged or force noisy version churn. AgentFlight verifies every push, but publishes only from version tags.
+
+## npm Trusted Publisher Settings
+
+Configure these values on npmjs.com for the `agentflight` package:
+
+- Publisher: `GitHub Actions`
+- Organization or user: `abhiyoheswaran1`
+- Repository: `AgentFlight`
+- Workflow filename: `release.yml`
+- Environment name: `npm`
+- Allowed actions: `Allow npm publish`
+
+Do not enable `Allow npm stage publish` unless AgentFlight intentionally adopts npm staged releases later.
+
+## Release Checklist
+
+1. Update `package.json` and `package-lock.json` to the new version.
+2. Update `CHANGELOG.md`.
+3. Run verification:
+
+   ```bash
+   npm run verify
+   npm run format:check
+   npm pack --dry-run
+   ```
+
+4. Commit the release:
+
+   ```bash
+   git add .
+   git commit -m "chore: release v0.1.1"
+   ```
+
+5. Tag and push:
+
+   ```bash
+   git tag v0.1.1
+   git push origin main --tags
+   ```
+
+6. Confirm:
+
+   ```bash
+   npm view agentflight version
+   npx --yes agentflight@latest --help
+   ```
+
+## Manual Emergency Publish
+
+Manual publishing is allowed for emergencies while the package is young:
+
+```bash
+npm run verify
+npm run format:check
+npm pack --dry-run
+npm publish --access public
+```
+
+Record any manual publish in `CHANGELOG.md` and `AGENTFLIGHT_DEVLOG.md`.

package/docs/examples/basic-agentflight-session.md

@@ -0,0 +1,164 @@
+# Basic AgentFlight Session
+
+This example shows a fictional local session for adding a password reset flow.
+
+## 1. Start The Flight
+
+```bash
+npx agentflight@latest init
+npx agentflight@latest start --task "Add password reset flow"
+```
+
+AgentFlight records the task, current branch, commit, dirty state, package manager, and available tools. It also writes `.agentflight/current/handoff.md` so the coding agent or human reviewer has a starting point.
+
+## 2. Run The Coding Agent
+
+Run Codex, Claude Code, Cursor, or another coding agent normally.
+
+In this example the agent changes:
+
+```text
+src/password-reset.ts
+tests/password-reset.test.ts
+docs/password-reset.md
+```
+
+## 3. Capture Proof
+
+```bash
+npx agentflight@latest verify -- npm test
+```
+
+AgentFlight runs the command and stores local evidence:
+
+```text
+Verification recorded
+
+Command:
+npm test
+
+Status:
+passed
+
+Evidence:
+stdout: .agentflight/evidence/.../verification-1.stdout.txt
+stderr: .agentflight/evidence/.../verification-1.stderr.txt
+```
+
+If the command fails, AgentFlight records it as failed. It does not turn failed proof into success.
+
+## 4. Create A Snapshot
+
+```bash
+npx agentflight@latest snapshot --note "Initial implementation verified"
+```
+
+The snapshot records:
+
+- branch
+- commit
+- dirty state
+- changed files
+- risk level
+- verification summary
+- note
+
+AgentFlight stores this as a session event. It does not store full code diffs by default.
+
+## 5. Check Status
+
+```bash
+npx agentflight@latest status
+```
+
+Example:
+
+```text
+AgentFlight status
+
+Task:
+Add password reset flow
+
+Changed files:
+3
+
+Changed areas:
+- docs: docs/password-reset.md
+- tests: tests/password-reset.test.ts
+- unknown: src/password-reset.ts
+
+Risk: medium
+- Dependency, backend, or unknown files changed.
+
+Verification Evidence:
+1 passed, 0 failed
+
+Latest snapshot:
+- Note: Initial implementation verified
+- Risk: medium
+- Changed files: 3
+
+Review readiness: Ready for review
+
+Next action:
+Generate a proof report with agentflight report
+```
+
+## 6. Generate Review Artifacts
+
+```bash
+npx agentflight@latest report
+npx agentflight@latest replay
+```
+
+The Markdown report gives a reviewer the task, session metadata, changed files, risk summary, timeline, verification evidence, and recommendation.
+
+The HTML replay gives a browser-friendly timeline:
+
+```text
+session_started
+verification_started
+verification_passed
+snapshot_created
+report_generated
+replay_generated
+```
+
+Both artifacts stay local under `.agentflight/reports/`.
+
+## 7. Resume Safely
+
+```bash
+npx agentflight@latest resume
+```
+
+The resume prompt includes:
+
+- original task
+- current state
+- changed files
+- risk
+- latest snapshot note
+- verification state
+- next recommended action
+- guardrails for the next agent
+
+Example guardrails:
+
+```text
+- Stay scoped to the current task.
+- Do not start unrelated work.
+- Do not claim completion without proof.
+- Run relevant verification before declaring success.
+```
+
+## What This Gives You
+
+By the end of the session, you know:
+
+- what changed
+- how risky it looks
+- what proof exists
+- what proof is missing
+- whether the work is ready for review
+- how to hand it off without losing context

package/docs/roadmap.md

@@ -0,0 +1,49 @@
+# Roadmap
+
+## MVP
+
+- Local CLI package.
+- Safe `.agentflight/` initialization.
+- Session start and current handoff.
+- Changed-file risk summary.
+- Markdown proof report.
+- Self-contained HTML replay.
+- Resume prompt.
+- Doctor checks.
+- Defensive ProjScan and AgentLoopKit adapters.
+- Verification evidence capture.
+- Session events and snapshots.
+
+## Future Free/Open-Core
+
+- Basic local session history.
+- Structured `--json` output.
+- Richer configurable verification command profiles.
+- More precise git diff stats without including full code by default.
+- Timeline filtering and richer local replay navigation.
+
+## Future Pro
+
+- Searchable local session history.
+- Advanced replay exports.
+- Multi-repo workspace.
+- Custom report themes.
+- Advanced policy packs.
+- Agent mistake analytics.
+
+## Future Team
+
+- GitHub PR comments.
+- Shared policies.
+- Team dashboard.
+- Audit trail.
+- Required verification gates.
+- Slack, Linear, and Jira integrations.
+
+## Future Enterprise
+
+- Self-hosted deployment.
+- SSO.
+- Compliance exports.
+- Custom risk rules.
+- Support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentflight",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Local-first flight recorder for AI coding agents.",
   "type": "module",
   "main": "./dist/cli.js",
@@ -11,6 +11,12 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
+    "docs/assets/agentflight-replay-timeline.png",
+    "docs/development/dogfooding.md",
+    "docs/development/release.md",
+    "docs/examples/basic-agentflight-session.md",
+    "docs/roadmap.md",
     "LICENSE"
   ],
   "scripts": {
@@ -34,8 +40,13 @@
   "keywords": [
     "ai",
     "coding-agents",
+    "codex",
+    "claude-code",
     "cli",
     "developer-tools",
+    "agentic-coding",
+    "verification",
+    "code-review",
     "local-first",
     "observability"
   ],