feat: scripts/MANIFEST.yaml — agent-navigable tool discovery template

[zkSoju]

Summary

Adds scripts/MANIFEST.yaml — a machine-readable tool declaration template that lets agents discover construct scripts without reading source code. Updates CONTRIBUTING.md with navigability guidance.

Why

Research across 6 AI firms + audit of all 23 constructs in the network revealed:

• 70% of scripted constructs have no --help flag — agents must read source to discover args
• Every major AI firm (Anthropic, OpenAI, Pi, Vercel, MCP) solves this with JSON Schema tool definitions
• Our constructs lack the CLI equivalent — scripts exist but aren't self-describing

The manifest bridges this gap at the construct level, mapping directly to industry patterns:

Manifest field	Anthropic	OpenAI	MCP
name + description	tool.name/description	function.name/description	tool.name/description
args	input_schema	parameters	inputSchema
output	tool_result	return value	outputSchema
danger_level	system prompt	—	annotations.destructiveHint

What's in the template

scripts/MANIFEST.yaml — 4 example script declarations:

• TypeScript search tool (reference: k-hole/dig-search.ts)
• Bash diff tool (reference: ruggy/corpus-diff.sh)
• Python generator (reference: the-mint/generate-gemstone.py)
• Batch pipeline (reference: k-hole/deep-research.ts)

Each declares: name, description, runtime, args (with types/defaults), output format/fields, credentials, side effects, danger_level.

CONTRIBUTING.md updated:

• Navigability section explaining MANIFEST.yaml's role
• AI firm comparison table
• Self-description convention (--help)
• Reference implementation pointers (3 languages)
• Explicit SKILL.md invocation guidance

Design decisions

• Structure, not prescription: The manifest shows the SHAPE. Constructs adapt it to their needs. Delete unused examples.
• Construct-level, not runtime-level: Each construct owns its manifest. The Loa loader could read it in the future (loa#449 scope), but it works today as a convention file.
• Hounfour-compatible: Field shapes align with Hounfour's AgentDescriptor/Capability schemas for future protocol-level validation.
• Backward compatible: Existing constructs without MANIFEST.yaml continue working. This is additive.

Research basis

• 3 parallel research agents: AI firm patterns, 23-construct audit, 5-layer ecosystem mapping
• Key finding: Open Agent Skills standard (agentskills.io) is 80% compatible with our existing construct format
• Our capabilities stanza (model_tier, danger_level, effort_hint) is unique and valuable — no other system has it

Test plan

• yq eval '.' scripts/MANIFEST.yaml validates cleanly
• New construct created from template includes MANIFEST.yaml
• CONTRIBUTING.md renders correctly on GitHub

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.