From f148d43c69e0f67ca7939ce0d2683783dae53431 Mon Sep 17 00:00:00 2001 From: Alex Standiford Date: Fri, 17 Jul 2026 17:34:05 -0400 Subject: [PATCH 1/2] Add Project Rocky agent-readiness kit - AGENTS.md and CLAUDE.md agent onboarding docs - navigator.yaml project metadata for Navigator integration Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_0138jQKyzwyDfEbbAeMmYNnL --- AGENTS.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + navigator.yaml | 15 ++++++++++++ 3 files changed, 80 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 navigator.yaml diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b1e56b2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,64 @@ +# siren-php — Agent Instructions + +Read this file at the start of every session. It is deliberately thin: it tells +you where the real context lives, not what the context is. Standards, patterns, +and anti-patterns live in the Navigator knowledgebase, not here. + +## What This Repo Is + +Official Siren SDK for PHP — records commerce and tracking events, verifies +signed webhooks in a constant-time call, manages API keys and webhook +subscriptions, and reconciles Siren's ledger against your own. PHP 8.1+ +library on Guzzle, published to Packagist as `siren/sdk` (MIT). + +- **Initiative:** `siren` (declared in `navigator.yaml`) +- **Repository:** `Novatorius/siren-php` + +## Before Coding: Load the KB Context + +Repo standards live in the Navigator KB, referenced from `knowledgeDependencies` +in `navigator.yaml`. They are not in your training data. + +1. If `.claude/kb-context.md` exists, read it. +2. If it doesn't, generate it, then read it: + +```bash +navigator kb context +``` + +Do not skip this step. For targeted lookups afterwards: + +```bash +navigator kb search "" --initiative=siren --json +navigator kb show +``` + +## Verification + +The `ci` block in `navigator.yaml` is the contract. Run its commands before and +after every change and leave them green: + +```bash +composer install # ci.setup +composer test # ci.test +``` + +What "done" means (PR audit, testing tiers, UAT proof) is defined in the KB: +`global-definition-of-done`. Test-modification rules: +`global-unit-testing-standards-modifying-existing-tests`. Both load via kb context. + +## Session End + +Journal early and often, not just at the end — journals are the update feed; +discovery docs (Navigator sources) hold current state. Conventions live in the +KB: `journaling-at-novatorius` and `discovery-process`. Quick path: the `/log` +skill, or: + +```bash +navigator journal submit "" "" \ + --initiative=siren --tags=siren-php --json +``` + +If this session produced decisions or durable understanding, that is discovery — +capture it per `discovery-process` (journal + charter drafts), don't let it +evaporate into chat history. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5d30268 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +Read AGENTS.md. diff --git a/navigator.yaml b/navigator.yaml new file mode 100644 index 0000000..3270465 --- /dev/null +++ b/navigator.yaml @@ -0,0 +1,15 @@ +initiative: siren +ci: + setup: composer install + test: composer test +knowledgeDependencies: + - initiative: phpnomad + description: "Org-wide engineering doctrine" + critical: + - global-definition-of-done + - global-failure-and-logging-doctrine + - global-unit-testing-standards-modifying-existing-tests + - global-taxonomy-and-sdk-doctrine + - global-integration-testing-standards-introduction + - global-e2e-testing-standards-introduction + - global-pattern-decidability-doctrine From 14fecc26c6c9152e0e93f38f728d3e98b82b4ae3 Mon Sep 17 00:00:00 2001 From: Alex Standiford Date: Sat, 18 Jul 2026 07:07:15 -0400 Subject: [PATCH 2/2] chore: gitignore agent-generated .claude/kb-context.md AGENTS.md instructs agents to generate .claude/kb-context.md via `navigator kb context`. Ignore it so the generated KB-context file (which can contain internal doctrine excerpts) is never accidentally committed to this public SDK repo. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_0138jQKyzwyDfEbbAeMmYNnL --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 3045dac..52c5d9d 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,6 @@ /.phpunit.cache/ .phpunit.result.cache composer.lock + +# Agent-generated KB context (do not commit — see AGENTS.md) +.claude/kb-context.md