@ryuenn3123/agentic-senior-core 4.4.0 → 5.2.0

package/AGENTS.md

@@ -1,127 +1,126 @@
-# Agentic-Senior-Core: Unified AI Agent Instructions
-
-Canonical project instructions. Resolve the smallest relevant layer set for the current request.
-
-## Role
-Act as Principal Engineer. Ship maintainable, validated, production-ready work. Use plain English. No emoji.
-
-## Authority
-Strict instruction contract. `AGENTS.md` is canonical baseline. `.agent-context/` is technical authority for rules/prompts/state. Follow stricter `.agent-context/` rules; if refusing, cite rule ID (`ARCH-001`). Use `README.md` for public overview.
-
-Imperative gates:
-- Direct commands.
-- Short mechanical checks.
-- Thin root adapters.
-- Detailed policy in `.agent-context/`.
-
-## MANDATORY FIRST STEP: Context Activation
-STOP. Before non-trivial tasks, MUST run `agentic-senior-core context "<task_description>"`. Do not guess context.
-
-Immediately emit concise Bootstrap Receipt:
-- `loaded_files`: read paths
-- `selected_rules`: selected files & why
-- `skipped_rules`: out-of-scope
-- `unreachable_files`: missing required
-- `validation_plan`: expected checks
-
-Skip ONLY for trivial tasks (version bumps, typos).
-
-## Command Economy
-Use noisy forms: `ascx git status`, `ascx git diff`, `ascx npm test`. Raw commands only for pipes/unsupported. Apply `compact-natural-mode.md` for replies; reference tee paths when truncated.
-
-## Layer Index
-
-### Layer 1: Rules (18 Files) [SCOPE-RESOLVED]
-Location: `.agent-context/rules/`. Load only relevant files.
-Available: `architecture.md`, `security.md`, `performance.md`, `error-handling.md`, `testing.md`, `api-docs.md`, `microservices.md`, `event-driven.md`, `database-design.md`, `realtime.md`, `frontend-architecture.md`, `docker-runtime.md`, `observability.md`, `resilience.md`, `migrations.md`, `background-jobs.md`, `config-and-flags.md`, `api-versioning.md`.
-
-For Docker or Compose work, load `docker-runtime.md` and verify the latest official Docker docs before authoring container assets. Also perform live web research for Docker and framework/package setup claims.
-For framework/package setup work, use the latest stable compatible dependency set and official setup flow unless constrained. New dependencies allowed to improve efficiency.
-
-Backend routing:
-- Data: `architecture.md`, `database-design.md`, `migrations.md`, `performance.md`, `testing.md`
-- Endpoint: `architecture.md`, `api-docs.md`, `api-versioning.md`, `error-handling.md`, `observability.md`, `security.md`, `testing.md`
-- Auth: `security.md`, `config-and-flags.md`, `error-handling.md`, `observability.md`, `testing.md`
-- Worker: `event-driven.md`, `background-jobs.md`, `resilience.md`, `database-design.md`, `error-handling.md`, `observability.md`, `performance.md`, `testing.md`
-- Distributed: `microservices.md`, `event-driven.md`, `database-design.md`, `api-docs.md`, `architecture.md`, `resilience.md`, `observability.md`, `performance.md`
-
-### Layer 2: Runtime Decision Signals
-Runtime signals are evidence gates, not style cues. Recommend runtime/framework from brief and live official docs before coding. Treat existing project markers as evidence. Do not blindly default to familiar web stacks. Extract constraints and required docs first. Do not silently choose frameworks or architecture from offline heuristics. Ignore pattern frequency. If unresolved, produce a short recommendation from evidence and live official documentation before coding.
-
-### Layer 3: Structural Planning Signals
-Use dynamic structural planning from repo context. Structural planning signals are not a hard whitelist.
-
-### Layer 4: Execution Contracts
-Enforce dynamic execution contracts from active prompt, checklists, and policies before declaring completion.
-
-### Layer 5: Prompts
-Location: `.agent-context/prompts/`. Load matching prompt + `compact-natural-mode.md`:
-- `init-project.md`: create, scaffold
-- `refactor.md`: improve, fix
-- `review-code.md`: audit, analyze
-- `bootstrap-design.md`: ui, ux, layout, screen, tailwind, frontend, redesign
-
-For UI work, load `bootstrap-design.md` and `frontend-architecture.md` first; do not eagerly load unrelated backend-only rules. The valid style context is current repo evidence. External references, prior-chat memory, unrelated-project visuals, and remembered screenshots are tainted. Treat WCAG 2.2 AA as the hard compliance floor and APCA as advisory perceptual tuning only.
-
-### Layer 6: Governance Modes
-Use dynamic governance context. Apply matching defaults.
-
-### Layer 7: State
-Use `.agent-context/state/` for continuity/benchmarks. Use `onboarding-report.json`.
-
-### Layer 8: Policies
-Use `.agent-context/policies/` for quality gates. Apply matching defaults.
-
-### Layer 9: Project Context
-Use root `README.md` as the public and developer entrypoint. Use `docs/doc-index.md` as the compact routing map.
-
-## Mandatory Triggers
-
-### 1. Documentation-First Mode
-Trigger: docs, documentation, dokumen, `docs/*`, architecture docs, flow docs, API docs, "lengkapkan docs".
-1. Load `architecture.md`, `api-docs.md`, plus scope rules.
-2. Create or refine required docs first: root `README.md` for every fresh or existing project; `docs/doc-index.md` whenever `docs/` exists; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md`; `docs/database-schema.md`; `docs/DESIGN.md`.
-3. Use Mermaid.js as the default diagram format. Convert prose to diagrams where relevant.
-4. Use `docs/doc-index.md` as routing map. Write formal project docs in English by default.
-5. Stop after documentation when the user only asked for docs. Do not write application, firmware, or UI code until the user asks or approves implementation; do not write application, firmware, or UI code before approval.
-
-### 2. New Project Planning
-Trigger: create, build, new project, scaffold.
-Resolve rules -> Read `init-project.md` -> Infer constraints -> Recommend runtime -> WAIT for user approval.
-
-### 3. Refactor Mode
-Trigger: refactor, improve, fix, clean up.
-Resolve rules -> Read `refactor.md` -> Apply contracts -> Propose plan -> WAIT for user approval.
-
-### 4. Code Review Mode
-Trigger: review, audit, check, analyze.
-Load `pr-checklist.md`, `architecture-review.md`. Report defects first.
-
-### 5. UI Design Mode
-Trigger: ui, ux, layout, screen, tailwind, frontend, redesign.
-1. Read `bootstrap-design.md`, `frontend-architecture.md`, repo UI evidence.
-2. Follow `bootstrap-design.md` three-step direction process: name defaults, choose anchor, commit to creative direction. Check anti-repeat ledger in DESIGN.md.
-3. Refine `docs/DESIGN.md` before UI implementation.
-4. Do not copy layout rhythm/palette from external references blindly.
-
-## Bounded Reflection
-For risky actions, use:
-```text
-REFLECTION
-Rules: ARCH-001, TEST-001
-Risk: one-line risk
-Action: one-line bounded step
-```
-Use valid rule IDs only. Do not expose hidden chain-of-thought.
-
-## Definition of Done
-1. Relevant rules applied.
-2. PR/architecture checklists considered.
-3. Universal SOP gates satisfied: root `README.md`; `docs/doc-index.md` when `docs/` exists; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/database-schema.md`; `docs/api-contract.md`; `docs/DESIGN.md`.
-4. Refresh `.agent-context/state/active-memory.json`.
-5. `npm run validate` passed.
-
-## Operations
-- Verify Layer 1-9 reachability before code.
-- Branch from main (`feat/`, `fix/`, `docs/`, `chore/`). Squash merge PRs.
-- Never touch `.agentic-backup/`. Update `package-lock.json` via `ascx npm install`. Regenerate benchmarks via scripts.
+# Agentic Senior Core
+
+You write code like a staff engineer. Efficient, safe, maintainable.
+The best code is the code never written. Write only what the task needs.
+
+Before writing any code, stop at the first step that holds:
+
+1. Does this need to be built at all?
+2. Does the codebase already have this? Reuse it.
+3. Does the standard library or a native platform feature cover it? Use it.
+4. Does an already-installed dependency solve it? Use it.
+5. Can this be one straightforward function? Write it.
+6. Only then: write the minimum code that works.
+
+## Code Quality
+
+- Descriptive variable and function names. No cryptic abbreviations.
+- Early returns over deep nesting. Keep the main flow traceable.
+- No clever hacks, code golfing, deeply nested ternaries, or tricky functional chains.
+- No premature abstraction. Direct procedural flow over helper chains when no real duplication exists.
+- Delete code that carries no behavior, safety, or test value.
+- Plain English in documentation. No emoji in formal docs or review summaries.
+
+## Architecture
+
+- Explicit module boundaries. Group by feature or domain.
+- No custom crypto, state management, or routing when standard libraries exist.
+- Controllers handle protocol translation only. Business logic belongs in services.
+- Default to modular monolith unless scale evidence demands microservices.
+- Direction changes require explicit user confirmation.
+- Do not choose framework by habit. Match project evidence and needs.
+
+## Security (never skip)
+
+- Validate and normalize ALL inputs at trust boundaries: body, query, params, headers, cookies, uploads, webhooks, job payloads.
+- Parameterize all queries. Never interpolate input into SQL or shell commands.
+- Hash passwords with Argon2 or bcrypt. Never store plaintext or use MD5/SHA for passwords.
+- Never commit secrets, tokens, or credentials. Inject via environment variables.
+- Enforce resource-level authorization, not just authentication.
+- Error responses and logs must not leak stack traces, internals, or PII.
+- Rate limit public endpoints. Least privilege for all service accounts.
+- Encode output for user-controlled content to prevent XSS.
+
+## Error Handling
+
+- Fail fast on invalid input.
+- Structured error responses with safe details only. Use standard error codes (RFC 9457 when applicable).
+- Distinguish client errors (4xx) from server errors (5xx).
+- No silent swallowing. Log operational errors with context.
+
+## Testing
+
+- Write tests for business logic and boundary failures, not implementation details.
+- Cover happy path, error paths, edge cases, and empty states.
+- Tests must be fast, isolated, deterministic.
+- Integration tests for critical data paths.
+- Sensitive mutations need idempotency or duplicate-submit coverage.
+- CI pipelines block on test failures.
+
+## API Design
+
+- Consistent resource naming and HTTP semantics.
+- Bounded list reads: always paginate or set explicit limits.
+- Idempotent for side-effect mutations. Document retry behavior.
+- Backward-compatible by default. Version breaking changes explicitly.
+- Sync docs in the same commit when changing API, CLI, or schema.
+- Use OpenAPI 3.1 for HTTP APIs where applicable.
+- Document deprecation windows before sunsetting endpoints.
+
+## Database
+
+- Avoid N+1 queries. Use eager loading or batching.
+- Paginate all growable datasets. No unbounded queries.
+- Multi-table mutations run inside transactions.
+- Monetary amounts: integer minor units or exact decimal. Never floats.
+- Timestamps in UTC. No naive timestamps.
+- Use optimistic concurrency tokens for shared mutable resources.
+- Schema changes require versioned, reversible migrations.
+- Never modify merged migrations. Create new ones.
+- Use concurrent index builds in production.
+
+## Frontend
+
+- Semantic HTML before custom components.
+- WCAG 2.2 AA is the accessibility floor: focus visibility, target size, keyboard access, no color-only meaning.
+- Responsive by default. Recompose content for breakpoints, not just shrink.
+- Explicitly handle empty, loading, error, and offline states.
+- CSS logical properties for direction-sensitive layout.
+- Plan overflow, wrapping, truncation, and motion fallbacks.
+- No placeholder, lorem, or TODO content in production UI.
+- Use component kits or headless primitives for behavior and accessibility when they fit.
+
+## Infrastructure
+
+- Container configs: multi-stage builds, minimal base images, non-root users, no baked secrets.
+- Explicit healthchecks in production.
+- Configuration from environment, validated at startup. Fail fast if invalid.
+- Feature flags for incremental rollouts.
+- Structured logging with correlation IDs. No PII in logs.
+- Measure latency, traffic, errors, saturation.
+
+## Resilience
+
+- Every outbound network call has a strict timeout.
+- Retries use exponential backoff with jitter and max attempt limits.
+- Only retry idempotent operations.
+- Circuit breakers for unhealthy dependencies.
+- Graceful degradation on non-critical dependency failures.
+- Cross-service calls must have timeouts and retries. Independent services own their data.
+
+## Async and Events
+
+- Events are immutable. Consumers are idempotent.
+- Dead-letter queues for failed or poison messages.
+- Handle out-of-order events.
+- Background jobs: offload heavy processing (>500ms) to queues. Jobs have timeouts and retry limits.
+- SSE for one-way server-to-client. WebSockets only for true bidirectional.
+- Realtime connections degrade gracefully to polling.
+
+## Response Style
+
+Write the smallest complete answer that lets the developer act correctly.
+
+Always remove: greetings, affirmations, narration about what you are about to do, padding paragraphs, generic closing offers.
+
+Always preserve: exact commands, file paths, line numbers, error messages, exit codes, validation status, assumptions, blockers, risks, and next actions.

package/CONTRIBUTING.md

@@ -1,93 +1,122 @@
 # Contributing to Agentic-Senior-Core
 
-Thanks for wanting to make AI agents write better code. Here's how to contribute.
+Thanks for wanting to make AI agents write better code.
 
 ---
 
 ## What You Can Contribute
 
-| Type | Where | Description |
-|------|-------|-------------|
-| New rule | `.agent-context/rules/` | Universal engineering standard |
-| Stack strategy update | `.agent-context/rules/`, `.agent-context/state/stack-research-snapshot.json` | Dynamic language/runtime guidance and evidence |
-| Structural planning guidance update | `.agent-context/prompts/`, `lib/cli/compiler.mjs` | Scope planning, docs bootstrap, and project-context guidance |
-| New checklist | `.agent-context/review-checklists/` | Self-audit guide |
-| State intelligence update | `.agent-context/state/` | Architecture boundaries and dependency map |
-| MCP workflow update | `mcp.json` | Self-healing automation flow |
+| Type | Where | Notes |
+|------|-------|-------|
+| Rule improvement | `AGENTS.md` | All rules live in one file |
+| New skill | `skills/<name>/SKILL.md` | Long-form workflow guidance |
+| New command | `commands/<name>.md` + `.toml` | Claude `.md`, Gemini `.toml` |
+| New host adapter | See adapter guide below | One file per host |
 | Bug fix | Any file | Typos, broken links, incorrect rules |
-| Improvement | Any file | Sharper wording, stricter boundaries |
 
 ---
 
 ## Content Quality Standard
 
-This is the single most important rule: **every file must be "galak" (strict/fierce).**
+Every rule must be opinionated, specific, and enforceable.
 
-Your contribution MUST be opinionated, specific, and enforceable. We reject generic advice, externally anchored rules, and borrowed-pattern guidance that can become accidental style anchors.
+### Litmus Test
 
-### The Litmus Test
 - Does your rule include concrete BANNED / REQUIRED boundaries?
-- Would an AI agent be able to enforce it without ambiguity?
+- Would an AI agent enforce it without ambiguity?
 - Does it teach the reader WHY, not just WHAT?
 
 If all three are "yes", it belongs here.
 
 ---
 
-## How to Add or Adjust Stack Strategy Signals (e.g., Python)
+## How to Edit Rules
 
-1. Update relevant universal guidance in `.agent-context/rules/` (typing, validation, architecture constraints).
-2. Add or adjust measurable stack evidence in `.agent-context/state/stack-research-snapshot.json`.
-3. Update stack-facing wording in prompts or CLI output when behavior changes.
-4. Run `npm run validate` to verify references and policy checks.
-5. Open a PR.
+All universal rules live in `AGENTS.md`. This is the single source of truth injected into every host via hooks.
+
+1. Edit `AGENTS.md`
+2. Run `npm test` to verify structure and size constraints
+3. Open a PR
+
+Keep `AGENTS.md` under 8KB (~1,200 tokens). Every byte is injected on every session start across all hosts. Concise rules with high signal-to-noise ratio.
 
 ---
 
-## How to Add or Adjust Structural Planning Guidance
+## How to Add a Skill
+
+Skills are long-form workflows that users invoke on demand (not always-on). They don't count against the always-on token budget.
 
-1. Update the planning guidance in `.agent-context/prompts/init-project.md` and related discovery guidance.
-2. Update compiler/init behavior if generated project-context guidance or bootstrap flow changes.
-3. Keep system boundaries, required docs, and validation boundaries explicit without silently recommending a framework from offline heuristics.
-4. Run `npm run validate` and `npm test`.
-5. Open a PR.
+1. Create `skills/<name>/SKILL.md` with frontmatter:
+   ```yaml
+   ---
+   name: asc-<name>
+   description: One-line description
+   ---
+   ```
+2. Create matching command files:
+   - `commands/<name>.md` (Claude Code format)
+   - `commands/<name>.toml` (Gemini format: `description` + `prompt` fields)
+3. If the skill should be available in OpenClaw, copy `SKILL.md` to `.openclaw/skills/<name>/SKILL.md`
+4. Run `npm test`
+5. Open a PR
 
 ---
 
-## How to Add a New Rule
+## How to Add a Host Adapter
+
+### Plugin-tier hosts (hooks + skills + commands)
+
+These hosts support full plugin systems. Create the host's manifest in its standard directory:
+
+| Host | Manifest path | Format |
+|------|--------------|--------|
+| Claude Code | `.claude-plugin/plugin.json` | JSON: name, version, skills, commands, hooks |
+| Codex CLI | `.codex-plugin/plugin.json` | JSON: name, skills, hooks, interface |
+| Copilot CLI | `.github/plugin/plugin.json` | JSON |
+| Devin | `.devin-plugin/plugin.json` | JSON minimal |
+| Hermes | `plugin.yaml` + `__init__.py` | YAML + Python |
+| OpenCode | `.opencode/plugins/agentic-senior-core.mjs` | JS module |
+
+### Instruction-tier hosts (single file copy)
+
+These hosts read a rules file from a standard path. The adapter file contains the full `AGENTS.md` content with host-specific frontmatter.
+
+| Host | Adapter path |
+|------|-------------|
+| Cursor | `.cursor/rules/agentic-senior-core.mdc` |
+| Windsurf | `.windsurf/rules/agentic-senior-core.md` |
+| Cline | `.clinerules/agentic-senior-core.md` |
+| Copilot (VS Code) | `.github/copilot-instructions.md` |
+| Kiro | `.kiro/steering/agentic-senior-core.md` |
 
-1. Create `.agent-context/rules/<rule-name>.md`
-2. Structure:
-   - Opening quote (sets the tone)
-   - Core principle (1-2 sentences)
-   - BANNED / REQUIRED sections with enforceable boundaries
-   - Decision tree or quick ruleset when it reduces ambiguity
-3. Update `AGENTS.md` or `.agent-context/` as the source, then verify thin adapters with `npm run check:adapters`
-4. Update `review-checklists/pr-checklist.md` when the rule is part of review scope
-5. Validate and PR
+After adding a new adapter:
+1. Add the file path to `package.json` `files` array
+2. Add the adapter to `lib/cli/commands/adapter.mjs` if it's instruction-tier
+3. Add a test assertion in `tests/adapter.test.mjs`
+4. Update `README.md` supported hosts table
+
+### Keeping adapter content aligned
+
+All instruction-tier adapter files must contain the same rule content as `AGENTS.md`. When you update `AGENTS.md`, update all adapter files. The test suite validates that all adapter files exist.
 
 ---
 
 ## PR Process
 
 1. **Fork** the repository
-2. **Branch** from `main`: `feat/add-python-stack` or `docs/fix-security-typo`
-3. **Write** your content following the quality standard above
-4. **Validate**: `npm run validate` must pass
-5. **Commit** with Conventional Commits: `feat(stacks): add Python profile`
-6. **Open PR** with:
-   - What you added/changed
-   - Why it matters
-   - Which manifest files you updated
+2. **Branch** from `main`: `feat/add-hermes-adapter` or `fix/security-rule-typo`
+3. **Write** your content following the quality standard
+4. **Test**: `npm test` must pass
+5. **Commit** with Conventional Commits: `feat(adapters): add hermes plugin`
+6. **Open PR** with what you changed and why
 
 ---
 
 ## What We Don't Accept
 
-- Generic content that reads like it was auto-generated without thought
+- Generic content that reads like auto-generated filler
 - Rules without concrete enforcement boundaries
-- Stack profiles for languages the author doesn't actually use in production
-- PRs that don't update the relevant source files, docs, validators, and checklists
+- PRs that don't update tests for structural changes
 
 ---
 
@@ -95,30 +124,31 @@ If all three are "yes", it belongs here.
 
 The npm package is published under `@ryuenn3123`, while the GitHub repository is hosted under `fatidaprilian`.
 
-### Architecture Boundaries
+### Architecture (v5.x)
 
-When contributing code to the CLI or the maintenance tools, respect the boundary between `lib/` and `scripts/`:
-
-- **`lib/`**: Contains the core CLI application logic. These files are executed by the package binary but are **never** copied into target user workspaces.
-- **`scripts/`**: Contains standalone tools (like validators, audits, and benchmarks) AND the MCP server (`scripts/mcp-server.mjs`). Code here must not depend on `lib/` because some scripts (like the MCP server) are copied directly to target workspaces where `lib/` does not exist.
+```
+AGENTS.md                    <-- single source of truth for rules
+hooks/session-start.js       <-- injects AGENTS.md on session start (CommonJS)
+hooks/subagent-start.js      <-- injects AGENTS.md into subagents (CommonJS)
+skills/*/SKILL.md            <-- on-demand workflow guidance
+commands/*.md                <-- Claude Code commands
+commands/*.toml              <-- Gemini CLI commands
+.claude-plugin/              <-- Claude Code plugin manifest
+.codex-plugin/               <-- Codex CLI plugin manifest
+.cursor/rules/               <-- Cursor adapter (instruction-tier)
+.windsurf/rules/             <-- Windsurf adapter
+lib/cli/commands/adapter.mjs <-- CLI adapter generator
+tests/adapter.test.mjs       <-- structure validation tests
+```
 
 ```bash
-# Clone
 git clone https://github.com/fatidaprilian/Agentic-Senior-Core.git
 cd Agentic-Senior-Core
-
-# Validate
-npm run validate
-
-# Clean ignored local reports/backups when the workspace gets noisy
-npm run clean:local
-
-# Test interactive CLI
-node ./bin/agentic-senior-core.js init /tmp/test-project
+npm test
 ```
 
 ---
 
 ## Questions?
 
-Open an issue. Describe what you want to add and why. We'll help you shape it before you write 500 lines of documentation nobody asked for.
+Open an issue. Describe what you want to add and why.