diff --git a/README.md b/README.md index 84b3148..f369d57 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) AgentTK is a small TypeScript toolkit for building deterministic, agent-friendly CLIs. +It is a framework for agent-authored CLIs, not a built-in CLI generator. It gives you a clean core for tools that need: - structured success and failure envelopes diff --git a/openspec/changes/define-agenttk-doctrine/.openspec.yaml b/openspec/changes/archive/2026-04-12-define-agenttk-doctrine/.openspec.yaml similarity index 100% rename from openspec/changes/define-agenttk-doctrine/.openspec.yaml rename to openspec/changes/archive/2026-04-12-define-agenttk-doctrine/.openspec.yaml diff --git a/openspec/changes/define-agenttk-doctrine/design.md b/openspec/changes/archive/2026-04-12-define-agenttk-doctrine/design.md similarity index 100% rename from openspec/changes/define-agenttk-doctrine/design.md rename to openspec/changes/archive/2026-04-12-define-agenttk-doctrine/design.md diff --git a/openspec/changes/define-agenttk-doctrine/proposal.md b/openspec/changes/archive/2026-04-12-define-agenttk-doctrine/proposal.md similarity index 100% rename from openspec/changes/define-agenttk-doctrine/proposal.md rename to openspec/changes/archive/2026-04-12-define-agenttk-doctrine/proposal.md diff --git a/openspec/changes/define-agenttk-doctrine/specs/agent-authoring-doctrine/spec.md b/openspec/changes/archive/2026-04-12-define-agenttk-doctrine/specs/agent-authoring-doctrine/spec.md similarity index 100% rename from openspec/changes/define-agenttk-doctrine/specs/agent-authoring-doctrine/spec.md rename to openspec/changes/archive/2026-04-12-define-agenttk-doctrine/specs/agent-authoring-doctrine/spec.md diff --git a/openspec/changes/archive/2026-04-12-define-agenttk-doctrine/tasks.md b/openspec/changes/archive/2026-04-12-define-agenttk-doctrine/tasks.md new file mode 100644 index 0000000..624fca3 --- /dev/null +++ b/openspec/changes/archive/2026-04-12-define-agenttk-doctrine/tasks.md @@ -0,0 +1,16 @@ +## 1. Doctrine + +- [x] 1.1 Record AgentTK's product doctrine as a framework for agent-authored CLIs. +- [x] 1.2 Define the explicit boundary between AgentTK core, the user's agent, and downstream tool repos. +- [x] 1.3 Capture the anti-goals that should be rejected in future scope decisions. + +## 2. Roadmap lanes + +- [x] 2.1 Define the next reusable primitive lanes for AgentTK. +- [x] 2.2 Clarify how future changes should be judged for inclusion in core. +- [x] 2.3 Establish the boundary between core primitives and higher-level helper layers. + +## 3. Validation + +- [x] 3.1 Validate the OpenSpec change. +- [x] 3.2 Use this doctrine as the reference for evaluating the next AgentTK roadmap changes. diff --git a/openspec/changes/define-agenttk-doctrine/tasks.md b/openspec/changes/define-agenttk-doctrine/tasks.md deleted file mode 100644 index 28ce5de..0000000 --- a/openspec/changes/define-agenttk-doctrine/tasks.md +++ /dev/null @@ -1,16 +0,0 @@ -## 1. Doctrine - -- [ ] 1.1 Record AgentTK's product doctrine as a framework for agent-authored CLIs. -- [ ] 1.2 Define the explicit boundary between AgentTK core, the user's agent, and downstream tool repos. -- [ ] 1.3 Capture the anti-goals that should be rejected in future scope decisions. - -## 2. Roadmap lanes - -- [ ] 2.1 Define the next reusable primitive lanes for AgentTK. -- [ ] 2.2 Clarify how future changes should be judged for inclusion in core. -- [ ] 2.3 Establish the boundary between core primitives and higher-level helper layers. - -## 3. Validation - -- [ ] 3.1 Validate the OpenSpec change. -- [ ] 3.2 Use this doctrine as the reference for evaluating the next AgentTK roadmap changes. diff --git a/openspec/specs/agent-authoring-doctrine/spec.md b/openspec/specs/agent-authoring-doctrine/spec.md new file mode 100644 index 0000000..1d7669b --- /dev/null +++ b/openspec/specs/agent-authoring-doctrine/spec.md @@ -0,0 +1,46 @@ +# agent-authoring-doctrine Specification + +## Purpose +Define the durable product boundary for AgentTK as a framework for agent-authored CLIs, so future roadmap and scope decisions stay narrow, reusable, and free of generator/framework sludge. +## Requirements +### Requirement: AgentTK is a framework for agent-authored CLIs +The system SHALL define AgentTK as a reusable framework used by a user's agent to build CLI tools. + +#### Scenario: Agent authors a tool using AgentTK +- **WHEN** a user's agent reads a skill, interface contract, or integration description +- **THEN** the agent can use AgentTK as the framework for writing the CLI tool +- **AND** AgentTK provides reusable primitives instead of trying to generate the complete tool itself + +### Requirement: Clear ownership boundaries +The system SHALL distinguish among framework responsibilities, agent responsibilities, and downstream tool responsibilities. + +#### Scenario: Framework boundary +- **WHEN** a capability is part of repeated CLI plumbing +- **THEN** it may belong in AgentTK core or an AgentTK helper layer + +#### Scenario: Agent boundary +- **WHEN** a capability involves interpreting a skill, deciding the command surface, or writing tool-specific code +- **THEN** that responsibility belongs to the user's agent rather than AgentTK itself + +#### Scenario: Downstream tool boundary +- **WHEN** a capability depends on provider-specific behavior, business rules, or domain quirks +- **THEN** that responsibility belongs in the downstream tool repo unless it later proves broadly reusable + +### Requirement: Anti-goals remain explicit +The system SHALL reject scope that conflicts with the doctrine. + +#### Scenario: Reject built-in tool generation +- **WHEN** a proposal attempts to make AgentTK itself generate complete tools +- **THEN** that proposal conflicts with the doctrine and should not be treated as core framework scope + +#### Scenario: Reject domain-specific core bloat +- **WHEN** a proposal attempts to place provider-specific integrations or business logic into AgentTK core +- **THEN** that proposal conflicts with the doctrine unless the behavior is proven reusable across multiple tools + +### Requirement: Roadmap decisions optimize for agent leverage +The system SHALL evaluate future capabilities by how much they help agents build good CLIs without rebuilding plumbing. + +#### Scenario: Good future primitive +- **WHEN** a proposal adds help metadata, auth blocks, lookup patterns, adapter contracts, config conventions, or richer test helpers +- **THEN** it aligns with the doctrine if it increases agent leverage without forcing domain assumptions into core +