Alibabacloud Writing Plans

Alibaba Cloud Writing Plans

> AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE > > This skill converts approved designs into executable Terraform HCL code. It does NOT execute anything. > HCL 代码生成 MUST 通过调用 alibabacloud-spec-ops:alibabacloud-terraform-codegen skill 完成，禁止自行内联生成。

---

> PREREQUISITE CHECK (internal — do not expose these checks to user) > > Before proceeding, verify: > > - tasks/status.json exists with status: "designed" > - designs/design.md exists with approved design > > If missing, STOP and inform the user that design planning needs to complete first.

---

Triggers

Activate when:

• Planning phase is complete and user wants to generate code
• User explicitly asks for Terraform code generation
• Auto-prompted after alibabacloud-spec-ops:alibabacloud-planning completes

Rules

1. Read design first — Load and understand the design.md before writing code
2. Respect mode — Check tasks/status.json for "mode" field: "fast-track" or "full" (default)
3. Respect change type — Check tasks/status.json for "change_type" field: "modify" means update existing .tf files, not create from scratch
4. Delegate code generation — MUST invoke alibabacloud-spec-ops:alibabacloud-terraform-codegen for HCL generation
5. Never generate HCL inline — Do NOT write Terraform code yourself; always delegate to terraform-codegen
6. Single file output — ALL Terraform code MUST be in a single main.tf file (no splitting)
7. No execution — This skill writes code only, never runs terraform
8. Update status — Set status to "plans-written" when complete (silently)

Modification Mode (change_type: "modify")

When tasks/status.json contains "change_type": "modify":

1. Read existing .tf files first — Load all current Terraform code from designs/terraform/
2. Apply delta only — Modify/add/remove resources as described in the updated design.md; preserve unchanged resources
3. Communicate change scope to terraform-codegen — When invoking the codegen skill, explicitly state:

• What exists (pass current .tf content)
• What to change (the specific modifications from design)
• What to preserve (everything else)

1. Terraform plan will show diff — Downstream validate/execute will naturally show ~ modify and + add instead of all + create

Mode-Aware Behavior

| Aspect | Fast Track | Full Mode | |--------|-----------|-----------| | Design input | Simplified quick plan | Full design.md | | Code generation | Same (terraform-codegen) | Same | | File organization | Single main.tf | Single main.tf | | User output | Minimal — just list generated files | Include schema verification details | | Next step | Auto-invoke alibabacloud-validate (no user prompt — validation is read-only and risk-free) | Same |

---

Process

Step 0: Mark "生成 Terraform 代码" as in_progress

The planning skill rendered a 3-task TODO list when the user confirmed the design. At the very start of this skill's run, update that list via TodoWrite to mark task "生成 Terraform 代码" as in_progress. Do this before loading the design — the user sees the spinner align with what's happening.

Step 1: Load Design

Read .aliyun-ai-ops-spec/{name}/designs/design.md and extract:

• Resource list with specifications
• Network topology
• Security requirements
• Dependencies between resources
• Region, AZ, instance type choices

Produce a structured resource manifest (mental model):

Resources to generate:
1. VPC (cidr: 10.0.0.0/16, name: xxx)
2. VSwitch x2 (zone_h, zone_i)
3. Security Group + Rules
4. ECS x2 (c6.large)
5. SLB (internet)
6. RDS MySQL 8.0 (HA)
...

Step 2: Invoke terraform-codegen Skill

CRITICAL: You MUST invoke the Skill tool with alibabacloud-spec-ops:alibabacloud-terraform-codegen here.

The terraform-codegen skill will:

1. Query IaCService for supported products and resource type schemas
2. Consult Alibaba Cloud documentation for correct attribute names and values
3. Generate production-quality HCL with proper data sources, variables, and outputs
4. Verify attribute correctness against real API schemas

How to invoke:

Use the Skill tool:

Skill:
  skill: "alibabacloud-spec-ops:alibabacloud-terraform-codegen"

Then provide the terraform-codegen skill with a clear instruction based on the design:

> "Based on the following design, generate complete Terraform HCL code for Alibaba Cloud: > > [paste the structured resource manifest from Step 1] > > Requirements: > > - Region: {region from design} > - Resources: {list all resources with specs} > - Network: {VPC/subnet topology} > - Security: {SG rules, encryption, RAM} > - HA: {multi-AZ, backup configs} > > IMPORTANT: Output ALL code in a single main.tf file. Do NOT split into separate files. > File internal order: terraform {} → provider → variables → locals → data → resources → outputs"

Step 3: Write Generated Code to Single File

After terraform-codegen produces the HCL, write ALL code into a single main.tf:

.aliyun-ai-ops-spec/{name}/designs/terraform/
└── main.tf          # ALL code: terraform{}, provider, variables, locals, data, resources, outputs

MANDATORY rules:

• All Terraform code MUST live in one main.tf — never split into variables.tf, outputs.tf, locals.tf, etc.
• Internal ordering: terraform {} → provider → variables → locals → data sources → resources → outputs
• Every variable MUST have a default value — ensures zero-input deployment without failure
• This applies regardless of code length or complexity
• Reason: simplifies IaC Service remote execution (single template body) and guarantees deployability

Step 4: Generate CLI Scripts (if needed)

For operations not supported by Terraform, create CLI scripts in .aliyun-ai-ops-spec/{name}/designs/cli/:

#!/bin/bash
# Operations that require Alibaba Cloud CLI
# Only for actions that Terraform cannot handle
# Example: DNS record verification, certificate validation, etc.

aliyun   --

When to use CLI scripts (instead of Terraform):

• One-time setup operations (e.g., enable a service)
• Operations with no Terraform resource support
• Verification commands (e.g., check DNS propagation)

Step 5: Update Internal State

Silently update .aliyun-ai-ops-spec/{name}/tasks/status.json to status: "plans-written". Do NOT mention this to the user.

---

Why Delegate to terraform-codegen?

The terraform-codegen skill provides capabilities that inline generation cannot:

| Capability | terraform-codegen | Inline generation | |-----------|:--:|:--:| | Query real resource schemas via IaCService | ✅ | ❌ | | Verify attribute names against API | ✅ | ❌ | | Consult latest Alibaba Cloud docs | ✅ | ❌ | | Error recovery with documentation lookup | ✅ | ❌ | | Correct provider version constraints | ✅ | ⚠️ | | Data source usage for dynamic values | ✅ | ⚠️ |

The IaCService schema query ensures generated code uses correct, current attribute names — avoiding common issues like deprecated attributes, renamed fields, or invalid enum values.

---

After Writing Plans

1. Update the user-facing TODO list via TodoWrite:

• Mark "生成 Terraform 代码" → completed
• Mark "双轨评审：spec compliance + code quality" → in_progress

1. Inform user of the result (one paragraph, no question):

> "Terraform code generated successfully. > > Generated: main.tf — {N} resources, {M} variables, {K} outputs (all in single file) > > Code was generated with resource schemas verified via IaCService API. > > Now running review (spec compliance + code quality)..."

1. Immediately and automatically invoke alibabacloud-spec-ops:alibabacloud-validate — do NOT stop to ask the user. Validation is read-only (no cloud changes, no cost) and the next user-facing decision is whether to deploy, which alibabacloud-validate itself gates.

Do NOT:

• Ask "Would you like to proceed with validation?" — validation is not a decision the user needs to make
• Mention status.json updates
• Mention internal file paths for state tracking
• Mention the terraform-codegen delegation details (implementation detail)

---

Anti-Patterns (FORBIDDEN)

• ❌ Generating HCL code directly without invoking terraform-codegen
• ❌ Guessing resource attribute names from memory
• ❌ Using hardcoded values instead of variables
• ❌ Skipping IaCService schema verification
• ❌ Splitting code into multiple .tf files (variables.tf, outputs.tf, etc.)
• ❌ Omitting outputs for important resource values
• ❌ Proceeding to validate without completing main.tf

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aliyun
• Source: aliyun/alibabacloud-agent-toolkit
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.