Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe

### What is your feature suggestion?

Add an optional machine-readable lifecycle contract for the main `agents-cli` skill workflow.

The current skills already describe a strong agent-building lifecycle:

```text
spec
-> scaffold
-> build
-> evaluate
-> deploy
-> publish
-> observe
```

I propose adding an optional **AISP V1.0.0 companion package** that documents the lifecycle gates as a structured contract.

AISP protocol reference:

https://github.com/AIXP-Labs/AISP

This should not replace the existing `SKILL.md` files.

This should not add AISP as a runtime dependency.

The goal is to make the existing lifecycle rules easier to test, audit, and preserve as the skills evolve.

Possible layout:

```text
skills/google-agents-cli-workflow/
├── SKILL.md
└── aisp/
└── google_agents_cli_lifecycle_contract_aisp/
├── aisp.aisop.json
├── README.md
└── evals/
└── lifecycle-traces/
```

A standard AISP V1.0.0 package could look like this:

```json
[
{
"role": "system",
"content": {
"protocol": "AISP V1.0.0",
"axiom_0": "Human_Sovereignty_and_Wellbeing",
"id": "google_agents_cli_lifecycle_contract_aisp",
"name": "Google Agents CLI Lifecycle Contract",
"version": "1.0.0",
"license": "Apache-2.0",
"summary": "A machine-checkable lifecycle contract for the agents-cli spec, scaffold, build, eval, deploy, publish, and observe workflow.",
"description": "Defines the non-negotiable phase order and evidence gates for coding agents that use agents-cli to build, evaluate, deploy, publish, and observe ADK agents.",
"flow_format": "mermaid",
"loading_mode": "node",
"tools": [
"filesystem",
"shell"
],
"params": {
"project_root": "string",
"user_goal": "string",
"deployment_target": "string?",
"publish_target": "string?"
},
"system_prompt": ""
}
},
{
"role": "user",
"content": {
"instruction": "STRICTLY OBEY aisp_contract; its non_negotiable rules are inviolable; then RUN aisop.main",
"user_input": "{user_input}",
"aisp_contract": {
"profile": "aisp.skill.v1",
"invocation": {
"mode": "manual_or_skill_runtime",
"when_to_use": [
"before a coding agent starts a new agents-cli project",
"before a coding agent modifies an existing ADK project with agents-cli",
"when a user asks to build, evaluate, deploy, publish, or observe an agent",
"when validating that agents-cli lifecycle phases were not skipped"
],
"when_not_to_use": [
"one-off informational questions about agents-cli",
"local code formatting only",
"manual terminal usage where the user does not want skill-driven lifecycle guidance",
"non-ADK projects with no agents-cli lifecycle involvement"
]
},
"non_negotiable": [
{
"rule": "Do not write agent code before the project goal and spec are captured.",
"enforced_by": "spec.step3:sys.assert"
},
{
"rule": "Do not scaffold or enhance a project before determining whether it is new or existing.",
"enforced_by": "classify_project.step2:sys.assert"
},
{
"rule": "Do not generate version-sensitive ADK code without official docs verification.",
"enforced_by": "docs_gate.step3:sys.assert"
},
{
"rule": "Do not mark an agent ready for deployment without an eval run or explicit user-approved no-eval mode.",
"enforced_by": "eval_gate.step3:sys.assert"
},
{
"rule": "Do not deploy to Google Cloud without explicit human approval.",
"enforced_by": "deploy_approval.step2:sys.io.confirm"
},
{
"rule": "Do not mark deployment complete without deployment status, endpoint metadata, and post-deploy validation.",
"enforced_by": "deploy.step4:sys.assert"
},
{
"rule": "Do not skip observability setup for production or shared deployments.",
"enforced_by": "observe.step2:sys.assert"
},
{
"rule": "Every lifecycle run must emit a trace with phase decisions, skipped phases, eval status, approval status, deploy status, and observe status.",
"enforced_by": "trace.step2:sys.assert"
}
],
"discovery": {
"category": "agent_lifecycle",
"tags": [
"agents-cli",
"adk",
"lifecycle",
"scaffold",
"eval",
"deploy",
"observe",
"aisp"
]
},
"risk_level": "high",
"resources": [
{
"id": "project_root",
"path": "{project_root}",
"kind": "repository",
"mode": "read_only",
"when": "Read before lifecycle classification.",
"scope": "skill"
},
{
"id": "lifecycle_trace",
"path": "evals/lifecycle-traces/",
"kind": "trace_dir",
"mode": "read_write",
"when": "Write after lifecycle run.",
"scope": "skill"
}
]
},
"aisop": {
"main": "graph TD\n classify_project[Classify project state] --> spec[Capture spec]\n spec --> scaffold[Scaffold or enhance]\n scaffold --> docs_gate[Verify official docs]\n docs_gate --> build[Build agent]\n build --> eval_gate[Run eval gate]\n eval_gate --> deploy_approval[Ask human deploy approval]\n deploy_approval --> deploy[Deploy]\n deploy --> publish[Publish if requested]\n publish --> observe[Configure observability]\n observe --> trace[Write lifecycle trace]\n trace --> end_node((End))"
},
"functions": {
"classify_project": {
"step1": "Inspect project_root for existing agents-cli manifest, ADK app structure, eval files, and deployment config.",
"step2": "sys.assert('project state classified as new existing or unsupported', 'Project state must be classified before scaffold/enhance')",
"output_mapping": "project_state"
},
"spec": {
"step1": "Capture user goal, target users, tools, constraints, success criteria, deployment intent, and evaluation intent.",
"step2": "Write or update .agents-cli-spec.md if the workflow requires a persisted spec.",
"step3": "sys.assert('spec exists before code generation', 'Agent code must not be written before spec')",
"output_mapping": "spec_status"
},
"scaffold": {
"step1": "Run scaffold, scaffold enhance, or init according to project_state.",
"output_mapping": "scaffold_status"
},
"docs_gate": {
"step1": "Identify version-sensitive APIs, SDK methods, model names, eval APIs, deploy specs, and publish fields.",
"step2": "Verify relevant official docs before generating code/config.",
"step3": "sys.assert('official docs verified for version-sensitive surfaces', 'Official docs verification required')",
"output_mapping": "docs_verification"
},
"build": {
"step1": "Build or modify the ADK agent using the spec and docs verification.",
"output_mapping": "build_status"
},
"eval_gate": {
"step1": "Run or update eval dataset and grading if applicable.",
"step2": "Record eval results, skipped reason, or explicit user-approved no-eval mode.",
"step3": "sys.assert('eval completed or explicit no-eval approval exists', 'Eval gate required before deployment readiness')",
"output_mapping": "eval_status"
},
"deploy_approval": {
"step1": "Summarize deploy target, project, region, expected resources, eval status, and risks.",
"step2": "sys.io.confirm('Proceed with deployment?') -> deploy_approved",
"output_mapping": "deploy_approval_status"
},
"deploy": {
"step1": "Deploy only if deploy_approved is true.",
"step2": "Poll status where deploy target requires asynchronous status.",
"step3": "Run post-deploy validation.",
"step4": "sys.assert('deployment status and endpoint metadata recorded', 'Deployment completion metadata required')",
"output_mapping": "deploy_status"
},
"publish": {
"step1": "If publish_target is set, publish/register the agent after deploy validation.",
"output_mapping": "publish_status"
},
"observe": {
"step1": "Configure or verify observability for production/shared deployment.",
"step2": "sys.assert('observability status recorded for production/shared deployment', 'Observability gate required')",
"output_mapping": "observability_status"
},
"trace": {
"step1": "Write lifecycle trace with project_state, spec_status, scaffold_status, docs_verification, build_status, eval_status, deploy_approval_status, deploy_status, publish_status, and observability_status.",
"step2": "sys.assert('lifecycle trace contains required phases', 'Lifecycle trace incomplete')",
"output_mapping": "lifecycle_trace"
},
"end_node": {
"step1": "Return lifecycle_trace."
}
}
}
}
]
```

### What will this enable you to do?

This would make the existing agents-cli lifecycle easier to preserve and test.

It would enable:

- coding agents to follow the intended phase order more reliably;
- maintainers to test that lifecycle gates are not skipped;
- users to see why a phase was skipped or required;
- eval/deploy/observe behavior to be auditable as a single workflow;
- docs and skills to share one lifecycle contract;
- future skills to add gates without making the main workflow skill much longer.

This is especially useful because agents-cli is not only a command tool. It is also a skill suite that teaches coding agents how to build, evaluate, deploy, publish, and observe ADK agents.

### Additional context

This should be optional.

Non-goals:

- Do not replace the current SKILL.md files.
- Do not require agents-cli runtime to execute AISP.
- Do not block standalone CLI users.
- Do not require all skills to have AISP packages.
- Do not change the user-facing command names.

A small MVP could be:

1. Document the lifecycle contract.
2. Add tests that mirror the non-negotiable gates.
3. Optionally include the AISP artifact as `skills/google-agents-cli-workflow/aisp/...`.
4. Emit a lifecycle trace in debug/eval mode.
5. Use the contract as a reference for future validators.

Start with skills/google-agents-cli-workflow/SKILL.md and compare its lifecycle with the proposed aisp/ package layout. Review the AISP V1.0.0 contract and the evals/lifecycle-traces/ location, then define the smallest optional package and tests that cover the listed lifecycle gates. Done means the contract is documented, does not replace SKILL.md or add a runtime dependency, and the proposed trace and validation behavior are specified.

Written by the indexing model from the issue text.