The NicAI workspace

Everything NicAI does happens in one folder: ~/ai. It holds the skills, the shared tools, the databases, the knowledge bases and every output. Claude Code runs inside it, reads the rules that live there, and writes its results back into it.

I moved to this layout in February 2026, when the work and personal folders were created side by side. One folder means one set of rules, one set of tools and one place to look.

The domains

Each top-level folder is a self-contained domain. The bigger ones have their own CLAUDE.md with rules that apply only there (see My Claude Code setup for how those files stack).

The split follows a simple question: whose data is it? Work data stays in ka/, private data stays in me/. A skill in one domain doesn't read the other's knowledge base unless I point it there. The shared tools are the only code both sides use, and NicAI shared tools covers them.

The conventions

The workspace CLAUDE.md is only 90 lines. Most of it is a map and a short list of rules. These are the rules that matter:

• Scripts at the project root. No scripts/ subfolder. An agent finds the script where it expects it.
• SQLite in db/. Always SQLite, always in a db/ subfolder. 5 lab projects and both main domains follow this.
• Knowledge in kb/. Markdown articles in a kb/ folder per domain. Skills read them as their first source.
• Shared keys in 1 place. All API keys sit in _shared/.env. No project keeps its own copy.
• Dated output folders. Every task gets its own subfolder in output/, named YYMMDD-slug, for example 260909-event-debrief. No loose files. The date is the day the work starts and stays fixed when I iterate.
• Deliverables at the root, working files below. The root of a task folder holds only what I open: the .md, .pdf, .pptx or .html. Scripts go in build/, sources in src/, raw inputs in data/, images in media/, preview renders in qa/.
• Versions, not overwrites. A new iteration gets -v2, -v3 in the filename. A delivered version is never overwritten.
• A context file per artifact. On the work side, each artifact folder has a _CONTEXT.md: the goal, the inputs, the decisions and a 1-line log per version. When an agent picks the work up days later, it reads this file first.
• No new top-level folders. A task never creates a new folder in ka/, me/ or lab/. If nothing fits, the answer is output/YYMMDD-slug/. Only I create new top-level folders, or approve a skill that declares one.

The last rule came from experience. An agent that can't find a home for a file makes one, and the workspace fills up with folders nobody owns.

TASKS.md: the queue

Each domain has a TASKS.md file. It is my to-do list for the agents, in plain Markdown, with 3 sections:

## Active
[ ] task description

## Waiting On Nic
[ ] task description (reason it's blocked)

## Done
[x] ~~task description~~ (date, duration)

It works like this:

1. I add a line under Active, in the same words I would use in chat.
2. I say "run your tasks" (or just "tasks.md") in that domain.
3. The main agent reads the file and starts 1 agent per task. Each agent can start its own sub-agents, but never takes on a second task. Independent tasks run in parallel. Tasks with a stated order wait for each other.
4. A finished task is ticked, struck through and moved to Done, with the date and how long it took.
5. A task that needs a decision from me moves to Waiting On Nic, with the reason in brackets. The agents never touch that section until I unblock it.

Why 1 agent per task? A single agent that runs 10 tasks carries the context of all 10. By task 7 it mixes up details from task 3. A fresh agent per task starts clean and fails alone.

Scale

On the work side, the busiest month was July 2026, with 607 tasks done. The personal queue has no Done entries after 15th June 2026.

What works

• Agents find things. The same layout everywhere means a new session knows where the tools, data and outputs are without a search.
• The queue scales. I write a batch of tasks, leave, and come back to a batch of results to review.
• Waiting On Nic keeps agents honest. An agent that is stuck parks the task with a reason, instead of guessing.

What doesn't

• The rules came late. The dated-folder rule arrived in September 2026. The work output/ folder still holds 350 loose files, and only 32 of its 69 subfolders start with a date.
• Drift between domains. The personal TASKS.md uses "Waiting" and "Completed" as section names, not "Waiting On Nic" and "Done". It works today, but it's the kind of inconsistency that breaks a script later.
• The Done list grows. The work file is over 1,400 lines. It's a log now, not a list. It will need an archive.

What I'd fix next

• Move old Done entries into an archive file, so TASKS.md stays short.
• Sort the old loose output files into dated folders, or delete them.
• Give both TASKS.md files the same section names.

Related notes

• The overview: What is NicAI
• The instruction files and settings: My Claude Code setup
• The skills that run the tasks: The NicAI skills catalogue
• The shared tools: NicAI shared tools
• The databases and knowledge bases: The NicAI data layer