AI-Powered Workflows

Understanding Terreno's autonomous AI workflows for continuous improvement.

Overview

Terreno uses GitHub Actions with AI agents to maintain code quality, documentation, and developer experience. These workflows run automatically and create pull requests when improvements are needed.

Workflow Categories

Documentation Workflows

Update Docs

Trigger: Push to master
Purpose: Keeps documentation synchronized with code changes

Analyzes code diffs after each merge to identify:

• New or changed APIs, functions, classes
• Missing or outdated documentation
• Documentation gaps that need attention

Output: Draft pull requests with documentation updates following the Diátaxis framework (tutorials, how-to guides, reference, explanation).

Philosophy: Treats documentation gaps like failing tests — they must be fixed.

Update Rules

Trigger: Push to master
Purpose: Keeps AI assistant rules synchronized with codebase changes

Maintains the single source of truth in .rulesync/rules/ and ensures:

• .cursorrules (Cursor IDE)
• .windsurfrules (Windsurf IDE)
• AGENTS.md (Claude Code, Copilot)
• .github/copilot-instructions.md (GitHub Copilot)

Workflow:

1. Detects package changes, new APIs, or convention updates
2. Updates source files in .rulesync/rules/
3. Creates PR with instructions to run bun run rules to regenerate outputs
4. Ensures rulesync-check CI passes

Key insight: Rule files are code — they must be kept in sync with implementation.

Code Quality Workflows

Daily JSDoc Improver

Trigger: Daily schedule + push to master
Purpose: Systematically improves JSDoc documentation across the codebase

Two modes:

• Targeted (on push): Improves JSDoc for files changed in recent commits
• Systematic (daily): Three-phase approach covering entire codebase

Output: Draft PRs with improved JSDoc comments on exported functions, methods, and classes.

Daily Test Improver

Trigger: Daily schedule
Purpose: Enhances test coverage and test quality

Analyzes test files and implementation to:

• Add missing test cases
• Improve test clarity and coverage
• Identify edge cases that need testing
• Ensure tests follow best practices

Output: Draft PRs with test improvements.

Maintenance Workflows

Agentic Maintenance

Trigger: Daily at 00:37 UTC
Purpose: Cleans up expired issues, discussions, and pull requests

Automatically closes expired entities based on the expires field in safe-outputs configuration. Schedule is determined by the shortest expiration time across all workflows.

Prevents: Stale issues and PRs from accumulating.

RulesSync Check

Trigger: Pull request
Purpose: Validates that generated rule files are synchronized with sources

Validation steps:

1. Runs bun run rules to regenerate outputs
2. Checks for uncommitted changes
3. Fails if generated files don't match committed versions

Prevents: Merging PRs with out-of-sync rule files.

CI/CD Workflows

Package Testing

Each package has its own CI workflow that runs on pull requests and pushes:

Workflow	Package	Tests
api-ci.yml	@terreno/api	Unit tests, type checking, linting
ui-ci.yml	@terreno/ui	Component tests, type checking, linting
rtk-ci.yml	@terreno/rtk	Unit tests, type checking, linting
mcp-server-ci.yml	@terreno/mcp	Integration tests, type checking, linting
example-backend-ci.yml	example-backend	Integration tests, type checking
example-frontend-ci.yml	example-frontend	Build verification, type checking
ui-demo-ci.yml	demo	Build verification, type checking

Deployment Workflows

Demo Deploy

Trigger: Push to master
Purpose: Deploys UI demo to Google Cloud Storage with Cloud CDN

Architecture: Static site hosting with custom domain, SSL, and CDN acceleration.

Learn more: GCP Hosting Architecture, Deploy to GCP

Frontend Example Deploy

Trigger: Push to master, pull request
Purpose: Deploys example frontend with preview environments

Features:

• Production: Deploys to production GCS bucket on master
• Preview: Creates preview environments for pull requests
• Cleanup: Automatically removes preview environments when PRs close

MCP Server Deploy

Trigger: Push to master
Purpose: Deploys Model Context Protocol server

Builds and deploys the MCP server for AI coding assistant integration.

Preview Cleanup

Trigger: Pull request close
Purpose: Removes preview deployments when PRs are closed or merged

Ensures preview environments don't accumulate and waste resources.

Security & Quality

CodeQL Analysis

Trigger: Push to master, pull request, schedule (weekly)
Purpose: Security vulnerability scanning with GitHub CodeQL

Languages analyzed: JavaScript, TypeScript

Output: Security alerts in the Security tab when vulnerabilities are found.

Dependabot Auto-merge

Trigger: Dependabot pull request opened
Purpose: Automatically merges dependency updates after CI passes

Requirements for auto-merge:

• All CI checks pass
• Dependabot PR (created by Dependabot)
• No conflicts
• 7-day cooldown for security (see Dependency Management)

Learn more: Dependency Management

Publishing

Publish on Tag

Trigger: Tag push matching v*.*.*
Purpose: Publishes packages to npm registry

Workflow:

1. Validates tag format and package versions match
2. Runs full test suite
3. Publishes to npm with appropriate tags (latest or next)
4. Creates GitHub release with changelog

Packages published:

• @terreno/api
• @terreno/ui
• @terreno/rtk
• @terreno/mcp

Workflow Philosophy

Single Source of Truth

• Documentation: Code is truth, docs must reflect it
• Rules: .rulesync/rules/ is truth, generated files derive from it
• Tests: Implementation is truth, tests verify it

Fail Fast

• All checks must pass before merge
• Generated files must be committed (no drift)
• Documentation gaps are treated like failing tests

Autonomous Improvement

• Workflows create PRs, not commits
• PRs are drafts requiring human review
• Workflow agents make suggestions, humans make decisions

Continuous Sync

• Documentation syncs on every master push
• Rules sync on every master push
• Dependencies update daily (Dependabot)
• Quality improvements run daily (JSDoc, tests)

Working with AI Workflows

When a Workflow Creates a PR

1. Review the changes — AI is helpful but not perfect
2. Run suggested commands — E.g., bun run rules for rule updates
3. Test locally — Ensure changes work as intended
4. Approve or close — Merge if valuable, close if not

When a Workflow Fails

Check the workflow run logs in the Actions tab:

• Documentation updates: May need manual clarification
• Rule updates: May need manual fixes to .rulesync/rules/
• JSDoc/test improvements: May need guidance on conventions

Customizing Workflows

Workflow definitions live in .github/workflows/*.md files. These are compiled into .github/workflows/*.lock.yml by the GitHub Agentic Workflows CLI.

To customize:

1. Edit the .md source file (e.g., update-docs.md)
2. Run gh aw compile (if using gh-aw CLI)
3. Commit both the .md and regenerated .lock.yml

Note: Never edit .lock.yml files directly — they are generated.

Best Practices

For Maintainers

• Review workflow PRs regularly — Don't let them accumulate
• Provide feedback — If a workflow generates bad suggestions, close with a comment explaining why
• Tune prompts — If a workflow consistently misses the mark, update the .md file

For Contributors

• Run CI before pushing — bun run lint && bun run test
• Update rules if needed — bun run rules after changing .rulesync/rules/
• Check workflow status — Ensure your PR doesn't break workflows

For Users

• Check Actions tab — See what's running and what's pending
• Review draft PRs — Workflow-generated PRs may contain useful improvements
• Report issues — If a workflow behaves unexpectedly, open an issue

Troubleshooting

Workflow doesn't run when expected

• Check .github/workflows/*.yml trigger configuration
• Verify branch name matches (usually master)
• Check workflow permissions and safe-outputs limits

RulesSync check fails on PR

• Run bun run rules locally
• Commit any generated file changes
• Ensure .rulesync/rules/ files have valid YAML frontmatter

Dependabot PR doesn't auto-merge

• Verify all CI checks pass (green checkmarks)
• Check 7-day cooldown hasn't been violated
• Ensure no merge conflicts exist

AI workflow creates poor quality PR

• Review the workflow definition in .github/workflows/*.md
• Consider customizing the prompt or instructions
• Close the PR with feedback for future improvements

Related Documentation

• Dependency Management — Dependabot configuration and auto-merge
• Deploy to GCP — Manual deployment guide
• GCP Hosting Architecture — Static site hosting design
• Environment Variables — Configuration reference