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

Bắt đầu với skills/google-agents-cli-workflow/SKILL.md và so sánh vòng đời của nó với bố cục package aisp/ được đề xuất. Xem lại contract AISP V1.0.0 và vị trí evals/lifecycle-traces/, sau đó xác định package tùy chọn nhỏ nhất và các test bao quát những lifecycle gate được liệt kê. Hoàn thành có nghĩa là contract đã được ghi lại, không thay thế SKILL.md hoặc thêm dependency runtime, đồng thời hành vi trace và validation được đề xuất đã được đặc tả.

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.