Artifacts & Knowledge System

What Are Artifacts?

Artifacts are structured documents the agent creates during its work. They serve as communication, documentation, and proof of work.

Each conversation has its own artifact directory where these files live.

The Artifact Types

1. Task List (task.md)

A living checklist that tracks progress:

# Task: Add Authentication

- [x] Research existing setup
- [x] Create database schema
- [/] Implement login API (in progress)
- [ ] Build login UI
- [ ] Add tests
- [ ] Deploy and verify

The agent updates this as it works, so you always know where things stand.

2. Implementation Plan (implementation_plan.md)

Created during PLANNING mode. This is where the agent proposes its approach before writing code:

# Add Authentication

## Proposed Changes

### Database Layer

#### [NEW] src/db/schema/users.ts

- User table with email, password hash, created_at

### API Layer

#### [MODIFY] src/app/api/auth/route.ts

- Add POST handler for login
- Add POST handler for register

## Verification Plan

- Run `pnpm build` to verify
- Test login flow with browser

Key behavior: The agent asks you to review and approve the plan before starting implementation. This prevents wasted work on the wrong approach.

3. Walkthrough (walkthrough.md)

Created after completing work. Documents what was done, what was tested, and results:

# Authentication Implementation

## Changes Made

- Created user schema with bcrypt password hashing
- Added login/register API routes
- Built React login form component

## Testing Results

✅ Build successful (0 errors)
✅ Login flow tested via browser
✅ Invalid credentials properly rejected

![Login Page Screenshot](file:///path/to/screenshot.png)

4. Screenshots

The agent captures screenshots to:

• Document UI changes
• Prove features work
• Show before/after comparisons

Screenshots are embedded in walkthroughs and can be viewed in the conversation.

5. Browser Recordings

When the agent uses the browser, actions are automatically recorded as WebP videos. These show:

• Navigation flows
• User interaction testing
• Visual regression checks

6. Knowledge Items

The most powerful artifact type. Knowledge items persist across conversations:

.gemini/antigravity/knowledge/
├── project_architecture/
│   ├── metadata.json
│   └── artifacts/
│       ├── architecture_overview.md
│       └── design_decisions.md
└── deployment_patterns/
    ├── metadata.json
    └── artifacts/
        └── cloudflare_setup.md

How Knowledge Works:

1. After conversations, a Knowledge Subagent reviews what was discussed
2. It extracts useful information and patterns
3. Creates or updates Knowledge Items
4. In future conversations, the agent checks these items FIRST

This means the agent learns over time. The 10th conversation about your project is dramatically more productive than the 1st.

The Artifact Workflow in Practice

Here’s a complete task flow showing all artifacts:

1. You: "Add a dark mode toggle"

2. Agent creates task.md:
   - [ ] Analyze current theme setup
   - [ ] Design the toggle component
   - [ ] Implement theme switching
   - [ ] Test in browser

3. Agent creates implementation_plan.md:
   - Proposes using CSS variables + localStorage
   - Lists files to modify
   - Asks for your review ← YOU APPROVE

4. Agent enters EXECUTION:
   - Updates task.md items to [x] as it works
   - Creates/modifies source files
   - Runs build commands

5. Agent enters VERIFICATION:
   - Takes screenshots (light + dark mode)
   - Records browser toggle interaction
   - Creates walkthrough.md with proof

6. Knowledge Subagent (async):
   - Creates "Theme System" knowledge item
   - Documents the CSS variable approach used
   - Future conversations know the theme pattern

Best Practices

1. Review plans — Don’t skip the implementation plan review
2. Check walkthroughs — They catch issues you might miss
3. Leverage knowledge — Ask “what do you know about this project?”
4. Keep artifacts clean — Delete outdated knowledge items
5. Use screenshots — Especially for UI work, they prevent miscommunication

What’s Next

In the final lesson, we’ll put it all together with real-world workflow examples — showing how to combine Rules, Skills, MCP, and Artifacts for maximum productivity.