Add an init command to create agents-cli-manifest.yaml for existing ADK projects

[ftnext]

What is your feature suggestion?

I would like agents-cli to provide a lightweight initialization command that writes agents-cli-manifest.yaml into an existing ADK project, without scaffolding a new project or adding deployment files.

For example, the command could be:

agents-cli init

or:

agents-cli scaffold init

Ideally this would feel similar to hatch new --init: when run from an existing project root, it detects reasonable defaults and creates the minimal project metadata needed by agents-cli commands.

A possible generated manifest could be:

name: my-agent
agent_directory: app
region: us-east1
create_params:
  deployment_target: none

It would also be helpful to support flags such as:

agents-cli init --agent-directory app --name my-agent
agents-cli init --dry-run
agents-cli init --yes

The command should avoid overwriting an existing agents-cli-manifest.yaml unless an explicit --force flag is provided.

What will this enable you to do?

This would make it much easier to adopt agents-cli in existing ADK projects.

Right now, after adding eval files to an existing project by skill equiped coding agent, running:

agents-cli eval run --all

fails with:

Error: No agents-cli-manifest.yaml found in the current directory or its parents.
  Run this command from your project root, or create a project first:
    agents-cli create my-agent

For an existing ADK project, I do not necessarily want to create a new project or run a broader scaffold/enhance flow. I only need the minimal manifest so commands like agents-cli eval run, agents-cli info, and other project-aware commands can locate the project root and agent directory.

A lightweight init command would provide a clear migration path:

1. Start with an existing ADK project.
2. Add evalsets/config.
3. Run agents-cli init.
4. Run agents-cli eval run --all.

This would reduce friction for users who already have ADK agents and want to gradually adopt agents-cli workflows.

Additional context

The ideal UX is similar to hatch new --init, where an existing project can be initialized in place.
https://hatch.pypa.io/dev/cli/reference/#hatch-new

Nice-to-have detection behavior:

• infer name from pyproject.toml or the current directory name
• infer agent_directory from common ADK layouts such as app/, a package listed in pyproject.toml, or a directory containing agent.py / root_agent.yaml
• default deployment_target to none so local eval usage works without opting into deployment scaffolding
• print the generated manifest and explain what was detected
• provide flags for explicit values when auto-detection is wrong

This would complement agents-cli create for new projects and agents-cli scaffold enhance for adding broader scaffold/deployment support, while covering the smaller "initialize this existing ADK project for agents-cli" use case.

[sushicw]

Thank you for this!

Just adding some notes:

• We would first need to make sure we are very clear about what parts of agents-cli require our opinionated project structure, and which should work for any arbitrary ADK project. Otherwise, we risk having something that breaks in unexpected ways because agents-cli is assuming structure that doesn't match the existing ADK project.
• This could possibly also be done as part of enhance, perhaps with a flag like --from-adk-project if needed.
• I did try doing a basic adk create project followed by agents-cli scaffold enhance . from within the folder, and I agree that as-is it isn't the experience we'd hope for. (Among other things, you end up with a copy of agent.py added to a subfolder under the original agent folder root, in addition to the original).

[optimization2026]

I think this is a good fit for a lightweight project manifest contract.

For existing ADK projects, users need:

detect existing layout
  -> infer minimal manifest
  -> validate agent directory
  -> write agents-cli-manifest.yaml
  -> do not scaffold or add deploy files

A standard AISP V1.0.0 companion contract could describe the init behavior:

[
  {
    "role": "system",
    "content": {
      "protocol": "AISP V1.0.0",
      "axiom_0": "Human_Sovereignty_and_Wellbeing",
      "id": "google_agents_cli_existing_project_init_aisp",
      "name": "Google Agents CLI Existing Project Init Contract",
      "version": "1.0.0",
      "license": "Apache-2.0",
      "summary": "A machine-checkable AISP package for initializing agents-cli manifest in existing ADK projects.",
      "description": "Creates a minimal agents-cli-manifest.yaml in an existing project without scaffolding new project files or deployment files.",
      "flow_format": "mermaid",
      "loading_mode": "node",
      "tools": ["filesystem"],
      "params": {
        "project_root": "string",
        "agent_directory": "string?",
        "name": "string?",
        "force": "boolean",
        "dry_run": "boolean"
      },
      "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": "project_initialization",
          "when_to_use": [
            "when an existing ADK project needs agents-cli-manifest.yaml",
            "when eval files were added to an existing project",
            "when agents-cli info or eval cannot find a manifest"
          ],
          "when_not_to_use": [
            "creating a brand new project from template",
            "enhancing a project with scaffolded deployment or CI files",
            "overwriting an existing manifest without --force"
          ]
        },
        "non_negotiable": [
          {
            "rule": "Do not scaffold a new project or add deployment files during lightweight init.",
            "enforced_by": "write_manifest.step2:sys.assert"
          },
          {
            "rule": "Do not overwrite an existing agents-cli-manifest.yaml unless --force is explicit.",
            "enforced_by": "check_existing.step2:sys.assert"
          },
          {
            "rule": "Generated manifest must include project name, agent_directory, region, and deployment_target:none unless user specifies otherwise.",
            "enforced_by": "validate_manifest.step2:sys.assert"
          },
          {
            "rule": "Dry-run must show the manifest content and no files should be written.",
            "enforced_by": "dry_run.step2:sys.assert"
          }
        ],
        "discovery": {
          "category": "project_initialization",
          "tags": ["agents-cli", "adk", "existing-project", "manifest", "init", "aisp"]
        },
        "risk_level": "low",
        "resources": [
          {
            "id": "project_root",
            "path": "{project_root}",
            "kind": "repository",
            "mode": "read_only",
            "when": "Read before initializing existing project manifest.",
            "scope": "skill"
          }
        ]
      },
      "aisop": {
        "main": "graph TD\n    inspect[Inspect existing project] --> check_existing[Check existing manifest]\n    check_existing --> infer[Infer manifest fields]\n    infer --> validate_manifest[Validate manifest]\n    validate_manifest --> dry_run{Dry run?}\n    dry_run -->|yes| show[Show manifest only]\n    dry_run -->|no| write_manifest[Write manifest]\n    show --> end_node((End))\n    write_manifest --> end_node"
      },
      "functions": {
        "inspect": {
          "step1": "Inspect project_root for ADK project shape, candidate agent directories, pyproject.toml, app folders, eval folders, and existing config.",
          "output_mapping": "project_detection"
        },
        "check_existing": {
          "step1": "Check whether agents-cli-manifest.yaml already exists.",
          "step2": "sys.assert('no existing manifest or force is true', 'Existing manifest must not be overwritten without --force')",
          "output_mapping": "existing_manifest_status"
        },
        "infer": {
          "step1": "Infer name, agent_directory, region, and create_params.deployment_target.",
          "output_mapping": "manifest_draft"
        },
        "validate_manifest": {
          "step1": "Validate manifest_draft fields and agent_directory existence.",
          "step2": "sys.assert('manifest contains required minimal fields', 'Minimal init manifest missing required fields')",
          "output_mapping": "manifest_validation"
        },
        "dry_run": {
          "step1": "If dry_run is true, display manifest_draft and planned write path.",
          "step2": "sys.assert('dry run writes no files', 'Dry-run must not write manifest')",
          "output_mapping": "dry_run_status"
        },
        "write_manifest": {
          "step1": "Write agents-cli-manifest.yaml only after validation passes.",
          "step2": "sys.assert('no scaffold/deployment files written', 'Lightweight init must only write manifest')",
          "output_mapping": "write_status"
        },
        "show": {
          "step1": "Return manifest preview and warnings.",
          "output_mapping": "manifest_preview"
        },
        "end_node": {
          "step1": "Return manifest_validation, dry_run_status or write_status."
        }
      }
    }
  }
]

This would make adoption easier for existing ADK users without conflating:

init:
  add minimal manifest

scaffold:
  create or enhance project structure

deploy setup:
  add deployment or infra files

[benagentai93-dot]

I validated a concrete, lightweight init contract against the v1.3.1 source baseline (5a306f8956cb1eeae69f9709de0e4d61b44e11e7) in a fork.

Proposed fixed interface

agents-cli init [PATH]
  --name
  --agent-directory
  --dry-run
  --yes
  --force

PATH defaults to . and must already be a directory. The command is Python-ADK-only in this first version and does not install, scaffold, enhance, or deploy anything. It produces only:

name: <normalized-project-name>
agent_directory: <relative-agent-directory>
deployment_target: none

Detection and failure contract

• Name precedence: --name, then pyproject.toml [project].name, then the PATH directory name; reuse the existing project-name normalization.
• An explicit --agent-directory must be a relative existing directory inside PATH (including after symlink resolution) and contain agent.py or root_agent.yaml.
• Automatic directory precedence:
  1. valid app/;
  2. root-package or src/ package candidate derived from the pyproject project name;
  3. the unique direct child containing an agent marker.
• Multiple candidates at the same priority prompt only on a TTY without --yes; non-interactive mode and --yes fail closed and request --agent-directory.
• No candidate is an error; the command does not silently create or assume app/.
• A root-level agent can still be selected explicitly with --agent-directory .; it is not auto-selected.
• Explicit non-Python project markers are rejected as unsupported. A valid Python pyproject.toml may coexist with auxiliary package.json or pom.xml files.

Output and overwrite contract

• --dry-run writes parseable YAML to stdout only, makes no filesystem changes, and can preview even when a manifest already exists.
• Notices remain on stderr.
• An existing manifest is byte-identical after the default path and after --yes; --yes never implies overwrite.
• Only --force replaces it, using a temporary file in the same directory and os.replace().
• If replacement fails, the original stays byte-identical and the temporary file is cleaned up.

Evidence

• Pre-implementation regression run: 24 failures because the command did not exist.
• Final focused matrix: 33 passed, covering name/directory precedence, app/, root and src/ package layouts, unique/multiple/no candidates, TTY and non-interactive behavior, symlink escape, unsupported languages, dry-run stdout, overwrite protection, atomic replacement, replacement failure, and PATH isolation.
• Full local gate: Ruff passed; Ty passed; pytest tests passed with 132 tests; uv build passed.
• The built wheel installed normally under Python 3.11 and 3.13; both returned agents-cli, version 1.3.1.
• Fork branch: https://github.com/benagentai93-dot/agents-cli/tree/codex/batch-6-init-existing-project
• Fork commit: benagentai93-dot@55d9f7c
• Local and fetched fork trees both equal 815eabdf113a3cff237e1380d74a1b805b73b7a5.

No upstream PR was opened, in line with the repository's current contribution policy.