@bastani/atomic 0.6.8-0 → 0.7.0-1

package/.agents/skills/gh-commit/SKILL.md

@@ -1,245 +0,0 @@
----
-name: gh-commit
-description: Create well-formatted commits with conventional commit format.
-metadata:
-  provider: atomic
----
-
-# Smart Git Commit
-
-Create well-formatted commit: $ARGUMENTS
-
-## Current Repository State
-
-- Git status: !`git status --porcelain`
-- Current branch: !`git branch --show-current`
-- Staged changes: !`git diff --cached --stat`
-- Unstaged changes: !`git diff --stat`
-- Recent commits: !`git log --oneline -5`
-
-## What This Command Does
-
-1. Checks which files are staged with `git status`
-2. If 0 files are staged, automatically adds all modified and new files with `git add`
-3. Performs a `git diff` to understand what changes are being committed
-4. Analyzes the diff to determine if multiple distinct logical changes are present
-5. If multiple distinct changes are detected, suggests breaking the commit into multiple smaller commits
-6. For each commit (or the single commit if not split), creates a commit message using conventional commit format
-
-## Best Practices for Commits
-
-- Follow the Conventional Commits specification as described below.
-
-# Conventional Commits 1.0.0
-
-## Summary
-
-The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with [SemVer](http://semver.org), by describing the features, fixes, and breaking changes made in commit messages.
-
-The commit message should be structured as follows:
-
-```
-<type>[optional scope]: <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-The commit contains the following structural elements, to communicate intent to the consumers of your library:
-
-1.  **fix:** a commit of the _type_ `fix` patches a bug in your codebase (this correlates with [`PATCH`](http://semver.org/#summary) in Semantic Versioning).
-2.  **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (this correlates with [`MINOR`](http://semver.org/#summary) in Semantic Versioning).
-3.  **BREAKING CHANGE:** a commit that has a footer `BREAKING CHANGE:`, or appends a `'!'` after the type/scope, introduces a breaking API change (correlating with [`MAJOR`](http://semver.org/#summary) in Semantic Versioning). A BREAKING CHANGE can be part of commits of any _type_.
-4.  _types_ other than `fix:` and `feat:` are allowed, for example [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional) (based on the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)) recommends `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others.
-5.  _footers_ other than `BREAKING CHANGE: <description>` may be provided and follow a convention similar to [git trailer format](https://git-scm.com/docs/git-interpret-trailers).
-
-Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE). A scope may be provided to a commit's type, to provide additional contextual information and is contained within parenthesis, e.g., `feat(parser): add ability to parse arrays`.
-
-## Examples
-
-### Commit message with description and breaking change footer
-
-```
-feat: allow provided config object to extend other configs
-
-BREAKING CHANGE: `extends` key in config file is now used for extending other config files
-```
-
-### Commit message with `'!'` to draw attention to breaking change
-
-```
-feat'!': send an email to the customer when a product is shipped
-```
-
-### Commit message with scope and `'!'` to draw attention to breaking change
-
-```
-feat(api)'!': send an email to the customer when a product is shipped
-```
-
-### Commit message with both `'!'` and BREAKING CHANGE footer
-
-```
-chore'!': drop support for Node 6
-
-BREAKING CHANGE: use JavaScript features not available in Node 6.
-```
-
-### Commit message with no body
-
-```
-docs: correct spelling of CHANGELOG
-```
-
-### Commit message with scope
-
-```
-feat(lang): add Polish language
-```
-
-### Commit message with multi-paragraph body and multiple footers
-
-```
-fix: prevent racing of requests
-
-Introduce a request id and a reference to latest request. Dismiss
-incoming responses other than from latest request.
-
-Remove timeouts which were used to mitigate the racing issue but are
-obsolete now.
-
-Reviewed-by: Z
-Refs: #123
-```
-
-## Specification
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
-
-1.  Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`, etc., followed by the OPTIONAL scope, OPTIONAL `'!'`, and REQUIRED terminal colon and space.
-2.  The type `feat` MUST be used when a commit adds a new feature to your application or library.
-3.  The type `fix` MUST be used when a commit represents a bug fix for your application.
-4.  A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., `fix(parser):`
-5.  A description MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., _fix: array parsing issue when multiple spaces were contained in string_.
-6.  A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
-7.  A commit body is free-form and MAY consist of any number of newline separated paragraphs.
-8.  One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a `:<space>` or `<space>#` separator, followed by a string value (this is inspired by the [git trailer convention](https://git-scm.com/docs/git-interpret-trailers)).
-9.  A footer's token MUST use `-` in place of whitespace characters, e.g., `Acked-by` (this helps differentiate the footer section from a multi-paragraph body). An exception is made for `BREAKING CHANGE`, which MAY also be used as a token.
-10. A footer's value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed.
-11. Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer.
-12. If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g., _BREAKING CHANGE: environment variables now take precedence over config files_.
-13. If included in the type/scope prefix, breaking changes MUST be indicated by a `'!'` immediately before the `:`. If `'!'` is used, `BREAKING CHANGE:` MAY be omitted from the footer section, and the commit description SHALL be used to describe the breaking change.
-14. Types other than `feat` and `fix` MAY be used in your commit messages, e.g., _docs: update ref docs._
-15. The units of information that make up Conventional Commits MUST NOT be treated as case sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase.
-16. BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer.
-
-## Why Use Conventional Commits
-
-- Automatically generating CHANGELOGs.
-- Automatically determining a semantic version bump (based on the types of commits landed).
-- Communicating the nature of changes to teammates, the public, and other stakeholders.
-- Triggering build and publish processes.
-- Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
-
-## FAQ
-
-### How should I deal with commit messages in the initial development phase?
-
-We recommend that you proceed as if you've already released the product. Typically _somebody_, even if it's your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc.
-
-### Are the types in the commit title uppercase or lowercase?
-
-Any casing may be used, but it's best to be consistent.
-
-### What do I do if the commit conforms to more than one of the commit types?
-
-Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs.
-
-### Doesn't this discourage rapid development and fast iteration?
-
-It discourages moving fast in a disorganized way. It helps you be able to move fast long term across multiple projects with varied contributors.
-
-### Might Conventional Commits lead developers to limit the type of commits they make because they'll be thinking in the types provided?
-
-Conventional Commits encourages us to make more of certain types of commits such as fixes. Other than that, the flexibility of Conventional Commits allows your team to come up with their own types and change those types over time.
-
-### How does this relate to SemVer?
-
-`fix` type commits should be translated to `PATCH` releases. `feat` type commits should be translated to `MINOR` releases. Commits with `BREAKING CHANGE` in the commits, regardless of type, should be translated to `MAJOR` releases.
-
-### How should I version my extensions to the Conventional Commits Specification, e.g. `@jameswomack/conventional-commit-spec`?
-
-We recommend using SemVer to release your own extensions to this specification (and encourage you to make these extensions'!')
-
-### What do I do if I accidentally use the wrong commit type?
-
-#### When you used a type that's of the spec but not the correct type, e.g. `fix` instead of `feat`
-
-Prior to merging or releasing the mistake, we recommend using `git rebase -i` to edit the commit history. After release, the cleanup will be different according to what tools and processes you use.
-
-#### When you used a type _not_ of the spec, e.g. `feet` instead of `feat`
-
-In a worst case scenario, it's not the end of the world if a commit lands that does not meet the Conventional Commits specification. It simply means that commit will be missed by tools that are based on the spec.
-
-### Do all my contributors need to use the Conventional Commits specification?
-
-No'!' If you use a squash based workflow on Git lead maintainers can clean up the commit messages as they're merged—adding no workload to casual committers. A common workflow for this is to have your git system automatically squash commits from a pull request and present a form for the lead maintainer to enter the proper git commit message for the merge.
-
-### How does Conventional Commits handle revert commits?
-
-Reverting code can be complicated: are you reverting multiple commits? if you revert a feature, should the next release instead be a patch?
-
-Conventional Commits does not make an explicit effort to define revert behavior. Instead we leave it to tooling authors to use the flexibility of _types_ and _footers_ to develop their logic for handling reverts.
-
-One recommendation is to use the `revert` type, and a footer that references the commit SHAs that are being reverted:
-
-```
-revert: let us never again speak of the noodle incident
-
-Refs: 676104e, a215868
-```
-
-### Attributing AI-Assisted Code Authorship
-
-When using AI tools to generate code, it can be beneficial to maintain transparency about authorship for accountability, code review, and auditing purposes. This can be done easily by using Git trailers that append structured metadata to the end of commit messages.
-
-This can be done by appending one or more custom trailers in the commit message, such as:
-
-```
-Assistant-model: Claude Code
-```
-
-Because most Git tooling expects `Co-authored-by` trailers to be formatted as email addresses, you should use a different trailer key to avoid confusion and to distinguish authorship from assistance.
-
-Trailers can be added manually at the end of a commit message, or by using the `git commit` command with the `--trailer` option:
-
-```
-git commit --message "Implement feature" --trailer "Assistant-model: Claude Code"
-```
-
-Trailers can be displayed using the [pretty formats](https://git-scm.com/docs/pretty-formats#Documentation/pretty-formats.txt-trailersoptions) option to `git log` command. For example, for a formatted history showing the hash, author name, and assistant models used for each commit:
-
-```
-git log --color --pretty=format:"%C(yellow)%h%C(reset) %C(blue)%an%C(reset) [%C(magenta)%(trailers:key=Assistant-model,valueonly=true,separator=%x2C)%C(reset)] %s%C(bold cyan)%d%C(reset)"
-```
-
-```
-2100e6c Author [Claude Code] Test commit 4 (HEAD -> work-item-8)
-7120221 Author [Claude Code] Test commit 3
-ea03d91 Author [] Test commit 2
-f93fd8e Author [Claude Code] Test commit 1
-dde0159 Claude Code [] Test work item (#7) (origin/main, origin/HEAD)
-```
-
-## Important Notes
-
-- By default, pre-commit checks (defined in `.pre-commit-config.yaml`) will run to ensure code quality
-    - IMPORTANT: DO NOT SKIP pre-commit checks
-- ALWAYS attribute AI-Assisted Code Authorship
-- If specific files are already staged, the command will only commit those files
-- If no files are staged, it will automatically stage all modified and new files
-- The commit message will be constructed based on the changes detected
-- Before committing, the command will review the diff to identify if multiple commits would be more appropriate
-- If suggesting multiple commits, it will help you stage and commit the changes separately
-- Always reviews the commit diff to ensure the message matches the changes

package/.agents/skills/gh-create-pr/SKILL.md

@@ -1,95 +0,0 @@
----
-name: gh-create-pr
-description: Commit unstaged changes, push changes, submit a pull request.
-metadata:
-  provider: atomic
----
-
-# Create Pull Request
-
-Commit changes, push to remote, and create a pull request with a conventional commit-style title and comprehensive description: $ARGUMENTS
-
-## Current Repository State
-
-- Git status: !`git status --porcelain`
-- Current branch: !`git branch --show-current`
-- Default branch: !`git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|origin/||' || echo main`
-- Staged changes: !`git diff --cached --stat`
-- Unstaged changes: !`git diff --stat`
-- Recent commits on this branch: !`git log --oneline -10`
-- Existing PR for branch: !`gh pr view --json number,title,body 2>/dev/null || echo "No existing PR"`
-
-## What This Command Does
-
-1. **Stage and commit changes** using conventional commit format (follow the gh-commit skill conventions)
-    - If there are unstaged changes, stage and commit them with appropriate conventional commit messages
-    - If multiple distinct logical changes exist, create separate commits for each
-    - ALWAYS attribute AI-assisted code authorship in commits
-2. **Push the branch** to the remote repository
-    - If the current branch is the default branch (main/master), create a new feature branch first
-    - Use `git push -u origin <branch>` to set upstream tracking
-3. **Analyze all changes** in the branch relative to the base branch
-    - Run `git diff origin/<default-branch>...HEAD` to review the full scope of changes
-    - Read relevant modified files to understand the context and impact of changes
-4. **Generate a PR title** following Conventional Commits format:
-    - Format: `<type>[optional scope]: <description>`
-    - Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
-    - Use `!` after type/scope for breaking changes: `feat(api)!: change response format`
-    - Keep the title concise (under 72 characters)
-    - For multi-commit PRs, synthesize a higher-level title that captures the overall theme
-5. **Generate a PR description** with the structure defined in the PR Description Template below
-6. **Create or update the pull request**
-    - If no PR exists for this branch: `gh pr create --title "TITLE" --body "DESCRIPTION"`
-    - If a PR already exists: `gh pr edit <number> --title "TITLE" --body "DESCRIPTION"`
-
-## PR Title Examples
-
-```
-feat(auth): add JWT token refresh endpoint
-fix(ui): resolve layout shift on mobile navigation
-docs: update API reference for v2 endpoints
-refactor(db): migrate from raw SQL to query builder
-feat(api)!: change pagination response format
-chore(deps): bump TypeScript to 5.x
-```
-
-## PR Description Template
-
-Use this structure for the PR body. Omit sections that are not applicable.
-
-```markdown
-## Summary
-
-[1-2 sentence overview of what this PR does and why]
-
-## Changes
-
-- [Key change 1]
-- [Key change 2]
-- [Key change 3]
-
-## Breaking Changes
-
-[Describe what breaks and required migration steps]
-
-## Notes
-
-[Additional context, testing instructions, or deployment considerations]
-```
-
-## Guidelines
-
-- **Respect existing content**: If the PR title already follows conventional commit format, keep it unless it's inaccurate. If a PR already has a meaningful description, enhance it rather than replace it entirely.
-- **Issue references**: If the branch name contains an issue number (e.g., `feat/123-add-auth`), reference it in the description with `Closes #123` or `Refs #123`.
-- **Holistic analysis**: The PR title should capture the overall intent of the changes, not just list individual commits.
-- **Single-commit PRs**: The PR title can mirror the commit message.
-- **Multi-commit PRs**: Synthesize a higher-level title that captures the full scope.
-- Use markdown formatting in the description for readability.
-
-## Important Notes
-
-- By default, pre-commit checks (defined in `.pre-commit-config.yaml`) will run to ensure code quality
-    - IMPORTANT: DO NOT SKIP pre-commit checks
-- ALWAYS attribute AI-Assisted Code Authorship in commit messages
-- Always review the diff before generating the title and description to ensure accuracy
-- If `gh` CLI is not authenticated, prompt the user to run `gh auth login` first

package/.agents/skills/hosted-agents/SKILL.md

@@ -1,262 +0,0 @@
----
-name: hosted-agents
-description: This skill should be used when the user asks to "build background agent", "create hosted coding agent", "set up sandboxed execution", "implement multiplayer agent", or mentions background agents, sandboxed VMs, agent infrastructure, Modal sandboxes, self-spawning agents, or remote coding environments. Part of the context engineering skill suite — also activates when the user mentions "context engineering" or "context-engineering" in the context of agent deployment and execution infrastructure.
-metadata:
-  provider: atomic
----
-
-# Hosted Agent Infrastructure
-
-Hosted agents run in remote sandboxed environments rather than on local machines. When designed well, they provide unlimited concurrency, consistent execution environments, and multiplayer collaboration. The critical insight is that session speed should be limited only by model provider time-to-first-token, with all infrastructure setup completed before the user starts their session.
-
-## When to Activate
-
-Activate this skill when:
-- Building background coding agents that run independently of user devices
-- Designing sandboxed execution environments for agent workloads
-- Implementing multiplayer agent sessions with shared state
-- Creating multi-client agent interfaces (Slack, Web, Chrome extensions)
-- Scaling agent infrastructure beyond local machine constraints
-- Building systems where agents spawn sub-agents for parallel work
-
-## Core Concepts
-
-Move agent execution to remote sandboxed environments to eliminate the fundamental limits of local execution: resource contention, environment inconsistency, and single-user constraints. Remote sandboxes unlock unlimited concurrency, reproducible environments, and collaborative workflows because each session gets its own isolated compute with a known-good environment image.
-
-Design the architecture in three layers because each layer scales independently. Build sandbox infrastructure for isolated execution, an API layer for state management and client coordination, and client interfaces for user interaction across platforms. Keep these layers cleanly separated so sandbox changes do not ripple into clients.
-
-## Detailed Topics
-
-### Sandbox Infrastructure
-
-**The Core Challenge**
-Eliminate sandbox spin-up latency because users perceive anything over a few seconds as broken. Development environments require cloning repositories, installing dependencies, and running build steps -- do all of this before the user ever submits a prompt.
-
-**Image Registry Pattern**
-Pre-build environment images on a regular cadence (every 30 minutes works well) because this makes synchronization with the latest code a fast delta rather than a full clone. Include in each image:
-- Cloned repository at a known commit
-- All runtime dependencies installed
-- Initial setup and build commands completed
-- Cached files from running app and test suite once
-
-When starting a session, spin up a sandbox from the most recent image. The repository is at most 30 minutes out of date, making the remaining git sync fast.
-
-**Snapshot and Restore**
-Take filesystem snapshots at key points to enable instant restoration for follow-up prompts without re-running setup:
-- After initial image build (base snapshot)
-- When agent finishes making changes (session snapshot)
-- Before sandbox exit for potential follow-up
-
-**Git Configuration for Background Agents**
-Configure git identity explicitly in every sandbox because background agents are not tied to a specific user during image builds:
-- Generate GitHub app installation tokens for repository access during clone
-- Set git config `user.name` and `user.email` when committing and pushing changes
-- Use the prompting user's identity for commits, not the app identity
-
-**Warm Pool Strategy**
-Maintain a pool of pre-warmed sandboxes for high-volume repositories because cold starts are the primary source of user frustration:
-- Keep sandboxes ready before users start sessions
-- Expire and recreate pool entries as new image builds complete
-- Start warming a sandbox as soon as a user begins typing (predictive warm-up)
-
-### Agent Framework Selection
-
-**Server-First Architecture**
-Structure the agent framework as a server first, with TUI and desktop apps as thin clients, because this prevents duplicating agent logic across surfaces:
-- Multiple custom clients share one agent backend
-- Consistent behavior across all interaction surfaces
-- Plugin systems extend functionality without client changes
-- Event-driven architectures deliver real-time updates to any connected client
-
-**Code as Source of Truth**
-Select frameworks where the agent can read its own source code to understand behavior. Prioritize this because having code as source of truth prevents the agent from hallucinating about its own capabilities -- an underrated failure mode in AI development.
-
-**Plugin System Requirements**
-Require a plugin system that supports runtime interception because this enables safety controls and observability without modifying core agent logic:
-- Listen to tool execution events (e.g., `tool.execute.before`)
-- Block or modify tool calls conditionally
-- Inject context or state at runtime
-
-### Speed Optimizations
-
-**Predictive Warm-Up**
-Start warming the sandbox as soon as a user begins typing their prompt, not when they submit it, because the typing interval (5-30 seconds) is enough to complete most setup:
-- Clone latest changes in parallel with user typing
-- Run initial setup before user hits enter
-- For fast spin-up, sandbox can be ready before user finishes typing
-
-**Parallel File Reading**
-Allow the agent to start reading files immediately even if sync from latest base branch is not complete, because in large repositories incoming prompts rarely touch recently-changed files:
-- Agent can research immediately without waiting for git sync
-- Block file edits (not reads) until synchronization completes
-- This separation is safe because read-time data staleness of 30 minutes rarely matters for research
-
-**Maximize Build-Time Work**
-Move everything possible to the image build step because build-time duration is invisible to users:
-- Full dependency installation
-- Database schema setup
-- Initial app and test suite runs (populates caches)
-
-### Self-Spawning Agents
-
-**Agent-Spawned Sessions**
-Build tools that allow agents to spawn new sessions because frontier models are capable of decomposing work and coordinating sub-tasks:
-- Research tasks across different repositories
-- Parallel subtask execution for large changes
-- Multiple smaller PRs from one major task
-
-Expose three primitives: start a new session with specified parameters, read status of any session (check-in capability), and continue main work while sub-sessions run in parallel.
-
-**Prompt Engineering for Self-Spawning**
-Engineer prompts that guide when agents should spawn sub-sessions rather than doing work inline:
-- Research tasks that require cross-repository exploration
-- Breaking monolithic changes into smaller PRs
-- Parallel exploration of different approaches
-
-### API Layer
-
-**Per-Session State Isolation**
-Isolate state per session (SQLite per session works well) because cross-session interference is a subtle and hard-to-debug failure mode:
-- Dedicated database per session
-- No session can impact another's performance
-- Architecture handles hundreds of concurrent sessions
-
-**Real-Time Streaming**
-Stream all agent work in real-time because high-frequency feedback is critical for user trust:
-- Token streaming from model providers
-- Tool execution status updates
-- File change notifications
-
-Use WebSocket connections with hibernation APIs to reduce compute costs during idle periods while maintaining open connections.
-
-**Synchronization Across Clients**
-Build a single state system that synchronizes across all clients (chat interfaces, Slack bots, Chrome extensions, web interfaces, VS Code instances) because users switch surfaces frequently and expect continuity. All changes sync to the session state, enabling seamless client switching.
-
-### Multiplayer Support
-
-**Why Multiplayer Matters**
-Design for multiplayer from day one because it is nearly free to add with proper synchronization architecture, and it unlocks high-value workflows:
-- Teaching non-engineers to use AI effectively
-- Live QA sessions with multiple team members
-- Real-time PR review with immediate changes
-- Collaborative debugging sessions
-
-**Implementation Requirements**
-Build the data model so sessions are not tied to single authors because multiplayer fails silently if authorship is hardcoded:
-- Pass authorship info to each prompt
-- Attribute code changes to the prompting user
-- Share session links for instant collaboration
-
-### Authentication and Authorization
-
-**User-Based Commits**
-Use GitHub authentication to open PRs on behalf of the user (not the app) because this preserves the audit trail and prevents users from approving their own AI-generated changes:
-- Obtain user tokens for PR creation
-- PRs appear as authored by the human, not the bot
-
-**Sandbox-to-API Flow**
-Follow this sequence because it keeps sandbox permissions minimal while letting the API handle sensitive operations:
-1. Sandbox pushes changes (updating git user config)
-2. Sandbox sends event to API with branch name and session ID
-3. API uses user's GitHub token to create PR
-4. GitHub webhooks notify API of PR events
-
-### Client Implementations
-
-**Slack Integration**
-Prioritize Slack as the first distribution channel for internal adoption because it creates a virality loop as team members see others using it:
-- No syntax required, natural chat interface
-- Build a classifier (fast model with repo descriptions) to determine which repository to work in
-- Include hints for common repositories; allow "unknown" for ambiguous cases
-
-**Web Interface**
-Build a web interface with these features because it serves as the primary power-user surface:
-- Real-time streaming of agent work on desktop and mobile
-- Hosted VS Code instance running inside sandbox
-- Streamed desktop view for visual verification
-- Before/after screenshots for PRs
-- Statistics page: sessions resulting in merged PRs (primary metric), usage over time, live "humans prompting" count
-
-**Chrome Extension**
-Build a Chrome extension for non-engineering users because DOM and React internals extraction gives higher precision than raw screenshots at lower token cost:
-- Sidebar chat interface with screenshot tool
-- Extract DOM/React internals instead of raw images
-- Distribute via managed device policy (bypasses Chrome Web Store)
-
-## Practical Guidance
-
-### Follow-Up Message Handling
-
-Choose between queueing and inserting follow-up messages sent during execution. Prefer queueing because it is simpler to manage and lets users send thoughts on next steps while the agent works. Build a mechanism to stop the agent mid-execution when needed, because without it users feel trapped.
-
-### Metrics That Matter
-
-Track these metrics because they indicate real value rather than vanity usage:
-- Sessions resulting in merged PRs (primary success metric)
-- Time from session start to first model response
-- PR approval rate and revision count
-- Agent-written code percentage across repositories
-
-### Adoption Strategy
-
-Drive internal adoption through visibility rather than mandates because forced usage breeds resentment:
-- Work in public spaces (Slack channels) for visibility
-- Let the product create virality loops
-- Do not force usage over existing tools
-- Build to people's needs, not hypothetical requirements
-
-## Guidelines
-
-1. Pre-build environment images on regular cadence (30 minutes is a good default)
-2. Start warming sandboxes when users begin typing, not when they submit
-3. Allow file reads before git sync completes; block only writes
-4. Structure agent framework as server-first with clients as thin wrappers
-5. Isolate state per session to prevent cross-session interference
-6. Attribute commits to the user who prompted, not the app
-7. Track merged PRs as primary success metric
-8. Build for multiplayer from the start; it is nearly free with proper sync architecture
-
-## Gotchas
-
-1. **Cold start latency**: First sandbox spin-up takes 30-60s and users perceive this as broken. Use warm pools and predictive warm-up on keystroke to eliminate perceived wait time.
-2. **Image staleness**: Infrequent image rebuilds mean agents run with outdated dependencies or code. Set a 30-minute rebuild cadence and monitor image age; alert if builds fail silently.
-3. **Sandbox cost runaway**: Long-running agents without timeout or budget caps accumulate unexpected costs. Set hard timeout limits (default 4 hours) and per-session cost ceilings.
-4. **Auth token expiration mid-session**: Long tasks fail when GitHub tokens expire partway through. Implement token refresh logic and check token validity before sensitive operations like PR creation.
-5. **Git config in sandboxes**: Missing `user.name` or `user.email` causes commit failures in background agents. Always set git identity explicitly during sandbox configuration, never assume it carries over from the image.
-6. **State loss on sandbox recycle**: Agents lose completed work if the sandbox is recycled or times out before results are extracted. Always snapshot before termination and extract artifacts (branches, PRs, files) before letting the sandbox die.
-7. **Oversubscribing warm pools**: Maintaining too many warm sandboxes wastes money during low-traffic periods. Scale pool size based on traffic patterns and time-of-day; use autoscaling rather than fixed pool sizes.
-8. **Missing output extraction**: Agents complete work inside the sandbox but results never get pulled out to the user. Build explicit extraction steps (push branch, create PR, return file contents) into the session teardown flow.
-
-## Integration
-
-This skill builds on multi-agent-patterns for agent coordination and tool-design for agent-tool interfaces. It connects to:
-
-- multi-agent-patterns - Self-spawning agents follow supervisor patterns
-- tool-design - Building tools for agent spawning and status checking
-- context-optimization - Managing context across distributed sessions
-- filesystem-context - Using filesystem for session state and artifacts
-
-## References
-
-Internal reference:
-- [Infrastructure Patterns](./references/infrastructure-patterns.md) - Read when: implementing sandbox lifecycle, image builds, or warm pool logic for the first time
-
-Related skills in this collection:
-- multi-agent-patterns - Read when: designing self-spawning or supervisor coordination patterns
-- tool-design - Read when: building tools for agent session management or status checking
-- context-optimization - Read when: context windows fill up across distributed agent sessions
-
-External resources:
-- [Ramp](https://builders.ramp.com/post/why-we-built-our-background-agent) - Read when: evaluating whether to build vs. buy background agent infrastructure
-- [Modal Sandboxes](https://modal.com/docs/guide/sandbox) - Read when: choosing a cloud sandbox provider or comparing isolation models
-- [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/) - Read when: designing per-session state management with WebSocket hibernation
-- [OpenCode](https://github.com/sst/opencode) - Read when: selecting a server-first agent framework or studying plugin architectures
-
----
-
-## Skill Metadata
-
-**Created**: 2026-01-12
-**Last Updated**: 2026-03-17
-**Author**: Agent Skills for Context Engineering Contributors
-**Version**: 1.1.0