docs: initialize ngn-agent project

.planning/PROJECT.md

@@ -0,0 +1,99 @@
+# ngn-agent
+
+## What This Is
+
+ngn-agent is a platform engineering agent powered by Nous Research's Hermes Agent. It manages multi-project infrastructure work through isolated sessions, connects via Telegram gateway, runs commands in Docker containers with limited AWS IAM roles, and persists knowledge across sessions via Hermes' memory system. Designed for platform engineers who manage real infrastructure and need guardrails against accidental mutations.
+
+## Core Value
+
+The agent must NEVER mutate real infrastructure beyond what the limited IAM role permits, while being maximally useful for diagnostics, research, and automation.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] **AUTH-01**: Agent authenticates via AWS Bedrock as primary LLM provider
+- [ ] **AUTH-02**: Agent falls back to OpenRouter when Bedrock is unavailable
+- [ ] **AUTH-03**: Agent uses limited SSO role via project-local `./.aws/` config
+- [ ] **AUTH-04**: Agent runs commands inside Docker containers with host hardening
+- [ ] **AUTH-05**: Hermes persistent memory stores infrastructure facts and user preferences
+- [ ] **AUTH-06**: Hermes session search allows recalling past infrastructure context
+
+- [ ] **GATE-01**: Telegram gateway allows multi-project session management
+- [ ] **GATE-02**: Users interact with the agent via Telegram DMs
+- [ ] **GATE-03**: Pairing-based authorization for new users
+- [ ] **GATE-04**: Scheduled daily reports and stale session cleanup
+
+- [ ] **SKIL-01**: Self-improving skills system with skills hub integration
+- [ ] **SKIL-02**: Infrastructure diagnostic skills (read-only by default)
+- [ ] **SKIL-03**: AWS cost/health/resource querying via read-only tools
+- [ ] **SKIL-04**: Jira and Confluence integration for reporting
+- [ ] **SKIL-05**: Git worktree isolation for parallel branch work
+
+- [ ] **OPS-01**: Minimal dependencies, repeatable setup via single install
+- [ ] **OPS-02**: `.env` file for credential management
+- [ ] **OPS-03**: `~/.aws`: never mounted; `./.aws` with limited role mounted instead
+- [ ] **OPS-04**: Dangerous command approval and hardline blocklist active
+
+### Out of Scope
+
+- Direct `~/.aws` mounting — use scoped `./.aws` instead
+- Full `kubectl exec` / `terraform apply` access without explicit approval gates
+- Non-AWS cloud providers (GCP/Azure) — defer to future
+- Native mobile app — Telegram gateway is the mobile interface
+- Self-hosted model serving — use Bedrock/OpenRouter
+
+## Context
+
+- **Base tool**: Nous Research Hermes Agent (Python/uv, MIT)
+- **Runtime**: macOS (Orbstack for Docker), CLI-only install (no Desktop)
+- **LLM**: AWS Bedrock (primary) via boto3 SSO auth → OpenRouter (fallback)
+- **Terminal backend**: Docker with hardened security (--cap-drop ALL, no-new-privileges)
+- **Memory**: Hermes persistent memory (MEMORY.md + USER.md) + FTS5 session search
+- **Credentials**: `./.aws/` with limited IAM role mounted read-only into Docker; `~/.hermes/.env` for OpenRouter key
+- **AWS auth**: SSO role chaining with cached session (~7 day refresh), browser login on expiry
+- **Project location**: `/Users/bapung/Razer/ngn-agent`
+
+## Constraints
+
+- **Security**: Agent must run inside Docker with limited capabilities
+- **Credential**: Only scoped AWS role — never raw admin access
+- **Auth**: Bedrock uses boto3 chain (SSO); no API key for primary provider
+- **Provider**: OpenRouter key in `.env` for fallback only
+- **Git**: Worktree-based isolation; pushes only to feature branches
+- **Gateway**: Telegram as primary messaging channel
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Hermes Agent over NanoClaw | Superior memory system (auto-learning, session search, 8 external providers) | ✓ Good |
+| Bedrock primary + OpenRouter fallback | Zero additional API cost for primary (uses existing AWS SSO); OpenRouter as reliability layer | — Pending |
+| Docker backend | Container isolation is the security boundary; dangerous command checks skipped | — Pending |
+| Project-local `./.aws` | Prevents privileged credentials from entering container | — Pending |
+| CLI-only install | Desktop not needed; minimal surface area | — Pending |
+| Git worktree isolation | Prevents branch contamination across sessions | — Pending |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd-transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd-complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-06-14 after initialization*