@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/skills/nsr-compliance/assets/nsr/assets/docs/working-with-agents.md

@@ -0,0 +1,260 @@
+# Working with Agents — Comprehensive Guide for Way-Of Teams
+
+> **Status:** Research-informed practice doc (`docs/research/`)
+> **Based on:** software-compliance research — full sources in `docs/research/software-compliance-research.md`.
+> **Companion:** `docs/research/agents-workflow.md` — the day-to-day workflow this guide feeds into.
+> **Applies to:** every Way-Of project following the NSR ruleset, and to how engineers + agents + automation cooperate.
+
+This is the operating manual for working **with** agent systems: the mental model, the architecture, the verification discipline, the economics, and the guardrails — grounded in the software-compliance research. The workflow *process* is documented separately in `docs/research/agents-workflow.md`.
+
+---
+
+## 1. What You Are Actually Building
+
+A **software compliance** is an agentic system that takes a specification and produces working, deployed, tested software with minimal intervention. It is **not** a chat — it is a **continuous feedback loop**:
+
+> "A pipeline runs once. A compliance learns." — mager.co
+
+There is a **maturity ladder** (widely adopted, from mager.co / Dan Shapiro):
+
+| Level | What it is |
+|-------|-----------|
+| **L0** | Autocomplete |
+| **L1** | Chat-to-code |
+| **L2** | File-aware coding agents |
+| **L3** | Multi-agent pipelines |
+| **L4** | Software compliance — autonomous build-test-deploy loops |
+| **L5** | "Dark compliance" — no human on the floor (Fanuc lights-out model) |
+
+A key distinction: an **AI compliance** (NVIDIA) manufactures *tokens* on GPUs. A **software compliance** **spends** tokens to produce software. Don't conflate the two.
+
+**In NSR terms** the ruleset is designed to operate at **L4** (with L5 guardrails): deterministic harness owns the process, agents are bounded workers, gates decide acceptance, and telemetry feeds the loop.
+
+---
+
+## 2. The Three-Actor Model: Engineer, Code, Agents
+
+From disler/IndyDevDan's Super Simple Software Compliance, keep **three actors** separate and use each at the right moment:
+
+| Actor | Strength | When to use |
+|-------|----------|-------------|
+| **The Engineer (you)** | Defining intent, trade-offs, review, approval | Start (scope/acceptance) and end (approve/merge) |
+| **The Code (determinism)** | Tests, lint, migrations, git, arithmetic, orchestration | Whenever the step is *known* — never pay an agent to do arithmetic |
+| **The Agents (LLMs)** | Reading, deciding, drafting, exploring unknown code | Steps needing judgment over unstructured content |
+
+> "The trick is not running more agents. The trick is using all three at the right moment." — disler/SSSF
+
+**Rule of thumb:** if the task can be a script (`test`, `lint`, `migrate`, `commit`), it **must** be a script — you "stop paying an agent to do arithmetic." Agents handle only what needs reading and deciding.
+
+---
+
+## 3. The Architecture: Deterministic Code Owns the Graph
+
+> "Deterministic Python owns the graph. Coding agents are bounded nodes inside it. An ADW script owns sequencing, retries, and acceptance. Agents work inside named phases. Typed JSON envelopes carry context across the seams. Every event streams into SQLite while it is still happening. **Agent proposes, code disposes.**" — disler/SSSF
+
+Break this down into concrete rules:
+
+1. **Sequencing, retries, acceptance = code.** The harness (`.compliance/harness/runner.py`) or an ADW-style script owns the run, not the agent's whim.
+2. **Agents are bounded nodes.** An agent works inside **one named phase**, produces its output, hands off — it never drives the whole run.
+3. **Context transfers in code, not conversation.** Agents write reference files into a `context_handoff/` or emit a final valid-JSON response parsed against a typed output (an envelope); code persists it (`envelope.json`) and injects it into the next agent's prompt. This kills the "game of telephone."
+4. **Agent proposes, code disposes.** An agent may *propose* a commit message on its envelope; the `git commit` **code phase** decides and writes. The agent never runs `git commit` itself.
+
+**In NSR terms:** this is `.compliance/harness/envelopes/` (typed JSON/YAML handoffs), `.compliance/gates/` (`$? == 0`), `.agents/skills/` (every operation is a bounded script), and the "zero ad-hoc shell commands" rule.
+
+---
+
+## 4. Orchestrator–Worker: The Dominant Pattern
+
+Anthropic's production multi-agent research system validated the dominant architecture:
+
+> "An orchestrator-worker pattern, where a lead agent coordinates the process while delegating to specialized subagents that operate in parallel."
+
+The orchestrator:
+- Breaks a task into **bounded, typed subtasks**.
+- Routes each to a specialized worker (architect, coder, reviewer, tester, documenter, deployer).
+- Holds state and re-collects results.
+
+**Critical caveats from Anthropic (design constraints, not optional):**
+
+- Multi-agent systems use **~4× more tokens** than single chat; some architectures **~15× more**. Agents "burn through tokens fast."
+- **"Most coding tasks involve fewer truly parallelizable tasks than research"** — do not fan out agents for the sake of it. Parallelize only genuine independent work.
+- Each subagent needs: **objective, output format, tool/source guidance, and clear task boundaries**.
+- Agents should write artifacts to the filesystem and pass **lightweight references** back (not giant context blobs).
+
+**Cost control pattern:** move known work (tests, lint) into **code phases**; reserve agents for the judgment-heavy parts. This is exactly the disler design and the NSR rule "everything via scripts."
+
+---
+
+## 5. The Task Packet: Standardize the Unit of Work
+
+Every agent gets a **compliance-ready task packet** (from Cole Murray's practitioner guide). In NSR this is the **typed envelope** (`.compliance/harness/envelopes/`) — if it doesn't fit the envelope, it isn't ready to dispatch:
+
+| Field | What it holds |
+|-------|---------------|
+| **Objective** | What must be achieved. |
+| **Non-goals** | Explicitly what it must NOT do. |
+| **Context** | Pointers to files/slices — not the whole repo. |
+| **Acceptance criteria** | How the result will be judged. |
+| **Capabilities** | Allowed tools, scripts, and paths. |
+| **Checks** | Which gates run against its output. |
+| **Terminal states** | `complete` / `retry` / `no-op` / `escalate`. |
+| **Evidence** | Artifacts and exit codes it must produce. |
+| **Rollback** | How to undo if it goes wrong. |
+
+Envelope example (disler, Pydantic-style):
+
+```python
+class EnvelopeBase:
+    status: "success" | "fail"
+    summary: str
+    artifacts: list[str]
+    notes_for_next_agent: str
+
+class BuildOutput(EnvelopeBase):
+    changed_files: list[str]
+    commit_message: str   # consumed by the git commit code phase
+```
+
+---
+
+## 6. Verification Is the Bottleneck — Not Generation
+
+The consensus across practitioners (Cole Murray, StrongDM, Plannotator, Compliance.ai):
+
+> Generation is cheap. **Your ceiling is how fast and how trustworthily you can verify output.** The bottleneck is almost always verification, not generation.
+
+Operational consequences:
+
+- **Gates verify claims, never predictions.** "Success must be earned. Every phase defaults to `fail`." — disler/SSSF
+- Gate types: `artifacts_exist`, `files_non_empty`, `json_parses`, `diff_matches_claims`, `tests_pass(...)`. A gate is `gate(envelope, run) -> GateReport`.
+- **The quality signal cannot be the same model that did the work.** An agent grading its own homework is too lenient. Use an independent deterministic check (tests, lint) or a different model.
+- **Back-pressure before review.** Linters, hooks, and static analysis run *inside* the sandbox so agents see and fix failures **before** the PR — "Left alone, an agent will confidently produce code that doesn't meet your standards."
+- **Visible failure is your friend; silent failure is the enemy.** A capped conversation, an unexercised test, a check that passed for the wrong reason — all silent failures. Make them loud.
+
+**In NSR terms:** `.compliance/gates/` (check_env, check_paths, check_platform, verify_docs, validate_code) run before commit and before deploy, judged by `$? == 0`.
+
+---
+
+## 7. The Feedback Loop Makes It a Compliance
+
+> "A pipeline runs once. A compliance learns." — mager.co
+
+```
+Signals → Triage → Plan → Build → Test → Review → Secure → Ship → Monitor → (new Signals)
+```
+
+Three loop behaviors matter:
+
+1. **Repair, don't restart.** When JSON doesn't parse or a gate fails: *nothing restarts.* The harness **re-prompts the same session** with a correction naming exactly what was wrong, and the context window stays intact. One correction = one message, not a cold start.
+2. **Monitoring feeds the queue.** Alerts/dashboards produce new signals that re-enter triage as tickets.
+3. **Measure to improve.** "If you cannot measure your agents, you cannot improve them." Every event streams to the telemetry store (`logger.py` / SQLite) — phases, events, envelopes, gate results, agent sessions.
+
+**Four observable properties of a working compliance** (Compliance.ai): standardized inputs, standardized tooling, measurable output, replayability.
+
+---
+
+## 8. Match Autonomy to Blast Radius
+
+Trust is earned in stages (the trust ladder seen across Cursor, Stripe, Harvey, StrongDM):
+
+| Blast radius | Suggested autonomy |
+|--------------|--------------------|
+| Read-only / research | Full autonomy |
+| Draft PRs / low-risk code | Auto-generate, human review |
+| Small scoped refactors, low-risk PRs | Auto-merge with gates + review |
+| Production / per-client / multi-tenant deploys | Full gates **+ human go/no-go gate** |
+
+> The field genuinely disagrees on whether review stays human or becomes automated — but the safe default is **match autonomy to blast radius.**
+
+Industry-landscape reality check (self-reported numbers — treat as promotional, not comparable):
+- Stripe: 1,300+ agent PRs/week, still human-reviewed.
+- Cursor: ~40% of internal PRs.
+- Uber Minion: ~11% of PRs.
+- Ramp Inspect: >50% of PRs.
+- Ona: 375 PRs in 10 days.
+- StrongDM: runs a **dark compliance** (no human review; validate purely by observable behavior).
+- Cost: ~$1,000/day per engineer in tokens (StrongDM-reported).
+
+---
+
+## 9. Guardrails: Costs, Loops, Credentials, Quality
+
+| Pitfall | Mitigation (NSR) |
+|---------|------------------|
+| **Token explosion** (~4× chat, ~15× multi-agent) | Move known work into code phases; effort budgets per phase; parallelize only genuine independent work |
+| **Agent loops / spiraling** | Bounded phases, retry caps, terminal states (`no-op`/`escalate`) |
+| **Hallucinated commands** | Zero ad-hoc shell commands — all ops via `.agents/skills/` scripts |
+| **Cost explosion** | Telemetry (`logger.py`), budgets, spend metering per phase |
+| **Code-quality erosion / "velocity theater"** | Structural gates, review by risk tier, one primary stack per feature (GitClear: more duplicate code & churn as AI code grows) |
+| **Credential exfiltration** | Secrets live in the control plane (`.compliance/`, env/secret manager) — never in the agent sandbox; secrets never committed |
+| **Self-graded homework** | Gates + tests independent of the producing agent |
+| **Prompt-injectable agents** | An agent that can be prompt-injected will eventually exfiltrate whatever credentials it can reach — keep credentials out of the sandbox |
+| **Overstated maturity** | "Repeatable inputs do not guarantee good intent. More autonomy ≠ lower cost or higher quality." (Plannotator) |
+
+---
+
+## 10. Model Selection per Phase (Core Four)
+
+> "It is not about which model is best anymore; it is about which model is right for that one phase." — disler/SSSF
+
+- **Fast/cheap model** for coding, tool calls, routine edits.
+- **Larger reasoning model** for planning, architecture, deep debugging.
+- Configure in `core_four.yaml` (**Context / Model / Prompt / Tools**); the harness reads it per phase.
+- Different models at different price/speed points can run **in the same run**.
+- Agent roster declares: `model` (provider/model-id), `thinking` level, `purpose`, prompt files, tools, and a `writes` boundary (which files it may touch — a scope guard).
+
+---
+
+## 11. Seams & Infrastructure
+
+- **MCP servers** standardize external tool access. Tool descriptions vary wildly in quality — centralize tool registration, auth, guardrails, and observability (NSR: `.compliance/` control plane; the embedded compliance skill's telemetry + WayOfTeams sync).
+- **Agent/skill registries** index capabilities so agents can discover them (NSR: `.agents/skills/`).
+- **Task queues / packets** are the standardized units of work entering the line.
+- **CI/CD feedback loops** re-enter failing work; monitor alerts spawn incident agents.
+- **Telemetry boundary**: agents write events; humans/dashboards poll them. One data path, no exceptions.
+
+---
+
+## 12. The NSR Working-with-Agents Playbook
+
+A concrete, per-task checklist:
+
+1. **Open an envelope** — objective, non-goals, acceptance, capabilities, checks, evidence, rollback (typed JSON/YAML).
+2. **Check `FEATURES.md`** — is this already built? Don't duplicate.
+3. **Route to a feature skill** — pick the phase and the feature's `.agents/skills/features/<feature>/` scripts.
+4. **Let code own the run** — the harness sequences; gates decide (`$? == 0`); agents stay in their phase.
+5. **Verify independently** — run gates + tests; another model or a deterministic check judges the result.
+6. **Log it** — telemetry records tokens, latency, tool calls, cost for that phase.
+7. **Review by blast radius** — dev loop can auto-merge; production requires the human gate.
+8. **Feed the loop** — test failures re-trigger the same agent; incidents become new tickets.
+
+---
+
+## 13. One-Line Rules to Remember
+
+- Agents read and decide; code sequences and verifies.
+- If it can be a script, it must be a script.
+- Context moves in envelopes, not conversation.
+- Success must be earned; every phase defaults to fail.
+- Verify with something independent of the producer.
+- Autonomy = f(blast radius).
+- Measure agents, or you can't improve them.
+- Make failure visible.
+- Repairs re-prompt the same session; they never restart cold.
+- Vibe coding is not knowing how your system works, and not looking. Agentic engineering is knowing how your system works so well you don't have to look.
+
+---
+
+## 14. Sources
+
+- disler / IndyDevDan — Super Simple Software Compliance: https://github.com/disler/super-simple-software-compliance
+- INDY DevDan breakdown: https://www.youtube.com/watch?v=haUfb1ievTE
+- Anthropic — multi-agent orchestration: https://www.anthropic.com/engineering/built-multi-agent-research-system
+- Cole Murray — software compliance guide: https://murraycole.com/posts/software-compliance
+- mager.co — Software Compliance: The End Goal of Agentic Engineering: https://www.mager.co/blog/2026-03-19-software-compliance/
+- Compliance.ai — Inside the software compliance: https://compliance.ai/articles/what-is-a-software-compliance
+- Plannotator — what is an AI software compliance: https://docs.plannotator.ai/learn/ai-development/what-is-an-ai-software-compliance
+- StrongDM — dark compliance: https://www.strongdm.com/blog/the-strongdm-software-compliance-building-software-with-ai
+- TrueFoundry — agentic enterprise guide / MCP gateway: https://www.truefoundry.com/blog/software-compliance-agentic-enterprise-guide
+- GitClear — AI code quality research: https://www.gitclear.com/ai_assistant_code_quality_2025_research
+- Wikipedia — Software compliance (history): https://en.wikipedia.org/wiki/Software_compliance

package/.agents/skills/nsr-compliance/assets/nsr/assets/root/AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md — __PROJECT__
+
+__DESCRIPTION__. This file is the fluff-free router — read the referenced docs before acting.
+
+## Routing
+
+- **`WayOfNorthstarRules.md`** — the canonical ruleset every project follows. Read first.
+- **`ARCHITECTURE.md`** — system overview.
+- **`STRUCTURE.md`** — repo tree map. Use it to find files without guessing.
+- **`FEATURES.md`** — master feature registry (prevents duplication).
+- **`TECH_STACK.md`** — what stack to use for what feature.
+- **`RULES.md` / `RULES/`** — execution rules index + detail.
+- **`docs/HOSTING/`** — hosting core info; never break production.
+- **`docs/DEVELOPER_SETUP/`** — developer core setups.
+- **`docs/CI_CD/deployment/`** — envs, per-client, per-tenant deployment configs.
+- **`docs/working-with-agents.md`** — operating manual: how to work with agents.
+- **`docs/project-skills.md`** — every skill this project ships (compliance-ready checklist).
+
+## Core Rules
+
+1. **Zero ad-hoc shell commands** — all operations via `.agents/skills/` scripts. No raw `npm test`, `git commit -m ...`, `kill -9`.
+2. **Env-driven config** — no hardcoded values; everything from `.env`/secret manager; secrets never committed.
+3. **Multi-deployment** — env tiers, per-client deployments, shared multi-tenant instances.
+4. **Relative paths only** — repo-root-relative; absolute paths forbidden (gated).
+5. **Cross-platform** — Mac, Linux, Windows (WSL/Git Bash); POSIX scripts.
+6. **Subfolder `AGENTS.md`** — every functional subfolder defines scoped rules.
+7. **No feature duplication** — register in `FEATURES.md`, ship scripts under `.agents/skills/features/<feature>/`.
+8. **Deterministic gates** — pass/fail by exit code (`$? == 0`), never text parsing.
+9. **Hosting & developer docs** — production hostings (`docs/HOSTING/`) and developers (`docs/DEVELOPER_SETUP/`) always documented.
+10. **Tech-stack discipline** — use `TECH_STACK.md`; one primary stack per feature.
+
+## Workflow
+
+1. Start at `STRUCTURE.md` to locate code; check `FEATURES.md` before building.
+2. Read `docs/working-with-agents.md` before dispatching any agent.
+3. Run operations via `.agents/skills/` scripts (lifecycle, git_ops, feature skills).
+4. Configure env via `docs/CI_CD/deployment/envs/*.env.example` → `.env`.
+5. Pass all gates (`.compliance/gates/*`) before committing or deploying.

package/.agents/skills/nsr-compliance/assets/nsr/assets/root/ARCHITECTURE.md

@@ -0,0 +1,36 @@
+# Architecture — __PROJECT__
+
+High-level system overview. Detail lives in `docs/` and `docs/features/`.
+
+## System Layers
+
+```
+             CLIENTS / TENANTS
+                   │
+        ┌──────────┴───────────┐
+        │  API / Services      │
+        │  Frontend / Apps     │
+        └──────────┬───────────┘
+                   │
+             ┌─────┴─────┐
+             │   Data    │
+             │   (DB)    │
+             └───────────┘
+```
+
+## Components
+
+- **API / services** — see `TECH_STACK.md` for the stack.
+- **Frontend / apps** — see `TECH_STACK.md`.
+- **Data layer** — schema, migrations, seed.
+- **Deployments** — see `docs/CI_CD/deployment/` (envs, clients, tenants) and `docs/HOSTING/`.
+
+## Multi-Tenancy
+
+- Tenant identity is dynamic (per-request), isolated at runtime.
+- Per-client deployments (`docs/CI_CD/deployment/clients/<client>/`) are isolated.
+- Shared multi-tenant instances isolate data by tenant at runtime.
+
+## Detail
+
+Deep-dive specs live in `docs/` — `docs/features/` for features, `docs/research/` for background.

package/.agents/skills/nsr-compliance/assets/nsr/assets/root/BEST_PRACTICES.md

@@ -0,0 +1,27 @@
+# Best Practices
+
+Code quality, patterns & design guidelines index. Category-specific standards live in `docs/BEST_PRACTICES/` — this file is the index.
+
+## Categories (`docs/BEST_PRACTICES/`)
+
+| File | Status | Domain |
+|------|--------|--------|
+| `api.md` | 🚧 Planned | REST/API design, versioning, error handling |
+| `state-management.md` | 🚧 Planned | State patterns, immutability, data flow |
+| `code-quality.md` | 🚧 Planned | Lint rules, naming, review checklists |
+| `compliance-wiring.md` | ✅ Built | How to wire the compliance to a project's real procedures (start/stop/test/deploy per stack) |
+
+## Cross-Cutting Practices
+
+- **Deterministic operations** — every action is a script in `.agents/skills/`; nothing is typed ad-hoc.
+- **Exit-code discipline** — automation is judged by `$? == 0`, never by parsing text output.
+- **Typed handoffs** — inter-agent communication uses JSON/YAML envelopes, not unstructured summaries.
+- **Observability first** — every agent phase logs tokens, latency, tool calls, and cost.
+- **Thin context routing** — agents ingest root routing files + subfolder `AGENTS.md` only; detail lives in sub-docs.
+- **Doc-driven navigation** — use `STRUCTURE.md` to find files and `FEATURES.md` to avoid duplicate work.
+- **Environment-driven everything** — no hardcoded config; inject via `.env`/secret manager; `.env.example` templates only.
+- **Multi-tenant discipline** — tenant isolation at runtime; client identity is an env input, never baked into shared code.
+- **Relative-path hygiene** — paths resolve from repo root; absolute paths are rejected by `check_paths.sh`.
+- **Platform portability** — POSIX bash, forward slashes, LF endings (Mac/Linux/Windows) — validated by `check_platform.sh`.
+- **Stack consistency** — follow `TECH_STACK.md`; one primary stack per feature; pin versions.
+- **Docs-before-production** — every hosting (`docs/HOSTING/`) and developer (`docs/DEVELOPER_SETUP/`) documented before going live.

package/.agents/skills/nsr-compliance/assets/nsr/assets/root/CI_CD.md

@@ -0,0 +1,23 @@
+# CI/CD — __PROJECT__
+
+Pipeline overview. Detail in `docs/CI_CD/`.
+
+## Stages
+
+1. **Build** — validate structure & docs.
+2. **Test** — run gates + scripted test suites.
+3. **Release** — versioning & promotion.
+4. **Deploy** — env-driven rollout per env tier, per client, per tenant (`docs/CI_CD/deployment/`).
+
+## Compliance Gates
+
+- `.compliance/gates/check_env.sh` — required env vars present.
+- `.compliance/gates/check_paths.sh` — no absolute paths.
+- `.compliance/gates/check_platform.sh` — POSIX-portable.
+- `.agents/skills/NSRcompliance/gates/verify_docs.py` — docs in sync.
+- `.agents/skills/NSRcompliance/gates/validate_code.sh` — runs all gates; `$? == 0`.
+
+## Rules
+
+- CI never hardcodes values or secrets; deploy via `deploy.sh --env <env> --target <client|tenant>`.
+- Every deploy runs `check_env.sh → check_paths.sh → check_platform.sh` then `validate_code.sh` before production.

package/.agents/skills/nsr-compliance/assets/nsr/assets/root/FEATURES.md

@@ -0,0 +1,15 @@
+# Features — __PROJECT__
+
+Master registry. No feature may be implemented without being registered here, and every registered feature ships automation under `.agents/skills/features/<feature>/`.
+
+## Registered Features
+
+| Status | Feature | Description | Skill Dir |
+|--------|---------|-------------|-----------|
+| 🚧 Planned | *(add feature)* | *(description)* | `.agents/skills/features/<feature>/` |
+
+## Rules
+
+- Every feature has a matching skill directory under `.agents/skills/features/`.
+- Every feature maps to a stack in `TECH_STACK.md`.
+- Keep in sync via `.compliance/gates/verify_docs.py`.

package/.agents/skills/nsr-compliance/assets/nsr/assets/root/README.md

@@ -0,0 +1,22 @@
+# __PROJECT__
+
+__DESCRIPTION__.
+
+Built by a distributed team on Mac, Linux, and Windows, shipped via the WayOfNorthStar ruleset.
+
+## Quick Start
+
+1. Read `AGENTS.md` → `ARCHITECTURE.md` → `STRUCTURE.md`.
+2. Copy `docs/CI_CD/deployment/envs/development.env.example` → `.env`; inject values.
+3. Start: `.agents/skills/lifecycle/start.sh`.
+4. Verify: `.compliance/gates/check_env.sh`, `check_paths.sh`, `check_platform.sh`.
+
+## Docs
+
+- Features: `FEATURES.md` + `docs/features/`
+- Hosting: `docs/HOSTING/`
+- Developer setup: `docs/DEVELOPER_SETUP/`
+- Stack mapping: `TECH_STACK.md`
+- Deployments: `docs/CI_CD/deployment/`
+- Work with agents: `docs/working-with-agents.md`
+- Project skills: `docs/project-skills.md`

package/.agents/skills/nsr-compliance/assets/nsr/assets/root/RULES.md

@@ -0,0 +1,37 @@
+# Rules — __PROJECT__
+
+Core enforcement & execution rules. Detail lives in `RULES/`.
+
+## Non-Negotiable Core Rules
+
+1. **Dual-layer docs** — root routing files are fluff-free; detail in `RULES/` and under `docs/`.
+2. **Zero ad-hoc shell commands** — every op via `.agents/skills/` scripts.
+3. **Env-driven config** — no hardcoded values; secrets never committed.
+4. **Multi-deployment + multi-tenant** — env tiers, per-client, shared tenants.
+5. **Relative paths only** — gated by `check_paths.sh`.
+6. **Cross-platform** — POSIX, forward slashes, LF; gated by `check_platform.sh`.
+7. **Deterministic harness** — Core Four config, `$? == 0` gates, typed envelopes, telemetry.
+8. **No feature duplication** — `FEATURES.md` registry + skill dirs.
+9. **Subfolder `AGENTS.md`** — scoped boundaries per folder.
+10. **Hosting/developer docs** — `docs/HOSTING/`, `docs/DEVELOPER_SETUP/` always current.
+11. **Tech-stack discipline** — `TECH_STACK.md`, one primary stack per feature.
+12. **Work with agents per `docs/working-with-agents.md`** — bounded nodes, code owns the graph.
+13. **Ship the `docs/project-skills.md` skill set** before compliance-ready.
+
+## Rule Files (`RULES/`)
+
+| File | Status | Domain |
+|------|--------|--------|
+| `security.md` | ✅ | Access control, secrets, tenant isolation |
+| `git-workflow.md` | ✅ | Branching, commits, PR gate |
+| `tech-stack.md` | ✅ | One primary stack per feature, pinned versions |
+
+## Mandatory Script Domains (per feature)
+
+| Domain | Files | Responsibility |
+|--------|-------|----------------|
+| Lifecycle | `start.sh`, `stop.sh`, `status.sh` | Predictable spin-up/teardown |
+| Testing | `test.sh`, `smoke_test.sh` | Targeted suites + smoke checks |
+| Data & Setup | `setup.sh`, `seed.sh`, `migrate.sh` | Deterministic state prep |
+| Source Control | `safe_commit.sh`, `sync.sh` | Safe git operations |
+| Diagnostics | `audit.sh`, `logs.sh` | Health & telemetry |

package/.agents/skills/nsr-compliance/assets/nsr/assets/root/STRUCTURE.md

@@ -0,0 +1,45 @@
+# Structure — __PROJECT__
+
+Repository tree map. Use this to navigate directly without unguided searching.
+
+```
+├── AGENTS.md                 # Root routing & core rules (fluff-free)
+├── ARCHITECTURE.md           # High-level system overview
+├── STRUCTURE.md              # This file — tree map
+├── FEATURES.md               # Master feature registry
+├── RULES.md                  # Execution rules index (detail in RULES/)
+├── BEST_PRACTICES.md         # Design guidelines index (detail in docs/BEST_PRACTICES/)
+├── CI_CD.md                  # Pipeline overview (detail in docs/CI_CD/)
+├── TECH_STACK.md             # Stack-to-feature mapping
+├── README.md                 # Product overview
+│
+├── RULES/                    # Execution & domain rules
+├── docs/                     # Granular documentation
+│   ├── BEST_PRACTICES/       # Engineering standards
+│   ├── CI_CD/                # Pipeline configs + deployment/
+│   │   └── deployment/       # envs/, clients/, tenants/, deploy.sh
+│   ├── DEVELOPER_SETUP/      # Per-developer setup (consolidated + developers/)
+│   ├── HOSTING/              # Per-hosting core info (consolidated + per-host)
+│   ├── RUNBOOK/              # deployment.md, disaster-recovery.md, ops-tasks.md
+│   ├── features/             # Per-feature deep-dive specs
+│   └── research/             # Research sources
+│
+├── src/                      # Application source (add as needed)
+├── tests/                    # Test suites (invoked via .agents/skills)
+│
+├── .agents/
+│   └── skills/               # Scripted automation layer
+│       ├── lifecycle/        # start.sh, stop.sh, status.sh, smoke_test.sh
+│       ├── git_ops/          # create_branch.sh, safe_commit.sh, sync_upstream.sh
+│       ├── features/         # <feature>/ (setup, test, smoke_test, rollback)
+│       └── compliance/          # Embedded Agent Skill Compliance
+│
+└── .compliance/                 # Deterministic harness engine
+    ├── config/               # core_four.yaml
+    ├── gates/                # check_env.sh, check_paths.sh, check_platform.sh
+    ├── harness/              # runner.py + envelopes/
+    ├── telemetry/            # logger.py
+    └── installer/            # install.sh
+```
+
+**Directory rule:** every functional subfolder must contain a local `AGENTS.md`.

package/.agents/skills/nsr-compliance/assets/nsr/assets/root/TECH_STACK.md

@@ -0,0 +1,28 @@
+# Tech Stack — __PROJECT__
+
+Authoritative stack-to-feature mapping. One primary stack per feature; pin versions.
+
+## Stack Registry
+
+| Layer | Technology | Version | Used For |
+|-------|-----------|---------|----------|
+| Language | *(fill)* | | |
+| Backend framework | *(fill)* | | |
+| Frontend framework | *(fill)* | | |
+| Database | *(fill)* | | |
+| Cache | *(fill)* | | |
+| Auth | *(fill)* | | |
+| Container | Docker | 24.x | Runtime, CI |
+| Observability | *(fill)* | | |
+
+## Feature → Stack Mapping
+
+| Feature | Stack | Constraints |
+|---------|-------|-------------|
+| *(feature)* | *(stack)* | *(constraints)* |
+
+## Rules
+
+- Pin versions; no floating/latest in production.
+- No new stack without updating this file AND `FEATURES.md`.
+- Stacks must run on Mac/Linux/Windows (or be containerized).

package/.agents/skills/nsr-compliance/assets/nsr/scaffold-spec.md

@@ -0,0 +1,63 @@
+---
+name: NSR
+description: Scaffold and validate a new Way-Of NorthStar (NSR) complaint repository/project. Use when creating a new project/repo, converting an existing repo to the NorthStar layout, or auditing a repo for NSR compliance. Installs the full dual-layer docs layout, .agents/skills automation layer, and .compliance deterministic harness, then runs compliance gates.
+allowed-tools:
+  - run_shell_command
+  - run_bash_command
+  - edit
+  - write
+---
+
+# SKILL.md — NSR (WayOfNorthStarRules)
+
+**Scaffold new projects and audit existing ones against the WayOfNorthStar Ruleset.**
+
+The skill is self-contained: it carries every template (`assets/`) and every automation script (`scripts/`) needed to create a fully compliant NSR repository and gate it.
+
+## When to Use
+
+1. **Creating a new project** — from a blank folder to a complete NSR repo.
+2. **Converting a legacy repo** — adopt the NorthStar layout + harness onto an existing codebase.
+3. **Auditing compliance** — run the gates and report what's missing.
+
+## Key Files
+
+- `WayOfNorthstarRules.md` — the master spec (source of truth). Read before scaffolding when a rule is in question.
+- `assets/root/` — root routing file templates (AGENTS.md, ARCHITECTURE.md, STRUCTURE.md, FEATURES.md, RULES.md, BEST_PRACTICES.md, CI_CD.md, TECH_STACK.md, README.md, .gitignore).
+- `assets/RULES/` — execution & enforcement rule templates (kept at root).
+- `assets/docs/` — the granular docs tree (BEST_PRACTICES, CI_CD, DEVELOPER_SETUP, HOSTING, RUNBOOK, features, research).
+- `assets/agents_skills/` — the `.agents/skills/` automation layer templates (incl. the self-contained compliance skill that generates `.compliance/`).
+- `assets/compliance/` — legacy `.compliance/` template tree (fallback stamp; the compliance skill's `generate.sh` is canonical).
+- `scripts/` — scaffold.sh (create/convert), validate.sh (audit).
+
+## Workflow
+
+1. **Confirm scope** — new blank project, or conversion of an existing repo?
+2. **Run the scaffolder:**
+   ```bash
+   .agents/skills/NSR/scripts/scaffold.sh /path/to/project --name "ProjectName" --description "What it does"
+   ```
+   - Creates the full NSR tree from templates (project name/description substituted).
+   - Installs `.agents/skills/` and generates `.compliance/` via the compliance skill (`generate.sh`), with runnable gates + `WIRE ME` stub scripts.
+   - Runs `validate.sh` as a post-condition.
+3. **Convert existing repo (optional):** run the same scaffolder over the existing repo — it creates only missing folders/files and never overwrites existing ones.
+4. **Author the skill layer** — fill feature dirs under `.agents/skills/features/<feature>/` for every feature in FEATURES.md (setup/test/smoke_test/rollback stubs are provided).
+5. **Wire the compliance to the project** — replace `WIRE ME` stubs in `.agents/skills/lifecycle/` and per feature with the app's real commands (delegate + protect; never rewrite). Add `# gate: dev|guard|human` to destructive scripts. Prove it: `.compliance/gates/check_wiring.sh --strict` and `.compliance/gates/check_danger.sh`. Walkthrough: `docs/BEST_PRACTICES/compliance-wiring.md`.
+6. **Configure environments** — create `.env.example` templates for env tiers, per-client, and tenant deployments under `docs/CI_CD/deployment/`.
+7. **Document hosting & developers** — fill `docs/HOSTING/` and `docs/DEVELOPER_SETUP/` (one explicit doc per hosting & per developer).
+8. **Audit:**
+   ```bash
+   .agents/skills/NSR/scripts/validate.sh /path/to/project
+   ```
+   Runs every gate (env, paths, platform, docs, structure) and reports pass/fail.
+
+## Referenced Rules (Non-Negotiable)
+
+- Root routing files are fluff-free; ALL granular detail lives under `docs/` (only `RULES/` stays at root).
+- Zero ad-hoc shell commands — all ops via `.agents/skills/` scripts.
+- Env-driven config — no hardcoded values, secrets never committed.
+- Multi-deployment (env tiers + per-client + multi-tenant).
+- Relative paths only (gated); cross-platform Mac/Linux/Windows (gated).
+- Every hosting (`docs/HOSTING/`) and every developer (`docs/DEVELOPER_SETUP/`) documented.
+- TECH_STACK.md maps every feature to a pinned stack.
+- Deterministic gates pass/fail by exit code (`$? == 0`).