Agentic Engineering

How we use AI agents as first-class collaborators — by Inctasoft

The Idea

The AI agent is not a tool you invoke — it's your primary collaborator. Everything in this workspace — docs, slash commands, hooks, project structure — is designed so that when Claude enters the workspace, it immediately knows where it is, what exists, how things connect, and what to do next.

Every project has a CLAUDE.md (what is this? how do I build it? what are the gotchas?), a DIFFICULTIES-LOG.md (what went wrong?), and a central registry (the single source of truth for ports, subdomains, dependencies, and deploy procedures).

Slash Commands

/docs-load <projects>

Deep-load context for one or more projects. Reads CLAUDE.md, DIFFICULTIES-LOG, docker-compose, .env.example, and architecture docs. Makes the agent the master architect for those projects.

/docs-load cars eops radar

/docs-update [projects]

Scan documentation against actual code and config. Fixes stale info, fills gaps, compacts the difficulties log (removes resolved items). This is how docs stay alive.

/docs-update cars eops

/status [ecosystem]

Check service health — ports, Docker containers, systemd units. Omit the argument to see everything.

/status radar

/start <ecosystem>

Start services in dependency order. The DAG is walked automatically — starting cars also ensures shared-auth and reverse-proxy are running.

/start cars

/stop <ecosystem>

Stop services in reverse dependency order. Shared services (Caddy, shared-auth) are kept running unless you explicitly stop all.

/stop radar

/deploy <services | all>

Unified deploy — auto-detects PROD vs DEV by machine. Pulls latest code, rebuilds, verifies health. Works cross-machine via SSH when needed.

/deploy cars

/push [repos]

Traverse git repos, analyze diffs, skip junk files, commit with descriptive messages, and push. Prints a summary table at the end.

/push eops scraper

/hide <service>

Toggle public visibility — disable or re-enable a service's Caddy route without tearing down the containers.

/hide scraper

/eject <service>

Remove a project from the ecosystem entirely — registry, CLAUDE.md, Caddy config, Docker resources.

/eject connectivity-tester

/b [target] Playwright

Open the browser via Playwright MCP and perform an action. Infers the target from arguments or conversation context (e.g. google, cloudflare, supertokens, any app name or URL).

/b google console

Hooks

Difficulties Logger

UserPromptSubmit — fires on every prompt

Injects standing instructions telling the agent to log any difficulty, unexpected behavior, or friction it encounters to the current project's DIFFICULTIES-LOG.md. Auto-detects which project you're in based on the working directory. If at the workspace root, entries go to the canonical cross-project log.

The agent tries to fix issues on the fly (marked FIXED if resolved). At the end of every response it reports: "Difficulties: none" or "Difficulties: logged N new item(s)".

This is the core of the compound learning loop — every session leaves the workspace smarter for the next one.

The Workflow

Start Claude from the workspace root

cd ~/projects && claude — Agent reads root CLAUDE.md, knows all projects, ports, subdomains, and connections.

Load deep context

/docs-load cars eops — Agent becomes the master architect for those projects. Knows code structure, open issues, conventions.

Work on the task

Build features, fix bugs, refactor, debug. The difficulties hook captures friction as it happens.

Manage services

/status, /start cars, /stop radar — check health, start/stop ecosystems with automatic dependency resolution.

Deploy

/deploy cars — pull, rebuild, health-check. Cross-machine via SSH when running from DEV.

Push code

/push — commit meaningful changes across all dirty repos, skip junk, push to GitHub.

Update documentation

/docs-update — agent scans docs against code, fixes drift. The workspace converges on truth.

The Dependency DAG

Services form a directed acyclic graph defined in registry/services.yaml. The /start, /stop, and /deploy commands all respect it.

The Compound Effect

Each conversation builds on the last:

Agent reads CLAUDE.md

Knows the system.

Agent reads DIFFICULTIES-LOG.md

Knows what's broken.

Agent works on your task

Discovers new issues.

Agent logs difficulties

Next agent starts smarter.

Run /docs-update

Documentation reflects reality. The workspace gets easier over time, not harder.

You decide what to build, what matters, and what's good enough. The agent remembers, executes, and documents.