agentik

Summary Agentik provides a powerful runtime, reference CLI, and built-in tools. However, first-time users must manually wire context loading, tool policy, session persistence, and lifecycle hooks before they can experience a deterministic, repo-aware agent workflow. This proposal adds an optional, additive scaffold layer that enables a working agent with only: • a selected model • a valid API key • a single command The goal is to reduce onboarding friction while preserving Agentik’s runtime-first philosophy. ⸻ Problem Today, a new user who wants a repo-aware coding agent must: 1. Create context files manually 2. Design a settings schema 3. Implement a context loader 4. Implement tool authorization logic 5. Wire lifecycle hooks 6. Configure session persistence While the runtime exposes all required primitives, there is no convention layer or minimal scaffold that demonstrates how these components fit together in practice. This results in: • onboarding friction • duplicated boilerplate across users • inconsistent patterns • unclear intended usage for repo-aware workflows ⸻ Proposal Add an optional scaffold and minimal loader layer that: • Does not change existing runtime APIs • Does not impose conventions on advanced users • Lives either in examples/, a companion package, or a small additive CLI feature • Demonstrates a complete deterministic workflow built on top of existing primitives ⸻ Proposed Scope 1. Default Project Structure Provide a minimal scaffold generated via: agentik init It creates: AGENT.md PROJECT_STATE.md .agent/ settings.json rules/ 00-safety.md 10-style.md sessions/ Purpose: • Demonstrates structured context layering • Provides editable templates • Encourages consistent usage patterns ⸻ 2. Minimal settings.json Schema Ship a documented baseline schema: { "model": { "provider": "anthropic", "name": "claude-3-7-sonnet", "temperature": 0.2 }, "tools": { "bash": { "enabled": true, "requireApproval": true }, "writeFile": { "enabled": true, "requireApproval": true }, "readFile": { "enabled": true } }, "qualityGates": { "requireTestsPassing": false } } This becomes: • the enforcement layer for lifecycle hooks • a clear extensible policy surface • a reference example of best practices ⸻ 3. Default Context Loader Add a minimal loader used by the CLI or example. Context assembly order: 1. AGENT.md 2. PROJECT_STATE.md 3. .agent/rules/*.md sorted 4. Optional active plan file This produces a deterministic context pack without custom wiring. ⸻ 4. Reference Policy Enforcement Use lifecycle hooks to implement a minimal policy layer: • Deny access to .env and secrets • Require approval for write, edit, bash • Log tool calls to .agent/sessions/ • Optional test or lint gate before completion This demonstrates intended hook usage. ⸻ 5. Default File-Based Session Store Out of the box: .agent/sessions/.jsonl Automatically created on first run. No custom store required for basic usage. ⸻ 6. Single-Command Experience After install and API key: agentik init agentik run "summarize this repository" This should: • Load scaffold • Enforce tool policy • Persist session • Run with built-in tools • Stream output No additional wiring required. ⸻ Implementation Placement Options Open question: Where should this live? 1. examples/quickstart/ 2. Companion package such as @agentik/create 3. Small addition to @jaredpalmer/coding-agent 4. Core package Preferred placement is examples or a companion package to avoid expanding core surface area. ⸻ Non-Goals • Turning Agentik into a monolithic CLI • Replacing flexibility • Enforcing mandatory conventions • Modifying runtime behavior • Introducing breaking changes This is entirely opt-in. ⸻ Acceptance Criteria • Installing the package and setting an API key is sufficient to run an agent in a repo • Scaffold is generated via a single command • Existing APIs remain unchanged • Advanced users can ignore scaffold entirely • Documentation clearly distinguishes runtime primitives from scaffold layer ⸻ Why This Improves the Project • Reduces onboarding friction • Establishes best practices • Makes demos easier • Encourages adoption • Reduces repeated boilerplate ⸻ Offer If aligned with project goals, I am willing to submit a PR implementing: • The scaffold generator • The minimal loader • The reference policy enforcement • Documentation updates Please advise preferred placement and scope boundaries.