keeponfirst/keeponfirst-agentic-workflow-starter

---

Why this exists

Most AI coding sessions are synchronous: you prompt, you wait, you review, you repeat. This workflow splits feature development across specialized agents so work continues asynchronously:

• 🌙 Async collaboration — cloud coding agents (Jules) keep working while you sleep; a watcher script wakes your orchestrator for review when they finish
• 🧯 No single-point quota failures — planning, asset generation, design, and coding run on different tools with independent quotas
• 🧾 Full traceability — every prompt, plan, and task is a versioned file in your repo; nothing lives only in a chat window
• ✅ Human gates — structured approval checkpoints (scope, wireframe, design DNA) so agents never run past your intent

Works with your stack. The pipeline is tool-agnostic: the default lineup is Google-first (Antigravity + Nano Banana + Stitch + Jules CLI), but each lane is swappable — the skill installs into Antigravity, Cursor, Claude Code, or Codex, and Pencil / Codex CLI slot in as design/code alternatives.

🚀 Quick Start

Install the workflow as a global skill (auto-detects your IDE):

curl -fsSL https://raw.githubusercontent.com/keeponfirst/keeponfirst-agentic-workflow-starter/main/scripts/install.sh | bash

Then trigger it in any project:

/kof                           # shorthand trigger
KOF workflow add dark mode     # natural language
用 KOF 開發新功能               # Chinese works too

Optional — for cloud code execution, install the Jules CLI:

npm install -g @google/jules && jules login

Prefer a full project scaffold instead? See Use as a project starter.

🔄 How It Works

flowchart LR
    subgraph Orchestrator
        A[0 INSIGHTS] --> B[1 PLAN] --> C[1.5 WIREFRAME GATE]
    end
    C --> D[2 ASSETSNano Banana]
    C --> E[2.5 DESIGNStitch]
    D --> F[3 CODEJules CLI]
    E --> F
    F --> G[4 REVIEW] --> H[5 RELEASE]

Each phase ends with a Human Gate — a structured checklist you approve before agents proceed. Logic-only tasks skip the visual phases (0, 1.5, 2.5).

Key design contracts along the way:

• design_dna.json — color palette (exact HEX + forbidden colors), typography, radii; every screen prompt inherits it
• Visual Audit — generated designs are checked against the DNA (nav consistency, color accuracy, component integrity) and auto-refined until they pass
• Task files — code work is written to jules/tasks/*.md first, so you review the brief before any agent runs

🧩 Install as a Skill (Multi-IDE)

The installer above handles this automatically. To install manually, copy skills/keeponfirst-agentic-workflow/ into your IDE’s skills directory:

Trigger keywords: /kof, KOF workflow, KOF agentic, keeponfirst workflow — deliberately specific to avoid clashing with other agentic skills. Edit the description field in SKILL.md to change them.

The skill package contains:

📦 Use as a project starter

Clone (or use as a template) to get the full scaffold — prompt libraries, task queues, and automation scripts:

git clone https://github.com/keeponfirst/keeponfirst-agentic-workflow-starter.git
cd keeponfirst-agentic-workflow-starter
./scripts/bootstrap.sh

scripts/agent.sh is the orchestrator’s adapter — it prepares task files; it never calls external APIs, so every command is a safe dry-run that consumes zero quota:

./scripts/agent.sh plan          # generate PLAN.md template
./scripts/agent.sh assets        # queue asset prompts → nanobanana/queue/
./scripts/agent.sh design        # queue design tasks  → stitch/queue/
./scripts/agent.sh jules         # queue code tasks    → jules/tasks/
./scripts/agent.sh watch     # monitor a Jules session, auto-review on completion
./scripts/agent.sh verify        # validate structure & scan for secrets

Actual execution happens in the agents themselves (Stitch web/MCP, jules remote new, Gemini web) — you review the prepared task files first, then run them.

In day-to-day use you don’t touch the scripts at all — you just talk to your orchestrator:

/kof I want a Tag Selector feature — plan it and create the Jules task
...
I've submitted the Jules task, session ID is 123456, please monitor it

The watcher polls the session, applies the result with jules remote pull --apply on completion, and notifies you for review.

📁 Directory Structure

.
├── skills/keeponfirst-agentic-workflow/   # The installable skill (SKILL.md + scripts + templates)
├── prompts/                # Prompt libraries per agent (antigravity / gemini-cli / jules)
├── scripts/                # agent.sh, install.sh, bootstrap.sh, watcher.sh, check_secrets.sh
├── plans/                  # PLAN outputs
├── nanobanana/queue/       # Asset prompt queue
├── stitch/                 # Design task queue & outputs
├── jules/tasks/            # Code task queue
├── assets/generated/       # Generated assets
├── examples/               # Worked examples (BabyLog app, feature specs)
└── docs/                   # Architecture, integrations, troubleshooting

📚 Documentation

MCP integrations: kof-stitch-mcp · kof-nanobanana-mcp · example config in .mcp.json.example

⚠️ Known Limitations

• Nano Banana free tier — Gemini image models have strict free-tier quotas (Pro models are paid-only since April 2026). The workflow’s default is a browser-generation hybrid flow: the orchestrator prepares prompt files, drives Gemini web via browser automation, and falls back to manual generation (resume with /kof resume or assets ready). See QUOTA_STRATEGY.md.
• agy chat can’t auto-execute prompts — after a Jules session completes, the watcher opens Antigravity but you must manually ask it to review. Tracked as a hoped-for upstream improvement.

🤝 Contributing

Contributions to prompts, examples, and IDE adapters are very welcome — see CONTRIBUTING.md. Good first contributions: a new worked example, a prompt template for your stack, or an adapter guide for another IDE.

☕ Support

If this project saves you time, you can support development here:

📄 License

MIT