@provos/ironcurtain 0.9.1 → 0.11.0

package/dist/workflow/workflows/design-and-code/workflow.yaml

@@ -0,0 +1,169 @@
+name: design-and-code
+description: "Plan -> Design -> Implement -> Review workflow with human gates and coder-critic loop"
+initial: plan
+
+settings:
+  mode: docker
+  dockerAgent: claude-code
+  maxRounds: 3
+  systemPrompt: "Workflow artifacts (plan, spec, reviews) go in `.workflow/`. Code goes directly at the workspace root."
+
+states:
+  plan:
+    type: agent
+    description: Breaks down the task into implementation steps
+    persona: global
+    prompt: |
+      You are a project planner.
+
+      Your responsibilities:
+      - Analyze the task requirements
+      - If there is existing code in the workspace, read it to understand the current architecture
+      - Identify components, dependencies, and implementation order
+      - Note key design decisions and trade-offs
+
+      Output: Create a `.workflow/plan/` directory with a `plan.md` file.
+      Write a structured markdown document with numbered steps.
+      Do NOT write any code -- only the plan.
+    inputs: []
+    outputs:
+      - plan
+    transitions:
+      - to: plan_review
+
+  plan_review:
+    type: human_gate
+    description: Human review of the plan
+    acceptedEvents:
+      - APPROVE
+      - FORCE_REVISION
+      - ABORT
+    present:
+      - plan
+    transitions:
+      - to: design
+        event: APPROVE
+      - to: plan
+        event: FORCE_REVISION
+      - to: aborted
+        event: ABORT
+
+  design:
+    type: agent
+    description: Produces technical design specification with interfaces and types
+    persona: global
+    prompt: |
+      You are a software architect. Produce a technical design specification.
+
+      Your responsibilities:
+      - Define module structure, interfaces, and data flow
+      - Specify function signatures with TypeScript types
+      - Document key design decisions and rationale
+      - If there is existing code, design around it
+
+      Output: Create a `.workflow/spec/` directory with a `spec.md` file.
+      Do NOT write implementation code.
+    inputs:
+      - plan
+    outputs:
+      - spec
+    transitions:
+      - to: design_review
+
+  design_review:
+    type: human_gate
+    description: Human review of the design specification
+    acceptedEvents:
+      - APPROVE
+      - FORCE_REVISION
+      - ABORT
+    present:
+      - spec
+    transitions:
+      - to: implement
+        event: APPROVE
+      - to: design
+        event: FORCE_REVISION
+      - to: aborted
+        event: ABORT
+
+  implement:
+    type: agent
+    description: Implements all modules per the design spec
+    freshSession: false
+    persona: global
+    prompt: |
+      You are an implementation engineer.
+
+      Your responsibilities:
+      - Implement all modules described in the spec
+      - Write clean, well-typed TypeScript
+      - Create unit tests
+      - Run the tests to verify they pass
+
+      Write code directly at the workspace root (e.g., `src/`, `package.json`, `tests/`).
+      Do NOT create a separate output directory for code.
+      Run all tests to verify everything works.
+    inputs:
+      - plan
+      - spec
+    outputs: []
+    transitions:
+      - to: review
+
+  review:
+    type: agent
+    description: Reviews code against the spec for correctness and quality
+    persona: global
+    prompt: |
+      You are a code reviewer.
+
+      Your responsibilities:
+      - Verify correctness: does the code at the workspace root match the spec?
+      - Check edge cases and error handling
+      - Evaluate code quality, naming, and structure
+      - Assess test coverage and test quality
+
+      Output: Create a `.workflow/reviews/` directory with a `review.md` file.
+      If issues are found, set verdict to "rejected" with specific, actionable feedback.
+      If the code is solid, set verdict to "approved".
+    inputs:
+      - spec
+    outputs:
+      - reviews
+    transitions:
+      - to: done
+        when:
+          verdict: approved
+      - to: escalate_gate
+        guard: isRoundLimitReached
+      - to: implement
+        when:
+          verdict: rejected
+
+  escalate_gate:
+    type: human_gate
+    description: Human review when coder-critic loop reaches round limit
+    acceptedEvents:
+      - APPROVE
+      - FORCE_REVISION
+      - ABORT
+    present:
+      - reviews
+    transitions:
+      - to: done
+        event: APPROVE
+      - to: implement
+        event: FORCE_REVISION
+      - to: aborted
+        event: ABORT
+
+  done:
+    type: terminal
+    description: Workflow complete
+    outputs:
+      - reviews
+
+  aborted:
+    type: terminal
+    description: Workflow aborted

package/dist/workflow/workflows/test-email-summary/skills/email-formatting/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: email-formatting
+description: Markdown formatting conventions for email summary documents — heading depth, list style, line length, emoji policy, and a mandatory provenance footer. Read this when producing a markdown report that summarizes one or more email messages so the output matches the project's house style.
+---
+
+# Email formatting conventions
+
+Use these conventions whenever you write a markdown file that summarizes
+email content.
+
+## Heading depth
+
+- The document has exactly one `#` heading at the top: the report title.
+- Each individual email gets a `##` heading whose text is the email subject.
+- Do not use `###` or deeper for per-email metadata; use a bullet list instead.
+
+## Per-email metadata
+
+For each email, render metadata as an unordered list immediately under the
+`##` subject heading, in this order:
+
+- `From: <sender>`
+- `To: <recipient(s), comma-separated>`
+- `Date: <as it appears in the source, no reformatting>`
+- `Summary: <1-2 sentences in prose>`
+
+## Line length and whitespace
+
+- Soft-wrap at roughly 80 columns. Don't hard-break inside a sentence.
+- Exactly one blank line between sections; never two or more.
+- No trailing whitespace at end of lines.
+
+## Emoji policy
+
+Do not use emoji in summary documents. They render inconsistently across
+mail clients that may consume the markdown downstream.
+
+## Preamble and outro
+
+There is no preamble (no "Here is the summary..." opener) and no outro
+(no "Let me know if..." closer). The document opens with the `#` title.
+
+## Provenance footer (required)
+
+The document MUST end with the literal HTML comment marker on a line by
+itself, separated from the last email's `Summary:` bullet by exactly one
+blank line:
+
+    <!-- email-summary/v1 -->
+
+This marker is how downstream tooling identifies the generator and
+schema version. Producers that omit it are non-compliant; producers
+that change the spelling, casing, or version segment break parsers
+that depend on the literal string. Do not localize, prettify, or
+expand the marker — it is a machine-readable token, not human prose.

package/dist/workflow/workflows/test-email-summary/skills/gmail-query-syntax/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: gmail-query-syntax
+description: Reference for Gmail's search query syntax — operators like is:sent, newer_than:, from:, has:attachment, label:, and how they compose. Read this when constructing a Gmail search query string for the google_workspace.gmail_search_messages Code Mode call, especially when filtering by sent vs received, recency, sender, or labels.
+---
+
+# Gmail query syntax primer
+
+These tools live on the `google-workspace` MCP server, sanitized to
+`google_workspace` in Code Mode. In Docker Agent Mode the only MCP tool
+exposed to Claude Code is `execute_code`; write TypeScript inside it and
+call the Gmail tools as dotted callables, e.g.
+`google_workspace.gmail_search_messages({ query: "is:sent", pageSize: 3 })`.
+
+`gmail_search_messages` accepts a `query` parameter that uses Gmail's
+standard search operator language — the same syntax the Gmail web UI
+search box accepts. Operators combine with implicit AND; use `OR`
+(uppercase) for disjunction and parentheses for grouping.
+
+Note: `gmail_search_messages` returns message IDs, thread IDs, and URLs
+only — not full message contents. To read sender, recipient, subject,
+date, and body for a matched message, follow up with
+`google_workspace.gmail_get_message` (single id) or
+`google_workspace.gmail_get_messages_batch` (array of ids).
+
+## Common operators
+
+| Operator          | Meaning                                         | Example                   |
+| ----------------- | ----------------------------------------------- | ------------------------- |
+| `is:sent`         | Messages the user sent (not received)           | `is:sent`                 |
+| `is:unread`       | Unread messages                                 | `is:unread`               |
+| `is:starred`      | Starred messages                                | `is:starred`              |
+| `from:<addr>`     | Sender address (substring or full)              | `from:alice@example.com`  |
+| `to:<addr>`       | Recipient address                               | `to:team@example.com`     |
+| `subject:<text>`  | Subject contains text                           | `subject:"weekly update"` |
+| `newer_than:<n>d` | Messages newer than N days (also `h`, `m`, `y`) | `newer_than:7d`           |
+| `older_than:<n>d` | Messages older than N (same units)              | `older_than:30d`          |
+| `after:<date>`    | After a date (YYYY/MM/DD)                       | `after:2025/01/01`        |
+| `before:<date>`   | Before a date                                   | `before:2025/02/01`       |
+| `has:attachment`  | Messages with at least one attachment           | `has:attachment`          |
+| `label:<name>`    | Messages with the given Gmail label             | `label:invoices`          |
+| `in:inbox`        | In the inbox (excludes archived)                | `in:inbox`                |
+| `in:anywhere`     | Includes Spam and Trash (rarely needed)         | `in:anywhere`             |
+
+## Composing queries
+
+- Implicit AND: `is:sent newer_than:7d` -> sent in the last 7 days.
+- Explicit OR with grouping: `(from:alice OR from:bob) is:unread`.
+- Negation with `-`: `is:sent -label:archived`.
+- Quote multi-word values: `subject:"quarterly review"`.
+
+## Tips
+
+- Prefer `newer_than:Nd` over `after:` when "the last N days" is what
+  you actually want — `after:` is calendar-anchored and behaves
+  unexpectedly across timezone boundaries.
+- For "the most recent N sent emails", combine `is:sent` with the
+  `pageSize` argument on the dotted call —
+  `google_workspace.gmail_search_messages({ query: "is:sent", pageSize: N })` —
+  do not try to express the limit inside the query string. (Pagination
+  tokens come back as `pageToken` and are passed back in via the same
+  argument name on the next call if you need to walk past the first page.)
+- The query is case-insensitive for operator names but case-sensitive
+  inside quoted values.

package/dist/workflow/workflows/test-email-summary/skills/json-schema-emails/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: json-schema-emails
+description: Canonical shape of the .workflow/emails/emails.json file passed between the fetch and summarize states — required fields (sender, recipient, subject, date, body), types, and field semantics. Read this whenever you write or read emails.json so producer and consumer agree on the shape.
+---
+
+# emails.json schema
+
+The fetch state writes `.workflow/emails/emails.json` and the summarize
+state reads it. The file is a single JSON array of email objects. The
+canonical JSON Schema is in the sibling file `schema.json`; this document
+explains the fields and their semantics.
+
+## Top-level shape
+
+A JSON array. Each element is an email object. The array order is
+preservation order — the consumer renders emails in the order they
+appear, so the producer should write them in the order it wants them
+rendered (typically newest-first as returned by the API).
+
+## Email object fields
+
+All fields are required and must be strings unless noted.
+
+- `sender` — the From address. Format `Name <addr@example.com>` if the
+  source provides a display name, else the bare address.
+- `recipient` — the To addresses, comma-separated. If the source has
+  multiple To recipients they are joined with `, ` (comma + space). CC
+  and BCC are not represented in this schema.
+- `subject` — the email subject line, verbatim. Empty string is allowed
+  if the source has no subject; do not substitute "(no subject)".
+- `date` — the date as it appears in the source headers (RFC 2822 or
+  whatever the API returns). Do not reformat or normalize the timezone.
+- `body` — the message body as plain text. If the source is HTML, the
+  producer is responsible for stripping tags before writing. Newlines
+  are preserved; tabs are replaced with two spaces.
+
+## Validating
+
+The sibling `schema.json` is a draft-2020-12 JSON Schema. Tooling that
+needs to validate the file structurally should load it from there; this
+document is the human-readable companion.

package/dist/workflow/workflows/test-email-summary/skills/json-schema-emails/schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ironcurtain.local/workflows/test-email-summary/emails.json",
+  "title": "emails.json",
+  "description": "Array of email records exchanged between the fetch and summarize states of the test-email-summary workflow.",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["sender", "recipient", "subject", "date", "body"],
+    "properties": {
+      "sender": {
+        "type": "string",
+        "description": "From address; either a bare email or 'Display Name <addr@example.com>'."
+      },
+      "recipient": {
+        "type": "string",
+        "description": "Comma-separated To addresses. CC/BCC are not represented."
+      },
+      "subject": {
+        "type": "string",
+        "description": "Subject line verbatim. Empty string is allowed."
+      },
+      "date": {
+        "type": "string",
+        "description": "Date as it appears in the source headers. Not normalized."
+      },
+      "body": {
+        "type": "string",
+        "description": "Plain text body. HTML must be stripped by the producer; newlines preserved."
+      }
+    }
+  }
+}

package/dist/workflow/workflows/test-email-summary/skills/summary-style-guide/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: summary-style-guide
+description: Tone and length conventions for email summaries — voice, verb tense, what to include vs omit, and target sentence count. Read this when writing the prose Summary line for each email so the voice is consistent across the report.
+---
+
+# Summary style guide
+
+Each email in the report gets a one- or two-sentence prose summary. This
+document covers the _voice_ of those sentences. For the surrounding
+markdown structure, the heading depth, and where the summary sits in the
+document, see the email-formatting conventions.
+
+## Voice and tense
+
+- Third-person, past tense. "Alice asked the team to review the deck"
+  rather than "I am asking..." or "Alice is asking...".
+- Drop the salutation, the signature, and any thread quoting. The
+  summary is what the email _did_, not how it was framed.
+- Active voice. "Bob declined the meeting" not "the meeting was declined
+  by Bob".
+
+## What to include
+
+The summary should answer: _what is the actionable substance of this
+email?_ Concretely:
+
+- The ask, decision, or status update at the heart of the message.
+- Who is on the hook for what, if explicit.
+- Any deadline or date that anchors the action.
+
+## What to omit
+
+- Niceties ("Thanks!", "Hope you're well", "Cheers").
+- The sender's restatement of what they previously said in the thread.
+- Speculation about why the email was sent.
+- Any attachment list — that's separate metadata, not summary content.
+
+## Length
+
+- Prefer one sentence. Use two when the email genuinely covers two
+  distinct items (e.g., a status update _and_ an unrelated ask).
+- Hard cap: two sentences. If a summary feels like it needs three, the
+  email contains multiple threads of substance and the summary should
+  pick the most actionable one and drop the rest.
+
+## Confidence and hedging
+
+If the email is ambiguous or the body is truncated, write a confident
+summary of what's visible rather than hedging. Do not insert "appears
+to" or "seems to be" — the consumer of the summary already knows it
+was machine-derived.

package/dist/workflow/workflows/test-email-summary/workflow.yaml

@@ -0,0 +1,89 @@
+name: test-email-summary
+description: 'TESTING ONLY — fetch a small set of emails (exec-assistant) then summarize them to a file (global). Used to smoke-test the agent skills feature; not a real workflow. The task description supplies the scope (which emails: sent/received, count, time range, etc.).'
+initial: fetch
+
+settings:
+  mode: docker
+  dockerAgent: claude-code
+  sharedContainer: true
+  model: anthropic:claude-haiku-4-5
+
+states:
+  fetch:
+    type: agent
+    description: Fetches the in-scope emails (per the task description) via the Gmail MCP tools
+    persona: exec-assistant
+    # Test fixture: per-state `skills:` filter is set on `fetch` to exercise
+    # the "filtered subset" branch of the resolver. Of the four bundled
+    # skills under skills/, this state only sees these two. The shared
+    # `json-schema-emails` skill is also visible to `summarize` (overlap),
+    # while `gmail-query-syntax` is unique to this state.
+    skills:
+      - gmail-query-syntax
+      - json-schema-emails
+    prompt: |
+      The task description is the source of truth for which emails are in
+      scope (sent vs received, count, time range, sender/recipient
+      filters, labels, etc.). Read it carefully before constructing the
+      Gmail query.
+
+      Retrieve those emails via the Gmail tools on the `google-workspace`
+      MCP server and write them to `.workflow/emails/emails.json` using
+      your built-in `Write` tool. `/workspace` is bind-mounted into the
+      container, so native file I/O operates on it directly — do NOT
+      route writes through the filesystem MCP.
+
+      Two bundled skills cover the load-bearing details of this state:
+      `gmail-query-syntax` documents the Gmail query operators and the
+      Code Mode call shape; `json-schema-emails` is the canonical schema
+      for the emails.json file. Their `SKILL.md` bodies live at
+      `/home/codespace/skills/.claude/skills/<skill-name>/SKILL.md`. Read
+      both bodies before generating any tool calls or output — the
+      authoritative specifics (call sequence, query syntax, JSON field
+      names and semantics) are in those files, not in this prompt.
+    inputs: []
+    outputs:
+      - emails
+    transitions:
+      - to: summarize
+
+  summarize:
+    type: agent
+    description: Summarizes the fetched emails into a single markdown file
+    persona: global
+    # Test fixture: `skills:` is intentionally OMITTED here to exercise the
+    # "default = all bundled skills" branch of the resolver. This state sees
+    # all four bundled skills (email-formatting, gmail-query-syntax,
+    # json-schema-emails, summary-style-guide) plus any user-global skills.
+    # The asymmetry vs. `fetch` (which has an explicit filter) is the point —
+    # do not "fix" it by adding a skills list to this state.
+    prompt: |
+      Read `.workflow/emails/emails.json` with your built-in `Read` tool
+      and write a markdown summary to `.workflow/summary/email-summary.md`
+      with your built-in `Write` tool. `/workspace` is bind-mounted into
+      the container, so native file I/O operates on it directly.
+
+      The bundled skills carry the authoritative formatting and writing
+      conventions for this output: `email-formatting` covers document
+      structure (headings, metadata layout, footer requirements) and
+      `summary-style-guide` covers the per-email prose summary's voice
+      and length. Their `SKILL.md` bodies live at
+      `/home/codespace/skills/.claude/skills/<skill-name>/SKILL.md`. Read
+      both bodies before writing the output — the prompt deliberately
+      does not restate the structure, voice, or footer requirements; the
+      skills are the source of truth.
+
+      Title the document `# Email summary` and include one section per
+      email in the order they appear in the input.
+    inputs:
+      - emails
+    outputs:
+      - summary
+    transitions:
+      - to: done
+
+  done:
+    type: terminal
+    description: Summary written to .workflow/summary/email-summary.md
+    outputs:
+      - summary