The Workspace Pattern: Building Serious Projects with amplihack¶

Quick Start¶

Already convinced? Here's how to set it up:

# 1. Create your amplihack workspace
git clone https://github.com/rysweet/MicrosoftHackathon2025-AgenticCoding.git my-workspace
cd my-workspace

# 2. Add your project (existing or new)
git submodule add <your-project-git-url> my-project
# OR: git submodule add git@github.com:yourname/your-project.git my-project

# 3. Set up project context
cd my-project
cat > AGENTS.md << 'EOF'
# My Project Context

This file provides guidance to AI agents working with this project.

## Project Overview
[Brief description of what this project does]

## Working in This Project

When working on this project:
- All project files belong in this directory
- Use `ai_working/` for temporary files
- Reference files with `@my-project/` prefix
- Follow our design principles at @my-project/docs/DESIGN.md

## Key Technologies
- [List your main technologies/frameworks]

## Development Workflow
- [Your specific workflow notes]
EOF

# 4. Start working
cd ..
uvx claude

In Claude Code, start with:

I'm working on the @my-project/ project within this amplihack workspace.
Please read @my-project/AGENTS.md for project-specific guidance.
For overall design philosophy, refer to @.claude/context/PHILOSOPHY.md.

That's it. Read on for why this matters and how to use it effectively with amplihack.

Why This Pattern Exists¶

When you start using amplihack, the simplest approach is to work directly in the ai_working/ directory. Create a folder, drop in your code, and go. This works great for experiments, prototypes, and small projects.

But as projects grow, you'll hit friction points:

Version control gets messy. Your project files mix with amplihack's structure. When you pull amplihack updates, you worry about conflicts. When you commit project changes, they're tangled with workspace changes.

Context doesn't persist. Each new Claude session starts fresh. You find yourself re-explaining your project's architecture, conventions, and goals. The AI agent is helpful but forgetful.

Boundaries blur. Project-specific documentation ends up in amplihack's docs. Project utilities creep into amplihack's scripts. It becomes unclear what belongs where.

Scaling is awkward. Want to work on multiple projects? You end up with ai_working/project1/, ai_working/project2/, each fighting for the same namespace.

The workspace pattern solves these problems by inverting the relationship: instead of projects living inside amplihack, amplihack becomes a dedicated workspace that hosts projects as first-class citizens.

amplihack-Specific Benefits¶

Using the workspace pattern with amplihack provides unique advantages:

Agent specialization per project. amplihack's powerful agent system (including specialized agents like /amplihack:ultrathink and /amplihack:modular-build) becomes available to all your projects. Each project can have its own AGENTS.md that leverages these specialized agents while maintaining project-specific context.

Philosophy inheritance. Your projects automatically benefit from amplihack's design philosophy documented in .claude/context/PHILOSOPHY.md. The "Brick Philosophy" of modular, regeneratable components applies to your project structure, making it easier to refactor and maintain with AI assistance.

Command integration. amplihack's extensive command library (accessible through slash commands) becomes available across all your projects. Commands like /amplihack:ultrathink for deep analysis or /amplihack:fix for code improvements work seamlessly within project boundaries.

Modular regeneration. Following amplihack's brick-and-stud philosophy, your project modules can be regenerated by AI agents while maintaining stable interfaces. This makes large-scale refactoring safe and predictable.

Persistent learning. As amplihack evolves and learns from your usage patterns, all your workspace projects benefit from those improvements without requiring individual project updates.

The Architecture¶

Think of it like a workshop. amplihack is your workbench with all your tools organized and ready. Your projects are the pieces you're actively working on, each with its own space on the bench but sharing the same tool set.

my-workspace/               # Your amplihack workspace
├── .claude/                # Agent + command definitions
│   ├── agents/             # amplihack's specialized agents
│   └── context/            # Philosophy and design docs
├── docs/                   # amplihack docs
├── scenarios/              # amplihack tools
│
├── my-blog/                # Your first project
│   ├── AGENTS.md           # Project context (AI guidance)
│   ├── docs/               # Project documentation
│   ├── src/                # Project code
│   └── ai_working/         # Temporary work files
│
└── client-portal/          # Your second project
    ├── AGENTS.md           # Different project, different context
    ├── backend/
    ├── frontend/
    └── ai_working/

Each project maintains its own git history, documentation, and context. amplihack stays pristine and updatable. Everything has a clear home.

Setting Up Your Workspace¶

Fork or Clone amplihack¶

Start by creating your personal amplihack workspace:

# Option 1: Fork and clone (recommended if you'll customize amplihack)
# Fork rysweet/MicrosoftHackathon2025-AgenticCoding on GitHub, then:
git clone https://github.com/yourusername/amplihack.git my-workspace

# Option 2: Direct clone (simpler if you won't customize)
git clone https://github.com/rysweet/MicrosoftHackathon2025-AgenticCoding.git my-workspace

Why make it your own? Because you might want to add custom agents, adjust configurations, or experiment with changes without affecting the upstream amplihack repository.

Add Your Project as a Submodule¶

A git submodule is just a way to include one git repository inside another while keeping their histories separate. Think of it as a bookmark: the outer repository (workspace) remembers which commit of the inner repository (project) to use, but the inner repository maintains its own version control.

For an existing project:

cd my-workspace
git submodule add git@github.com:yourname/your-project.git my-project

For a new project:

cd my-workspace
mkdir my-project
cd my-project
git init
git remote add origin git@github.com:yourname/your-project.git
cd ..
git submodule add ./my-project my-project

The key is that my-project maintains its own .git directory and history. Changes you make in my-project/ are tracked by your project's repository, not by the amplihack workspace.

Create Your AGENTS.md¶

This file is your project's persistent memory. Every time Claude starts working with your project, it reads this file first. Think of it as the onboarding document for a new team member—except this team member has perfect memory within a session but starts fresh each time.

cd my-project

Create AGENTS.md with your project's context:

# My Blog Platform Context

This file provides guidance to AI agents working on this blog platform.

## Project Overview

A personal blog platform built with Next.js and Markdown, focused on fast static
generation and rich media support. The architecture prioritizes simplicity over
flexibility—we'd rather have less features done well than many features done poorly.

## Core Principles

- **Ruthless simplicity**: Every feature must justify its existence
- **Static-first**: Generate at build time, serve static HTML
- **Markdown is truth**: Blog posts live in `/content` as Markdown files
- **No database**: File system is our storage layer

## Key Technologies

- Next.js 14 (App Router)
- TypeScript (strict mode)
- TailwindCSS for styling
- gray-matter for frontmatter parsing
- remark/rehype for Markdown processing

## Project Structure

```bash
src/
├── app/            # Next.js app router pages
├── components/     # React components
├── lib/            # Utilities and shared logic
└── types/          # TypeScript type definitions

content/            # Blog posts (Markdown)
public/             # Static assets
```

Development Workflow¶

Run dev server: pnpm dev
Posts go in content/posts/YYYY-MM-DD-slug.md
Images go in public/images/
Test builds with pnpm build

Common Tasks¶

Add new post: Create Markdown file in content/posts/
Add component: Create in src/components/, export from index
Update types: Modify src/types/blog.ts
Deploy: Push to main, Vercel auto-deploys

Things to Avoid¶

Don't add a database (we're committed to file-based)
Don't create complex state management (keep it simple)
Don't add build-time external API calls (they slow builds)

amplihack Integration¶

This project leverages amplihack's design philosophy:

Brick Philosophy: Each component is a self-contained module that can be regenerated
Modular design: Follow @.claude/context/PHILOSOPHY.md for architectural decisions
Agent support: Use /amplihack:ultrathink for architectural analysis
Code transformations: Use /amplihack:codemod for refactoring tasks

The key is making this document useful for both AI agents and human developers. It should answer: What is this project? How is it architected? What conventions do we follow? What should I avoid?

### Optional: Add Philosophy Documents

For larger projects, consider documenting your architectural principles separately:

```bash
mkdir -p docs

Create docs/DESIGN_PHILOSOPHY.md:

# Blog Platform Design Philosophy

## Core Beliefs

**Static generation is superior to dynamic rendering** for content that doesn't
change often. Our blog posts are timeless once published. Pre-rendering them at
build time means instant page loads for readers and lower hosting costs.

**The file system is the database.** Instead of a PostgreSQL table of blog posts,
we have a directory of Markdown files. This makes the content portable, version-
controllable, and debuggable. You can read a blog post without starting the
application.

**Convention over configuration.** We don't need a CMS with ten different ways to
structure a post. We have one way: frontmatter for metadata, Markdown for content.
This constraint is freeing, not limiting.

## Alignment with amplihack Philosophy

This project follows amplihack's Brick Philosophy (see @.claude/context/PHILOSOPHY.md):

- **Bricks and Studs**: Each component (PostList, Header, Footer) is a self-contained
  brick with clear interfaces (studs) that other components connect to
- **Regeneratable modules**: Components can be rebuilt by AI agents without affecting
  the rest of the system, as long as interfaces remain stable
- **Trust in emergence**: Complex features emerge from simple, well-defined components
  rather than being imposed through elaborate architecture

## Decision Framework

When adding features, ask:

1. **Does this need to be dynamic?** If not, do it at build time.
2. **Can we do this with files?** If yes, avoid adding a database.
3. **Is this the simplest approach?** If not, simplify.
4. **Does this align with our principles?** If not, reconsider.
5. **Can this be a regeneratable brick?** If yes, design clear interfaces.

These philosophy documents act as decision filters. When the AI agent proposes something complex, it checks against these principles and often finds a simpler path.

Working in the Workspace¶

Starting a Session¶

When you open Claude Code in your workspace, set context immediately:

I'm working on the @my-blog/ project within this amplihack workspace.
Please read @my-blog/AGENTS.md for project-specific guidance.
All changes should be scoped to the @my-blog/ directory.
Use @my-blog/ai_working/ for temporary files.

For architectural decisions, refer to @.claude/context/PHILOSOPHY.md.

This establishes boundaries from the start. The @ prefix creates namespace clarity—it's always obvious which files belong to which context.

Integration with amplihack Commands¶

amplihack's command system is available throughout your workspace and provides powerful capabilities for project work:

Analysis and Planning:

/amplihack:ultrathink - Deep analysis with extended thinking time
/amplihack:modular-build - Build self-contained modules with clear contracts

Code Transformations:

/amplihack:fix - Automated error fixing and code improvements
/amplihack:improve - Capture learnings and implement improvements

Knowledge and Context:

/amplihack:analyze - Comprehensive codebase analysis
/amplihack:knowledge-builder - Build comprehensive knowledge base

These commands work seamlessly within project boundaries:

Working on @my-blog/. Use /amplihack:ultrathink to analyze the best approach
for implementing automatic social media preview generation while maintaining
our static-first philosophy.

The specialized agents have full access to your project's AGENTS.md and can provide recommendations that align with both amplihack's philosophy and your project-specific principles.

Using @ Syntax Consistently¶

Reference files with their full workspace path:

@my-blog/src/components/Header.tsx
@my-blog/docs/DESIGN_PHILOSOPHY.md
@my-blog/content/posts/2024-01-15-hello.md

This prevents ambiguity. When Claude sees @my-blog/, it knows these files belong to your project, not to amplihack.

Scoping File Operations¶

Tell Claude explicitly when scoping matters:

Please review all TypeScript files in @my-blog/src/ for type safety.

Add error handling to the functions in @my-blog/lib/markdown.ts.

Create a new component at @my-blog/src/components/PostList.tsx.

Being explicit prevents accidental changes to amplihack itself.

Managing Temporary Files¶

Use the project's ai_working/ directory for drafts, experiments, and temporary work:

my-blog/
├── ai_working/                # Temporary work
│   ├── refactor-ideas.md      # Planning documents
│   ├── test-output/           # Test artifacts
│   └── experiments/           # Code experiments
├── src/                       # Real project code
└── content/                   # Real blog posts

This keeps your project clean while giving Claude space to work. The ai_working/ directory should be in your .gitignore.

Version Control Workflow¶

Your workspace and project have independent git histories:

# Working on your project
cd my-blog
git add src/components/Header.tsx
git commit -m "Add responsive header"
git push origin main

# Updating amplihack in your workspace
cd ..                   # Back to workspace root
git pull origin main    # Updates amplihack
git submodule update    # Syncs submodule references

The workspace tracks which version of your project it expects, but your project's git history is entirely separate. This means you can:

Update amplihack without affecting your project
Version your project independently
Share your project without sharing your workspace
Collaborate with others who might use different workspaces

The AGENTS.md Contract¶

Think of AGENTS.md as a contract between you and the AI agents. Each session, Claude reads this contract and agrees to work within its terms. The contract establishes:

What this project is. Not just technically (a Next.js blog), but philosophically (a static-first, simplicity-focused platform). This shapes every suggestion the AI agent makes.

How we work here. Where do files go? What's our naming convention? What commands do we run? These conventions prevent the AI agent from reinventing the wheel each session.

What we avoid. Just as important as what we do. "Don't add a database" is a guardrail that prevents well-meaning but misguided complexity.

Our current state. Technologies, structure, recent changes. This context means the AI agent doesn't suggest outdated patterns or incompatible tools.

The beauty of AGENTS.md is that it compounds over time. Each session, you might add a new insight, clarify a convention, or document a decision. The next session benefits from all previous sessions' learning. Context doesn't reset—it accumulates.

Agent Configuration per Project¶

amplihack's agent system provides powerful project-level customization. Your project's AGENTS.md can specify which amplihack agents to use for specific tasks and how they should behave in your project context.

Configuring Agent Behavior:

## amplihack Agent Configuration

### Preferred Agents for Common Tasks

- **Architecture decisions**: Use `/amplihack:modular-build` with reference to our
  static-first principles in @my-blog/docs/DESIGN_PHILOSOPHY.md

- **Complex refactoring**: Use `/amplihack:ultrathink` to analyze impact across
  all components before making changes

- **Code transformations**: Use `/amplihack:fix` but always maintain TypeScript
  strict mode compliance

### Agent Constraints

When working with amplihack agents on this project:

- All suggestions must maintain static-first architecture
- Database proposals should be immediately rejected
- New dependencies require explicit justification
- Component changes must preserve existing interfaces (brick studs)

Integration with .claude/agents/:

amplihack's workspace-level agents in .claude/agents/ are available to all projects but respect project-level constraints defined in each project's AGENTS.md. This creates a hierarchy:

Workspace-level: amplihack's philosophy and agent capabilities (.claude/context/PHILOSOPHY.md)
Project-level: Your project's specific constraints and preferences (my-blog/AGENTS.md)
Session-level: Specific instructions for the current task

This layered approach means agents can leverage amplihack's general capabilities while respecting project-specific requirements. For example, /amplihack:modular-build knows how to design modular systems (workspace-level) but will apply your static-first constraints (project-level) when working on your blog.

Example Session Integration:

Working on @my-blog/. I need to add a tagging system for posts.

Context:
- Read @my-blog/AGENTS.md for project constraints
- Refer to @.claude/context/PHILOSOPHY.md for modular design approach
- Use /amplihack:modular-build to design the solution

Requirements:
- Must work with file-based storage (no database)
- Tags should be in frontmatter
- Generate tag index at build time
- Keep components regeneratable (brick philosophy)

The agent will combine amplihack's architectural expertise with your project's specific constraints to provide a solution that's both well-designed and appropriate for your context.

When to Use This Pattern¶

The workspace pattern isn't always the right choice. Here's a decision framework:

Use ai_working/ for:

Quick experiments and prototypes
Learning exercises and tutorials
Throwaway code and one-off scripts
When you need something fast and don't care about long-term maintenance

Use the workspace pattern for:

Projects that will live for months or years
Codebases with their own git repository
Work you'll share with others or deploy to production
Projects where you want persistent AI context
When you're working on multiple projects simultaneously
When you want to leverage amplihack's agent system fully

Think of ai_working/ as your scratch pad and the workspace pattern as your filing cabinet. Both have their place.

Migrating from ai_working/¶

Already have a project in ai_working/ that's outgrown it? Here's how to migrate:

1. Initialize Git in Your Project¶

cd ai_working/my-project
git init
git add .
git commit -m "Initial commit - migrating to workspace pattern"

2. Push to Remote Repository¶

Create a repository on GitHub/GitLab/etc, then:

git remote add origin git@github.com:yourname/my-project.git
git push -u origin main

3. Move to Workspace Root¶

cd ../..  # Back to workspace root
git submodule add git@github.com:yourname/my-project.git my-project

4. Copy Working Files¶

If you have useful temporary files in the old location:

cp -r ai_working/my-project/ai_working my-project/ai_working

5. Create AGENTS.md¶

Document what you've learned about this project:

cd my-project
cat > AGENTS.md << 'EOF'
# My Project Context

[Document your project's architecture, conventions, and principles]

## amplihack Integration

This project uses amplihack's workspace pattern and agent system.

Refer to @.claude/context/PHILOSOPHY.md for modular design guidance.
EOF
git add AGENTS.md
git commit -m "Add AGENTS.md for workspace pattern"
git push

6. Update Your Workspace¶

cd ..  # Back to workspace root
git add .gitmodules my-project
git commit -m "Add my-project as submodule"

7. Clean Up Old Location¶

rm -rf ai_working/my-project

Now your project has clean git history, persistent context, and clear boundaries.

Multiple Projects¶

The workspace pattern shines when you're working on several projects. Each project gets its own submodule with its own AGENTS.md:

my-workspace/
├── personal-blog/           # Personal project
│   └── AGENTS.md           # "This is a casual blog..."
├── client-portal/          # Client work
│   └── AGENTS.md           # "Enterprise security requirements..."
└── ml-experiment/          # Research project
    └── AGENTS.md           # "Experimental ML approaches..."

When you switch projects, just tell Claude which context to load:

Switch to working on @client-portal/. Read @client-portal/AGENTS.md.

The AI agent instantly adapts to that project's conventions, technologies, and constraints. No cross-contamination between projects.

Practical Tips¶

Keep AGENTS.md current. When you make architectural decisions, document them. When you adopt new conventions, add them. Treat it as a living document.

Use philosophy docs for big decisions. If you find yourself making the same architectural argument repeatedly, write it down in a philosophy document. Then reference it: "Review this against our principles at @my-project/docs/DESIGN_PHILOSOPHY.md."

Namespace with @. Always use the @project-name/ prefix in Claude conversations. It prevents ambiguity and makes transcripts clearer.

Separate concerns clearly. Project code in the project directory. amplihack customizations in the workspace. Temporary work in ai_working/. Clear boundaries prevent confusion.

Update amplihack regularly. Since your projects are isolated submodules, you can pull amplihack updates without fear:

cd my-workspace
git pull origin main
git submodule update

Your projects remain untouched while you get the latest amplihack features and agent improvements.

Commit project changes frequently. Since your project has its own git history, commit often. This creates restore points and makes collaboration easier.

Leverage amplihack agents. Don't forget to use specialized commands like /amplihack:ultrathink for deep analysis or /amplihack:modular-build for modular design work. These agents understand both amplihack's philosophy and your project's constraints.

Common Questions¶

Q: Can I use this pattern without git submodules?

Yes, but you lose the version control isolation. You could symlink your project directory into the workspace, but then you don't get the clean separation of git histories. The submodule approach is recommended precisely because it maintains that separation.

Q: What if I want to customize amplihack?

That's why you fork it first. Make your workspace repository your own fork, then customize away. Add custom agents, modify configurations, experiment with new features. Your projects continue working because they're isolated submodules.

Q: How do I share my project with someone using a different workspace?

Just share the project repository. They add it as a submodule to their workspace (which might be amplihack, amplifier, or something else). The project code is fully portable—it doesn't depend on any specific workspace configuration.

Q: Can I have nested projects?

Technically yes, but it gets complicated. Better to keep projects flat at the workspace level. If you need related projects, make them siblings rather than nested.

Q: What goes in the workspace's ai_working/ vs the project's?

Workspace-level experiments and notes that span multiple projects. Project-specific temporary files in the project's ai_working/. When in doubt, put it in the project's directory.

Q: Do amplihack commands work in my project?

Yes! All amplihack commands (like /amplihack:ultrathink, /amplihack:modular-build, etc.) work seamlessly within your project. They have access to both your project's AGENTS.md and amplihack's workspace-level philosophy documents.

Q: How do I install and run amplihack?

amplihack can be run with uvx claude from your workspace directory, or you can install it globally. Refer to amplihack's main documentation for installation options.

The Pattern in Practice¶

Here's what a typical session looks like once you've internalized the pattern:

cd my-workspace
uvx claude

In Claude:

Working on @personal-blog/. Read @personal-blog/AGENTS.md.

I want to add a new feature: automatically generate social media preview images
for blog posts. This should happen at build time and follow our static-first
philosophy. What's the best approach?

For architectural analysis, use /amplihack:modular-build with reference to our
Brick Philosophy at @.claude/context/PHILOSOPHY.md.

Claude reads your AGENTS.md, understands your tech stack (Next.js) and principles (static-first, simple), accesses amplihack's architectural guidance, and proposes a solution that fits your architecture. The specialized agents ensure the solution is modular and regeneratable. No need to re-explain your project every time.

When you're done:

cd personal-blog
git add .
git commit -m "Add social media preview generation"
git push

Clean git history, persistent context, clear boundaries, and powerful agent support. The workspace pattern with amplihack working as intended.

Conclusion¶

The workspace pattern is about treating your development environment as seriously as your code. By inverting the relationship—making amplihack the host rather than the container—you get clean separation, persistent context, agent system integration, and a scalable foundation for multiple projects.

It's more setup than dropping code in ai_working/, but the payoff grows over time. Each project accumulates context through AGENTS.md. amplihack stays updatable with new agents and features. Version control stays clean. And you can work on multiple projects without them interfering with each other. All while benefiting from amplihack's powerful agent system and Brick Philosophy for modular, regeneratable code.

Start simple with ai_working/ for experiments. Graduate to the workspace pattern when projects get serious. Your future self will thank you, and the AI agents will work more effectively with the persistent context and clear boundaries.