@zalom/plastic 1.0.0-beta.9 → 1.0.0

package/skills/update/SKILL.md

@@ -13,58 +13,69 @@ description: Use when updating Plastic. Runs the `update` verb, which reads the
 ## What it does
 
 `update` is a single deterministic command. It reads `~/.plastic/VERSION`, derives the
-channel from the version string (`-alpha`/`-beta`/none → stable), queries `npm` dist-tags,
+channel from the version string (`-alpha`/`-beta`/none -> stable), queries `npm` dist-tags,
 and advances to the **next version on the current channel**. "Already up to date" is a
-clean no-op. You do not compute the target yourself — the script does.
+clean no-op. You do not compute the target yourself, the script does.
+
+## Channel rule
+
+If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version containing
+`-alpha` means `@alpha`, `-beta` means `@beta`, otherwise `@latest`. If not installed
+(first install), default to `@beta`. The user can always override with
+`--alpha` / `--beta` / `--latest`.
 
 ## Flags
 
 | Flag | Behaviour |
 |------|-----------|
 | (none) | Advance to the next version on the **current** channel |
-| `--latest` | Switch to / advance the **stable** channel (toward stability — frictionless) |
+| `--latest` | Switch to / advance the **stable** channel (toward stability, frictionless) |
 | `--beta` | Switch to / advance the **beta** channel |
-| `--alpha` | Switch to / advance the **alpha** channel (bleeding edge — confirmed if moving down in stability) |
+| `--alpha` | Switch to / advance the **alpha** channel (bleeding edge, confirmed if moving down in stability) |
 
 Switching toward a more stable channel is frictionless; switching toward bleeding edge is
 confirmed. To roll **back** to a previously-installed version, use `plastic-versions`.
 
 ## Prerequisites
 
-Plastic must be installed (`~/.plastic/VERSION` present). If not, run
-`npx @zalom/plastic install --claude` first.
+Plastic must be installed (`~/.plastic/VERSION` present). If not, run `plastic-install`
+first (or `npx -y @zalom/plastic@beta install --claude` directly).
 
 ## Procedure
 
 ### Step 1: Run the update
 
 ```bash
-npx @zalom/plastic update            # next version on the current channel
-# or: npx @zalom/plastic update --beta   /   --latest   /   --alpha
+npx -y @zalom/plastic@<channel> update --claude
+# channel switch: append --beta / --latest / --alpha
+# other agents: append --codex / --hermes / --all
 ```
 
-Append the agent flag(s) if not just Claude (`--codex`, `--hermes`, `--all`).
-The command prints the transition (`vX → vY`) or "already up to date", and records the
-move in the append-only `~/.plastic/versions.json` ledger.
+`bunx -y @zalom/plastic@<channel> update --claude` works as a fallback if `npx` is
+unavailable. The command prints the transition (`vX -> vY`) or "already up to date", runs
+a post-update doctor summary, and records the move in the append-only
+`~/.plastic/versions.json` ledger.
 
-### Step 2: Announce key changes
+### Step 2: Relay the result, announce convention changes
 
-After it completes, read `~/.plastic/PLASTIC.md` and announce convention changes that
-affect the current session:
+Relay what `update` printed, do not recompute the version transition or the doctor
+summary:
 
 ```
-Plastic updated to vX.Y.Z (channel).
-
-Key changes:
-- [notable convention changes, if any]
-
-Recommendation: run /clear for a clean session with all new conventions loaded.
+Plastic update (<channel>)
+Command:  npx -y @zalom/plastic@<channel> update --claude <flags>
+Version:  <before> -> <after>
+Doctor:   <relayed summary, or "all clear">
 ```
 
-### Step 3: Health check
+Then read `~/.plastic/PLASTIC.md` and announce convention changes that affect the
+current session, and recommend `/clear` for a clean session with all new conventions
+loaded.
+
+### Step 3: Health check only on a relayed failure
 
-Invoke `plastic-doctor`. If all checks pass: **"Health check: all clear."** Otherwise show
-the report and offer to fix.
+If the relayed doctor summary shows a failure, invoke `plastic-doctor` for the full
+report and offer to fix. If it already reads clean, do not re-run doctor.
 
 ### Step 4: Commit + clear update cache
 

package/skills/versions/SKILL.md

@@ -3,7 +3,7 @@ name: plastic-versions
 description: Use when the user wants to see their Plastic version history or roll back to a previously-installed version after a bad release. Manages the local, append-only versions.json ledger and steps between versions the user has actually run. For moving to a brand-new release, use plastic-update instead.
 ---
 
-# Plastic Versions — local version time-machine
+# Plastic Versions: local version time-machine
 
 ## When to Use
 - "show plastic versions", "version history", "what versions have I run"
@@ -11,11 +11,18 @@ description: Use when the user wants to see their Plastic version history or rol
 - A new version broke something and the user wants their last known-good build
 
 For upgrading to a **new** release, use `plastic-update`. This skill only navigates
-versions you have **already installed** — the ones recorded in the ledger.
+versions you have **already installed**, the ones recorded in the ledger.
+
+## Channel rule
+
+`versions` restores whichever build you pick from the ledger, it does not take a channel
+flag for the target. The pinned `<channel>` below is only the npx invocation itself:
+derive it from `~/.plastic/VERSION` the same way as the other lifecycle skills,
+`-alpha` -> `@alpha`, `-beta` -> `@beta`, otherwise `@latest`.
 
 ## The ledger
 
-`~/.plastic/versions.json` is an **append-only JSONL** ledger — one line per version
+`~/.plastic/versions.json` is an **append-only JSONL** ledger, one line per version
 change, never modified or deleted:
 
 ```json
@@ -23,15 +30,16 @@ change, never modified or deleted:
 {"version":"1.0.0-alpha.18","action":"update","at":"..."}
 ```
 
-`action` ∈ `install | reinstall | update | downgrade` (derived from version direction; the
-channel is derived from the version string, never stored). It is a troubleshooting record.
+`action` is one of `install`, `reinstall`, `update`, `downgrade` (derived from version
+direction; the channel is derived from the version string, never stored). It is a
+troubleshooting record.
 
 ## Procedure
 
 ### Show history
 
 ```bash
-npx @zalom/plastic versions
+npx -y @zalom/plastic@<channel> versions
 ```
 
 Prints the table with the currently-installed version marked. If the most recent action was
@@ -40,8 +48,8 @@ a `downgrade`, it asks whether to keep rolling back.
 ### Roll back
 
 ```bash
-npx @zalom/plastic versions --downgrade                    # one step back
-npx @zalom/plastic versions --downgrade --version 1.0.0-alpha.15   # to a specific run
+npx -y @zalom/plastic@<channel> versions --downgrade                    # one step back
+npx -y @zalom/plastic@<channel> versions --downgrade --version 1.0.0-alpha.15   # to a specific run
 ```
 
 Rollback targets are restricted to versions in the ledger (only builds you have actually
@@ -51,15 +59,22 @@ re-fetched from npm and re-synced; your intent store, config, and the ledger are
 ### Step forward (after a rollback)
 
 ```bash
-npx @zalom/plastic versions --upgrade                      # one step forward in your history
+npx -y @zalom/plastic@<channel> versions --upgrade                      # one step forward in your history
 ```
 
 ### After any change
 
-Run `plastic-doctor` to confirm health, and suggest `/clear` so the session picks up the
-swapped conventions.
+Run `plastic-doctor` to confirm health, then emit the reporting block and suggest
+`/clear` so the session picks up the swapped conventions:
+
+```
+Plastic versions (<channel>)
+Command:  npx -y @zalom/plastic@<channel> versions <flags>
+Version:  <before> -> <after>
+Doctor:   <summary or "all clear">
+```
 
 ## Notes
-- The ledger is **never** edited or pruned — it is the audit trail.
+- The ledger is **never** edited or pruned, it is the audit trail.
 - Downgrades cannot un-migrate a store-format change; if a warning appears, surface it to
   the user rather than forcing the rollback.

package/skills/writing-plans/SKILL.md

@@ -48,70 +48,13 @@ This structure informs the task decomposition. Each task should produce self-con
 - "Run the tests and make sure they pass" - step
 - "Commit" - step
 
-## Plan Document Header
+## Plan Format
 
-**Every plan MUST start with this header:**
-
-```markdown
-# [Feature Name] Implementation Plan
-
-> **For agentic workers:** Use `plastic-executing-plan` to implement this plan task-by-task.
-
-**Goal:** [One sentence describing what this builds]
-
-**Architecture:** [2-3 sentences about approach]
-
-**Tech Stack:** [Key technologies/libraries]
-
-**Intent:** {id} — {name}
-
----
-```
-
-## Task Structure
-
-````markdown
-### Task N: [Component Name]
-
-**Files:**
-- Create: `exact/path/to/file.rb`
-- Modify: `exact/path/to/existing.rb:123-145`
-- Test: `test/exact/path/to/test.rb`
-
-- [ ] **Step 1: Write the failing test**
-
-```ruby
-def test_specific_behavior
-  result = function(input)
-  assert_equal expected, result
-end
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
-Expected: FAIL with "undefined method"
-
-- [ ] **Step 3: Write minimal implementation**
-
-```ruby
-def function(input)
-  expected
-end
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add test/path/test.rb lib/path/file.rb
-git commit -m "feat: add specific feature"
-```
-````
+For the exact plan/task/checklist/action format (the Plan Document Header
+template, the full Task Structure worked example, and the checklist.md /
+actions/ACTION_N.md templates), read `references/plan-format.md` before
+writing plan.md. Every plan starts with the header template and decomposes
+into tasks matching the Task Structure shape.
 
 ## No Placeholders
 
@@ -144,31 +87,10 @@ If you find issues, fix them inline. No need to re-review — just fix and move
 ## Plastic Artifacts
 
 After writing `plan.md`, create two additional artifacts in the intent directory:
-
-### checklist.md
-
-Execution registry with one checkbox per task. Format:
-
-```markdown
-# Checklist — Intent {id}: {name}
-
-- [ ] Task 1: {task title}
-- [ ] Task 2: {task title}
-- [ ] Task 3: {task title}
-...
-```
-
-### actions/ACTION_N.md
-
-One file per task. Each action is self-contained — a subagent can execute it without reading the plan.
-
-```markdown
-# Action {N}: {task title}
-
-{Full task text copied from plan.md — all steps, all code, all commands. Nothing omitted.}
-```
-
-Create the `actions/` directory inside the intent directory: `{intent_dir}/actions/`
+`checklist.md` (execution registry with one checkbox per task) and
+`actions/ACTION_N.md` (one self-contained file per task, in an `actions/`
+directory inside the intent directory). For the exact format of both, read
+`references/plan-format.md`.
 
 ## Git Commit
 

package/skills/writing-plans/references/plan-format.md

@@ -0,0 +1,102 @@
+# Plan, Checklist, and Action Format
+
+The exact templates for `plan.md`'s header and task structure, and for the
+`checklist.md` and `actions/ACTION_N.md` artifacts. Read this before writing
+plan.md so the shape matches on the first pass.
+
+## Table of Contents
+
+- [Plan Document Header](#plan-document-header)
+- [Task Structure (worked example)](#task-structure-worked-example)
+- [checklist.md format](#checklistmd-format)
+- [actions/ACTION_N.md format](#actionsaction_nmd-format)
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For agentic workers:** Use `plastic-executing-plan` to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+**Intent:** {id} — {name}
+
+---
+```
+
+## Task Structure (worked example)
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.rb`
+- Modify: `exact/path/to/existing.rb:123-145`
+- Test: `test/exact/path/to/test.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+def test_specific_behavior
+  result = function(input)
+  assert_equal expected, result
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
+Expected: FAIL with "undefined method"
+
+- [ ] **Step 3: Write minimal implementation**
+
+```ruby
+def function(input)
+  expected
+end
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test/path/test.rb lib/path/file.rb
+git commit -m "feat: add specific feature"
+```
+````
+
+## checklist.md format
+
+Execution registry with one checkbox per task. Format:
+
+```markdown
+# Checklist — Intent {id}: {name}
+
+- [ ] Task 1: {task title}
+- [ ] Task 2: {task title}
+- [ ] Task 3: {task title}
+...
+```
+
+## actions/ACTION_N.md format
+
+One file per task. Each action is self-contained — a subagent can execute it without reading the plan.
+
+```markdown
+# Action {N}: {task title}
+
+{Full task text copied from plan.md — all steps, all code, all commands. Nothing omitted.}
+```
+
+Create the `actions/` directory inside the intent directory: `{intent_dir}/actions/`

package/templates/config.yml

@@ -11,3 +11,11 @@ agent:
   parallel_mode: linear
 architect:
   style:
+
+# Per-agent model override (intent 116). Uncomment and set to a Claude Code
+# alias (opus, sonnet, haiku) to override the shipped tier for one agent. With
+# no entry, the shipped default applies. Never resolves to Fable.
+# agents:
+#   models:
+#     plastic-executor: sonnet
+#     plastic-enforcer: opus

package/templates/outcome.md

@@ -1,3 +1,6 @@
+---
+disposition: delivered|abandoned
+---
 # Outcome: <intent name>
 
 ## Summary

package/templates/revisions.md

@@ -0,0 +1,58 @@
+# revisions.md
+
+<!--
+FORM reference. A live revisions.md exists in an intent directory ONLY when structural
+maintenance actually happened. It is never scaffolded at intent birth, it carries no
+placeholder sentinel, and its mere presence signals that this intent underwent structural
+(not conceptual) change.
+
+Rules:
+- Append-only. Newest entry at the BOTTOM. Never edit or reorder past entries.
+- One entry per relocated item (one section, one file, or one ref per entry).
+- Move-and-record: remove the misplaced thing from its artifact and preserve it IN FULL
+  here. Never rewrite, summarize, or reinterpret delivered meaning. A change to delivered
+  meaning is a new intent, not a revision.
+- Header form: "## Revision vN - YYYY-MM-DD-HH:MM" (N increments by one per entry).
+
+Fields:
+- Why:            one sentence naming the broken rule, ending with "[rule: <tag>]".
+- Prior location: the artifact plus the section or path the content came from.
+- Content held:   the verbatim removed content, as an indented block (block form), OR
+- Change:         a one-line "removed X (before: ... -> after: ...)" for a frontmatter
+                  edit, used instead of a Content held block.
+
+Stray file: embed the file's full content as the Content held block and delete the
+original; Prior location names the filename. revisions.md is the single container.
+
+Violation-tag catalog (starter set; free-text tags are allowed):
+- unsanctioned-section : a top-level section the sanctioned-section rule now rejects
+- phantom-section      : a section referenced but not present or not sanctioned
+- stray-file           : a file that does not belong in the intent directory
+- dangling-ref         : a link or reference to something that no longer exists
+- broken-chain         : a chain frontmatter edge to an intent that no longer exists
+- broken-source        : a sources frontmatter edge to an intent that no longer exists
+- misplaced-content    : content that belongs in a different artifact or section
+
+The examples below show the three variants. Delete them when you write the first real
+entry; keep the "# revisions.md" title line above.
+-->
+
+## Revision v1 - 2026-06-30-14:35
+- Why: unsanctioned top-level section left over from an early draft [rule: unsanctioned-section]
+- Prior location: intent.md - ## Scope
+- Content held:
+
+  ## Scope
+  <the full content that was removed, verbatim>
+
+## Revision v2 - 2026-06-30-15:02
+- Why: chain edge to an intent that no longer exists [rule: broken-chain]
+- Prior location: intent.md frontmatter - chain
+- Change: removed "99x"  (before: ["4a1a", "99x"]  ->  after: ["4a1a"])
+
+## Revision v3 - 2026-06-30-15:20
+- Why: a stray notes file that does not belong in the intent directory [rule: stray-file]
+- Prior location: notes-old.md
+- Content held:
+
+  <the full content of notes-old.md, verbatim; the original file is then deleted>

package/templates/roadmap.md

@@ -0,0 +1,30 @@
+# Roadmap: <name>
+
+(one-line meta: what this roadmap delivers, and which tier it lives in. `roadmaps/` is a sibling
+of `INDEX.md` — a project's root or the global `~/.plastic/`, never inside `store/`. When this
+roadmap's goal is reached, move this file from `roadmaps/{slug}.md` to
+`roadmaps/archived/{slug}.md`; `roadmaps/` itself lists only live roadmaps.)
+
+## Goal
+(a checkable prose condition — one or a few sentences a human or coordinator reads to decide the
+roadmap is done. Not an executable checker.)
+
+## Waves
+Entries in a wave are parallel-safe; waves run top to bottom. The checkbox is checked once an entry
+is delivered, unchecked otherwise; the trailing token after the em-dash is the precise mirrored
+status (queued | delivering | delivered | abandoned | blocked) from INDEX.md. INDEX always wins on
+any conflict between the checkbox/token here and INDEX's real status.
+
+### Wave 1
+- [ ] <intent-id> <title> — queued
+- [ ] <intent-id> <title> — queued
+
+### Wave 2
+- [x] <intent-id> <title> — delivered
+
+## Log
+(append-only, dated, one line per event. Each line is one plain-language, EM-to-CTO-voice sentence:
+what shipped and its impact for a non-expert reader, no jargon or internal codenames, ending with a
+link to that entry-intent's `outcome.md`. Never restate outcome detail here; link to it instead.
+Newest at the bottom.)
+- 2026-01-01 00:00 UTC Shipped the first wave of this roadmap; see store/<intent-id>--<slug>/outcome.md.

package/skills/writing-instructions/SKILL.md

@@ -1,159 +0,0 @@
----
-name: plastic-writing-instructions
-description: >
-  Write or restructure agent instructions, conventions files, and SKILL.md
-  content using progressive disclosure and the agentskills.io specification.
-  Use when creating PLASTIC.md, rewriting convention docs, authoring new
-  skills, restructuring large instruction files to fit context budgets,
-  or when instructions feel too long, too vague, or agents aren't following
-  them. Also use when the user says "progressive disclosure", "restructure
-  instructions", or "the instructions are too big".
----
-
-# Writing Agent Instructions
-
-Based on the [agentskills.io specification](https://agentskills.io).
-
-## Progressive Disclosure Architecture
-
-All agent instructions follow three loading stages. Design for this — it's the
-architecture, not a nice-to-have.
-
-| Stage | What loads | Budget | Design for |
-|-------|-----------|--------|------------|
-| **Discovery** | name + description | ~100 tokens | Trigger accuracy |
-| **Activation** | Full instruction body | <5000 tokens / <500 lines | Core procedures |
-| **Execution** | references/, scripts/, assets/ | As needed | Deep detail |
-
-**The description carries the entire burden of triggering.** If agents aren't
-activating your skill, the description is the problem.
-
-## Procedure
-
-### Step 1: Audit the content
-
-Before writing or restructuring, classify every piece of content:
-
-| Classification | Where it goes | Example |
-|---------------|---------------|---------|
-| **Trigger context** | description field | "Use when...", keywords |
-| **Core procedure** | SKILL.md body | Step-by-step workflows |
-| **Gotchas** | SKILL.md body (early) | Facts that defy assumptions |
-| **Deep reference** | references/ | API details, full schemas |
-| **Templates** | assets/ or inline | Output format examples |
-| **Executable logic** | scripts/ | Validation, data processing |
-
-Ask for each piece: "Would the agent get this wrong without this?"
-If no — cut it. If unsure — test it.
-
-### Step 2: Write the description
-
-The description must convey WHEN to use, not just WHAT it does.
-
-**Rules:**
-- Imperative phrasing: "Use this skill when..." not "This skill does..."
-- Focus on user intent, not implementation
-- Err on the side of being pushy — list contexts explicitly
-- Include cases where user doesn't name the domain directly
-- Under 1024 characters (hard limit)
-- Include specific trigger keywords
-
-**Template:**
-```yaml
-description: >
-  [One sentence: what it does]. Use when [primary trigger context],
-  [secondary trigger], or when [indirect trigger where user doesn't
-  name the domain]. Also use when [edge case trigger].
-```
-
-### Step 3: Write the body
-
-**Principles (in priority order):**
-
-1. **Procedures over declarations** — Teach HOW to approach a class of problems,
-   not WHAT to produce for a specific instance
-2. **Defaults, not menus** — Pick one approach, mention alternatives briefly.
-   "Use X. For Y cases, use Z instead." Never present options as equals.
-3. **Calibrate control to fragility** — Prescriptive for fragile/sequential tasks,
-   flexible when multiple approaches are valid. Most skills have a mix.
-4. **Reasoning over rigid directives** — "Do X because Y tends to cause Z" beats
-   "ALWAYS do X, NEVER do Y"
-5. **Add what the agent lacks, omit what it knows** — No explaining HTTP, PDFs,
-   or what a migration is. Jump to what's non-obvious.
-
-**Structure:**
-```markdown
-# Title
-
-[1-2 sentence purpose statement]
-
-## Gotchas
-- [Highest-value content first — facts that defy assumptions]
-- [Each gotcha is a concrete correction, not general advice]
-
-## Procedure
-### Step 1: ...
-### Step 2: ...
-
-## Patterns
-[Only if the skill covers multiple approaches to similar problems]
-```
-
-### Step 4: Extract to references/
-
-Anything over 500 lines or 5000 tokens goes to `references/`. But tell the
-agent WHEN to load each file — conditional references, not a generic "see
-references/ for details."
-
-**Good:** "Read `references/api-errors.md` if the API returns a non-200 status"
-**Bad:** "See references/ for more information"
-
-### Step 5: Validate
-
-Run through this checklist:
-
-- [ ] Description under 1024 chars
-- [ ] Body under 500 lines / 5000 tokens
-- [ ] Every instruction passes "would the agent get this wrong without it?"
-- [ ] Gotchas are concrete corrections, not general advice
-- [ ] Defaults chosen, not menus presented
-- [ ] Control calibrated: prescriptive where fragile, flexible where tolerant
-- [ ] References have conditional load triggers
-- [ ] No explaining what the agent already knows
-
-For structured evaluation beyond this checklist (paired evals, pass rate
-tracking, regression testing), use `plastic-evaluating-skills`.
-
-## Gotchas
-
-- Hook `additionalContext` truncates at **10,000 characters**. If instructions
-  must load via hooks (not skills), they must fit this budget.
-- `~/.claude/rules/*.md` files load fully with no truncation — use for
-  always-loaded conventions that don't fit in a skill.
-- CLAUDE.md supports `@path/to/file` imports (max depth 4) — another way
-  to load large instruction sets without truncation.
-- Agents only consult skills for tasks beyond what they can handle alone.
-  Simple one-step requests may not trigger even with a perfect description.
-- Content from real domain expertise (runbooks, incident reports, code review)
-  dramatically outperforms LLM-generated instructions without project context.
-- The most common cause of agents not following instructions: the instruction
-  was too vague, didn't apply to the current task, or presented too many
-  options without a clear default. Read execution traces to diagnose.
-
-## For Convention Files (PLASTIC.md, CLAUDE.md)
-
-Convention files aren't skills — they load differently. Apply progressive
-disclosure by splitting:
-
-| Layer | Mechanism | Budget | Content |
-|-------|-----------|--------|---------|
-| **Always-on** | `~/.claude/rules/` or hook | <10K chars | Core identity, gotchas, critical procedures |
-| **On-demand** | Skills (SKILL.md) | <5K tokens each | Specific workflows activated by task |
-| **Deep reference** | `references/` in skills | Unlimited | Full specs, schemas, examples |
-
-**The always-on layer should answer: "What does this agent need to know about
-every single task?"** Everything else activates on demand.
-
-## References
-
-- Read `references/agentskills-spec.md` for the complete agentskills.io specification including frontmatter fields, description optimization methodology, evaluation framework, and script design requirements