Refresh agent instruction files
This commit is contained in:
parent
10868739a8
commit
465a778c1f
10 changed files with 381 additions and 138 deletions
147
CLAUDE.md
147
CLAUDE.md
|
|
@ -1,140 +1,11 @@
|
|||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
# KeyCape — Claude Code Instructions
|
||||
|
||||
## What This Repo Is
|
||||
|
||||
**KeyCape** is the lightweight IAM component of NetKingdom.
|
||||
|
||||
> *"Prepare for Keycloak without Keycloak"*
|
||||
|
||||
KeyCape implements the **NetKingdom IAM Profile** — a versioned OIDC/PKCE contract
|
||||
that NetKingdom applications integrate against. It orchestrates:
|
||||
|
||||
| Component | Role |
|
||||
|--------------|-------------------------------|
|
||||
| Authelia | OIDC provider / session / tokens |
|
||||
| LLDAP | Lightweight identity directory |
|
||||
| privacyIDEA | MFA authority |
|
||||
|
||||
Keycape is intentionally replaceable by **Keycloak** in expanded mode. All apps
|
||||
must target the profile, not Keycape or Keycloak incidentals.
|
||||
|
||||
## Custodian State Hub Integration
|
||||
|
||||
- **Domain:** `netkingdom`
|
||||
- **Repo ID:** `8a99bb74-1ec0-4478-ac70-35a7cddb0e3c`
|
||||
- **State Hub API:** `http://127.0.0.1:8000` (run `cd ~/the-custodian/state-hub && make api` if offline)
|
||||
|
||||
### Session Protocol
|
||||
|
||||
**Start of every session:**
|
||||
```bash
|
||||
cat .custodian-brief.md # offline-safe orientation, always read first
|
||||
```
|
||||
Then call for richer context (skip if MCP unreachable):
|
||||
```
|
||||
get_domain_summary("netkingdom")
|
||||
```
|
||||
This gives the full picture of active workstreams, blocking decisions, and recent
|
||||
progress for the NetKingdom domain at ~10% of the cost of `get_state_summary()`.
|
||||
|
||||
**During work:**
|
||||
- `record_decision()` for any architectural choice (profile extensions, backend selection, etc.)
|
||||
- `add_progress_event()` for milestones, blockers, discoveries
|
||||
- `resolve_decision()` once a decision is closed
|
||||
|
||||
**End of every session:**
|
||||
```
|
||||
add_progress_event(summary="...", event_type="...", workstream_id="<active ws id>")
|
||||
```
|
||||
|
||||
After modifying workplan files, run:
|
||||
```
|
||||
cd ~/the-custodian/state-hub && make fix-consistency REPO=key-cape
|
||||
```
|
||||
|
||||
## Key Documents
|
||||
|
||||
| Document | Path | Purpose |
|
||||
|---|---|---|
|
||||
| Keycape Specification v0.1 | `wiki/KeyCapeSpecification_v0.1.md` | Architecture, design intent, objectives |
|
||||
| Normative Specification Pack v0.1 | `wiki/KeyCapeSpecificationPack_v0.1.md` | Normative spec for implementation agents: identity model, LDAP schema, error taxonomy, telemetry, migration contract, acceptance test matrix |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
key-cape/
|
||||
wiki/ # Specifications (read before implementing)
|
||||
workplans/ # Implementation workplans (ADR-001 convention)
|
||||
src/ # Implementation (to be created)
|
||||
tests/ # Test suite (to be created)
|
||||
```
|
||||
|
||||
### Lightweight mode stack
|
||||
|
||||
```
|
||||
Application ──→ NetKingdom IAM Profile
|
||||
│
|
||||
KeyCape ←── config translation, claim normalization
|
||||
/ | \
|
||||
Authelia LLDAP privacyIDEA
|
||||
```
|
||||
|
||||
### Expanded mode stack (Keycape → Keycloak)
|
||||
|
||||
```
|
||||
Application ──→ NetKingdom IAM Profile
|
||||
│
|
||||
Keycloak (same profile, different runtime)
|
||||
/ \
|
||||
LDAP privacyIDEA
|
||||
```
|
||||
|
||||
## Implementation Priorities (from spec)
|
||||
|
||||
1. **Profile endpoints** — OIDC discovery, authorization, token, JWKS, userinfo
|
||||
2. **Canonical identity model** — product-neutral user/group/client schema
|
||||
3. **Claim normalization** — stable claim set regardless of backend quirks
|
||||
4. **Unsupported-feature enforcement** — structured errors, never silent emulation
|
||||
5. **Telemetry** — demand visibility for unsupported features and auth events
|
||||
6. **Migration tooling** — export/validate for LLDAP → Keycloak path
|
||||
|
||||
## Normative Constraints (from spec — binding on implementation)
|
||||
|
||||
**Never silently emulate unsupported features.** Any request outside the profile MUST fail with a structured error from this taxonomy:
|
||||
- `feature_not_supported_by_profile` — outside the NetKingdom IAM Profile entirely
|
||||
- `available_in_keycloak_mode_only` — exists in expanded mode, absent here by design
|
||||
- `rejected_for_profile_safety` — would weaken profile guarantees or security discipline
|
||||
- `invalid_profile_usage` — supported endpoint/feature used incorrectly
|
||||
|
||||
**Security hard rules:** No handwritten cryptography. No handwritten password hashing. Use established protocol and crypto libraries. Strict redirect URI validation. Strict issuer consistency.
|
||||
|
||||
**Canonical identity model** is the source of truth for test fixtures, provisioning, migration, and validation — not any backend's native schema.
|
||||
|
||||
**Spec Pack structure** (`wiki/KeyCapeSpecificationPack_v0.1.md`) contains 7 normative components agents must read before implementing:
|
||||
1. Normative Specification — OIDC/PKCE contract, endpoints, scopes, claims, client model, MFA
|
||||
2. Canonical Identity Schema — User, Group, Membership, Client, Role, MFAEnrollmentReference, etc.
|
||||
3. Canonical LDAP Schema + Validator Rules — restricted LDAP expression of identity model
|
||||
4. Error Taxonomy — machine-readable/human-readable/loggable structured errors
|
||||
5. Telemetry Schema — event types, required fields (timestamp, env, client_id, endpoint, feature_category, correlation_id, …)
|
||||
6. Migration Contract — LLDAP → full LDAP, KeyCape → Keycloak migration paths
|
||||
7. Acceptance Test Matrix — lightweight baseline, IAM replacement, full expansion, negative profile tests
|
||||
|
||||
## Workplan Convention (ADR-001)
|
||||
|
||||
Workplans live in `workplans/<id>-<slug>.md` with YAML frontmatter:
|
||||
```yaml
|
||||
id: KEY-WP-0001
|
||||
type: workplan
|
||||
title: "..."
|
||||
domain: netkingdom
|
||||
repo: key-cape
|
||||
status: todo|active|done
|
||||
owner: Bernd
|
||||
topic_slug: netkingdom
|
||||
```
|
||||
|
||||
Tasks are embedded as `## Task Title\n```task\nid: ...\nstatus: todo\n```\n` blocks.
|
||||
@SCOPE.md
|
||||
@.claude/rules/repo-identity.md
|
||||
@.claude/rules/session-protocol.md
|
||||
@.claude/rules/first-session.md
|
||||
@.claude/rules/workplan-convention.md
|
||||
@.claude/rules/stack-and-commands.md
|
||||
@.claude/rules/architecture.md
|
||||
@.claude/rules/repo-boundary.md
|
||||
@.claude/rules/agents.md
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue