docs: initialize ngn-agent project

.planning/REQUIREMENTS.md

@@ -0,0 +1,96 @@
+# Requirements: ngn-agent
+
+**Defined:** 2026-06-14
+**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.
+
+## v1 Requirements
+
+### Authentication & Provider
+
+- [ ] **AUTH-01**: Agent authenticates via AWS Bedrock as primary LLM provider using boto3 SSO auth chain
+- [ ] **AUTH-02**: Agent falls back to OpenRouter when Bedrock encounters errors (rate limits, 5xx, auth failures)
+- [ ] **AUTH-03**: Project-local `./.aws/` config with limited SSO role mounted read-only into Docker container
+- [ ] **AUTH-04**: SSO token refresh handled via AWS SDK cached registration (~7 day validity); browser login on expiry
+- [ ] **AUTH-05**: OpenRouter API key stored in `~/.hermes/.env`
+
+### Container & Security
+
+- [ ] **CONT-01**: Hermes configured with Docker terminal backend
+- [ ] **CONT-02**: Docker container runs with `--cap-drop ALL`, `--security-opt no-new-privileges`, PID limits
+- [ ] **CONT-03**: `./.aws/` mounted into container as read-only volume
+- [ ] **CONT-04**: AWS_PROFILE=limited environment variable set in container
+- [ ] **CONT-05**: Hermes dangerous command approval enabled with manual or smart mode
+- [ ] **CONT-06**: Hardline blocklist protects against catastrophic commands
+
+### Memory & Knowledge
+
+- [ ] **MEM-01**: Hermes persistent memory (MEMORY.md + USER.md) stores infrastructure facts
+- [ ] **MEM-02**: Agent proactively saves environment facts and conventions
+- [ ] **MEM-03**: Session search available for recalling past infrastructure context
+- [ ] **MEM-04**: Git worktree isolation enabled for parallel branch work
+
+### Gateway
+
+- [ ] **GATE-01**: Telegram gateway configured and connected
+- [ ] **GATE-02**: Pairing-based authorization for new users
+- [ ] **GATE-03**: Scheduled daily reports and stale session cleanup
+
+### Skills
+
+- [ ] **SKIL-01**: Skills system operational with Hermes Skills Hub integration
+- [ ] **SKIL-02**: Read-only infrastructure diagnostic skills operational
+- [ ] **SKIL-03**: Jira and Confluence reporting via MCP tools
+
+## v2 Requirements
+
+### Enhanced
+
+- **SKIL-04**: Self-improving auto-skills that detect and adapt to recurring patterns
+- **SKIL-05**: Custom Hermes skills catalog for platform engineering workflows
+- **GATE-04**: Microsoft Teams gateway
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Direct `~/.aws` mounting | Privileged credentials must never enter container |
+| Non-AWS cloud providers | GCP/Azure deferred — focus on AWS first |
+| Native mobile app | Telegram gateway covers mobile use case |
+| Self-hosted model serving | Bedrock + OpenRouter sufficient |
+| Kubernetes in-cluster deployment | Local agent with CLI access only |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 1 | Pending |
+| AUTH-02 | Phase 1 | Pending |
+| AUTH-03 | Phase 1 | Pending |
+| AUTH-04 | Phase 1 | Pending |
+| AUTH-05 | Phase 1 | Pending |
+| CONT-01 | Phase 1 | Pending |
+| CONT-02 | Phase 1 | Pending |
+| CONT-03 | Phase 1 | Pending |
+| CONT-04 | Phase 1 | Pending |
+| CONT-05 | Phase 1 | Pending |
+| CONT-06 | Phase 1 | Pending |
+| MEM-01 | Phase 2 | Pending |
+| MEM-02 | Phase 2 | Pending |
+| MEM-03 | Phase 2 | Pending |
+| MEM-04 | Phase 2 | Pending |
+| GATE-01 | Phase 3 | Pending |
+| GATE-02 | Phase 3 | Pending |
+| GATE-03 | Phase 3 | Pending |
+| GATE-04 | Phase 3 | Pending |
+| SKIL-01 | Phase 4 | Pending |
+| SKIL-02 | Phase 4 | Pending |
+| SKIL-03 | Phase 4 | Pending |
+
+**Coverage:**
+- v1 requirements: 22 total
+- Mapped to phases: 22
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2026-06-14*
+*Last updated: 2026-06-14 after initial definition*