1. Introduction and Goals
Rukh is an embeddable core for a CLI with its own name, built-in commands and trusted installable extensions. People use its CLI; agents can use approved tools generated from the same command model through MCP. ADR-0010, ADR-0013
1.1 Requirements overview
Section titled “1.1 Requirements overview”Rukh separates the application supplied by its owner from the commands supplied by independent publishers. The user works in one command tree; a publisher can add or update an extension without distributing another branded CLI. Supported execution bindings preserve language independence without promising that every language or runtime is already supported.
The identifiers below summarize accepted requirements; they are not a second specification of their contracts.
| ID | Product requirement | Defining decisions |
|---|---|---|
| REQ-01 | An owner assembles a named CLI from the core, built-in commands and admitted integrations. Owner configuration selects their use; ordinary extensions cannot add privileged implementations. | ADR-0010 |
| REQ-02 | Independent publishers add commands and subcommands through declared, versioned extension releases. Command identity survives aliases and presentation changes; supported native and script mappings share invocation semantics. | ADR-0001, ADR-0002, ADR-0006 |
| REQ-03 | Users discover, install and update approved releases. Visibility, artifact trust, installation, activation and permission to act are separate checks; updates must not replace the implementation of a running call. | ADR-0005, ADR-0007 |
| REQ-04 | A small team can distribute a catalog and explicit local rules without running identity or permission services. Organizations can independently add existing identity, access and runtime integrations while retaining the same extension contracts. | ADR-0005, ADR-0008, ADR-0009 |
| REQ-05 | People and approved machine clients use one command model. MCP tools are generated from compatible active commands only when the owner permits exposure; machine publication neither grants access nor turns every CLI command into an agent tool. | ADR-0013 |
| REQ-06 | Invocations have explicit ownership, bounded authority and a defined final outcome. Required execution restrictions and consequential-action guarantees must be supported, with uncertainty preserved rather than hidden by automatic replay. | ADR-0004, ADR-0014, ADR-0015, ADR-0016 |
The domain is extension delivery and controlled command execution. Rukh is not a package build service, an identity directory or an agent planner. 3. Context and Scope defines these boundaries and the separate meanings of publisher, operator, subject and actor.
1.2 Quality goals
Section titled “1.2 Quality goals”The order below expresses the accepted design’s trade-offs: missing authority or a required guarantee prevents work; convenience and speed cannot silently weaken that boundary. It does not make the lower goals optional or alter their ADR targets.
| Priority / ID | Goal and domain consequence | Stakeholders most affected | Source |
|---|---|---|---|
| 1 · QG-01 | Controlled authority. A trusted release, a signed-in user and a listed tool are not blanket permission. The actual action stays within current owner, subject and task limits; direct OS access is described honestly. | CLI owner, access administrator, resource owner, user | ADR-0005, ADR-0014, ADR-0015 |
| 2 · QG-02 | Predictable outcomes and recovery. Cancellation, concurrent updates and lost responses cannot silently replace a running command or repeat an external action. An uncertain effect stays distinguishable from confirmed success. | CLI operator, agent integrator, resource owner | ADR-0004, ADR-0007, ADR-0016 |
| 3 · QG-03 | Extensibility with compatibility. Publishers release independently and owners replace integrations while preserving command identity, input semantics and explicit unsupported behavior. | Extension publisher, CLI owner, integration author | ADR-0002, ADR-0006, ADR-0010 |
| 4 · QG-04 | A practical local baseline. Sharing approved extensions and exposing selected tools does not require a server estate or an organization account. Added services do not create a different extension model. | Small-team owner, CLI operator, organization integrator | ADR-0009, ADR-0013 |
| 5 · QG-05 | Responsive inspection and execution. Base help and tool listing do not start extension code or prepare runtimes. Startup and IPC have scenario-specific targets, with cold preparation assessed separately. | CLI user, machine client, extension publisher | ADR-0001, ADR-0003, ADR-0008, ADR-0013 |
Detailed scenarios and evidence limits are in 10. Quality Requirements; known gaps are in 11. Risks and Technical Debt.
1.3 Stakeholders
Section titled “1.3 Stakeholders”| Participant | Responsibility and expected result | Main requirements |
|---|---|---|
| CLI owner | Defines the application, admitted integration code and configuration authority; supplies a coherent branded tool rather than delegating core trust to package authors | REQ-01, REQ-04 |
| Extension author / publisher | Implements commands and publishes exact declarations and artifacts; can request facilities but cannot grant their use or choose privileged provider code | REQ-02, REQ-03 |
| CLI user / operator | Uses commands and, where authorized, maintains installed extensions and profiles; expects stable routes, useful help and explainable failures | REQ-03, REQ-06 |
| Access administrator | Maintains approved sources, subject/group mappings and policy through explicitly delegated authority; local rule files and external services remain alternatives | REQ-03, REQ-04, REQ-06 |
| Agent integrator / machine client | Connects to an approved tool surface, supplies valid inputs and handles stale bindings or uncertain results without assuming broader rights | REQ-05, REQ-06 |
| Integration and resource owner | Provides trusted adapters and resource contracts; states which identity, enforcement and effect guarantees are actually supported | REQ-01, REQ-04, REQ-06 |
These are responsibilities, not mandatory departments or application roles. One person can be owner, publisher and operator in a small team. None of those labels alone establishes a verified identity or an authorization grant. The binding rules are in ADR-0005, ADR-0010 and ADR-0014.
Continue with 2. Architecture Constraints and 3. Context and Scope. The sidebar follows the arc42 section order.