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

[optimization2026]

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:

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:

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:

[
  {
    "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.