Standalone description-to-contract CLI tool

[danielbentes]

Context

The Automated Capability Discovery Pipeline (grounded_agency/discovery/) can generate typed contracts (input/output JSON schemas, risk levels, layer assignments, edges) for proposed capabilities. However, this contract generation logic is embedded inside the GapDetector stage of the full discovery pipeline — there is no standalone entry point for converting a natural language description into a typed contract.

Current State

To generate a typed contract from a description, users must run the full discovery pipeline which includes task analysis, capability matching, gap detection, and workflow synthesis. This is heavyweight for users who simply want to produce a contract for a known capability idea. The relevant logic lives in GapDetector.build_gap_proposal_prompt() and ProposedCapability but cannot be invoked independently.

Objective

Provide a lightweight, single-purpose CLI tool that accepts a natural language capability description and outputs a complete typed contract — including input/output JSON Schemas, layer assignment, risk classification, mutation flag, and suggested ontology edges — ready for integration into the capability ontology.

Proposed Solution

• A CLI entry point that takes a description string and optional parameters (layer hint, risk hint, domain)
• LLM-assisted contract generation leveraging ontology context (existing capabilities, layer descriptions, edge patterns)
• Output in both YAML and JSON formats, selectable via flag
• Reuse of existing ProposedCapability type and prompt engineering from prompts.py
• Validation of generated contracts against the ontology schema

Tasks

• Extract contract generation logic into a reusable function independent of GapDetector
• Create CLI entry point with argument parsing (description, output format, optional hints)
• Support YAML and JSON output formats
• Validate generated contracts against ontology schema structure
• Add unit tests for the standalone tool
• Document usage in project README or dedicated guide

Benefits

• Faster iteration when designing new capabilities — no need to run full discovery
• Lower barrier for contributors proposing new capabilities
• Composable building block — can be piped into scaffold.py or sync_skill_schemas.py
• Consistent contract quality through ontology-aware LLM generation

Acceptance Criteria

• Running the tool with a description string produces a valid typed contract with input_schema, output_schema, layer, risk, mutation, and suggested_edges
• Output can be produced in both YAML and JSON formats via a flag
• Generated contracts pass ontology schema validation
• The tool operates independently of the full discovery pipeline
• Existing ontology context (layer descriptions, nearby capabilities) is used to improve generation quality

Related Issues

• Follow-up from Automated capability discovery #87 (Automated capability discovery)