Asking a model to write a small function is no longer the interesting part of AI-assisted development. The difficult transition happens one level above that. A task becomes “understand this product, find the right part of the repository, change only what needs changing, preserve behaviour we already trust, and leave enough evidence for somebody else to judge the result.” At that point the model is not merely a faster keyboard. It is participating in an engineering system that needs context, permissions, memory, checks and a credible definition of done.
We started exploring this more deliberately while the project was still called Blupoli Puzzles. The current identity is Blupoli and the games product is Blupoli Puzzles, but the original question still describes the work well: how do we use agents without turning the repository into a stream of fast changes that nobody fully understands? The answer we are converging on is not one magical agent. It is a loop in which every participant leaves evidence that another participant can inspect, challenge and improve.
Calling it a “team” does not mean replacing people with models
The phrase “AI team” can suggest a fully autonomous organisation where a swarm receives a vague goal and somehow delivers a finished product. That is not the model we are trying to build. “Team” describes a distribution of work. Different tools can research, implement, compare alternatives, review diffs or prepare documentation, while a person remains responsible for direction, priorities and acceptance. The useful part is not the theatrical resemblance to a human org chart. It is that each role has a recognisable input, output and boundary.
That distinction protects us from a dangerous expectation. An agent can produce a great deal of code without automatically possessing months of product history, the reason a strange convention exists, or the judgement needed to decide whether an interaction actually feels good. It can retrieve some of that knowledge when the repository expresses it clearly, and it can collect evidence that supports a decision, but production capacity is not the same thing as authority over product direction. Technical autonomy works best inside explicit constraints.
Context becomes part of the infrastructure
A developer who has lived in a codebase for months carries an invisible map: which folder is canonical, which abstraction failed before, which component is the best reference, and which shortcut looks tempting but has already caused trouble. A fresh agent session has none of that continuity unless the project makes it available. Documentation, conventions, well-written tasks and repository structure therefore stop being optional background material. They become part of the runtime environment for collaborative work.
The goal is not to document absolutely everything. A giant handbook can be just as unusable as no documentation at all. We care most about information that reduces future ambiguity: architecture, sources of truth, quality gates, verification commands, recurring decisions and strong examples that can serve as precedents. A short instruction that points to one trustworthy document is often more effective than an enormous prompt that tries to replay the entire history of the project from memory.
A useful task has an observable definition of success
Agents become much more reliable when the task describes something that can be inspected at the end. “Improve the catalogue” leaves too many hidden decisions. “Make translated article cards use translated titles, descriptions and covers, preserve canonical routes, and pass the editorial checks” defines a surface that can actually be tested. Precision does not remove room for investigation or design. It removes needless guessing about which problem the task is supposed to solve.
It helps just as much to say what must not change. Real repositories contain behaviour that already works, compatibility requirements and concurrent work on other branches. Explicit boundaries prevent opportunistic refactors from making a diff larger without making the outcome better. A task that is ready for delegation should answer four questions: what should be observable when we are done, where are the relevant references, which constraints are non-negotiable, and what evidence will count as completion?
Git becomes verifiable memory, not just version control
Branches, commits and pull requests fit agent workflows unusually well because they turn every proposal into something concrete. A conversation can claim that a problem is fixed; a diff shows exactly what changed. An agent can explain its reasoning, but the repository lets us compare that explanation with files, tests and build output. The distinction between narrative and evidence becomes essential once the cost of producing changes drops dramatically.
Git also makes exploration cheap without making every experiment permanent. We can branch, let a tool try an approach, compare it with the base and throw it away if the result is worse. The ability to revert changes lowers the risk of trying ideas. At the same time, a well-described commit or PR creates a durable precedent another agent can discover later. Project memory no longer depends entirely on finding the right old chat or asking the same person to remember why something happened.
Delegating and routing are different operations
In practice we have had to separate two ideas that often get bundled together. Delegation means assigning part of the work inside a flow that already controls the repository and its context. Routing means sending a task to another tool or agent with a different environment, capability set or permission model. Both can be valuable, but they fail in different ways.
An external agent may be excellent at reasoning about an algorithm and still be a poor choice for modifying the product if it cannot inspect the right files or return a reviewable patch. An integrated agent may be able to edit a branch effortlessly and still not be the strongest option for specialised research. The selection question should therefore be less “which model is smartest?” and more “which combination of context, tools, permissions and evidence does this task require?”
Permissions are part of system design
Autonomy without permissions is a demo; permissions without boundaries are a risk. Real work may require reading project files, writing to a branch, executing checks or interacting with external services. But not every task needs the same reach. A code review may only need read access. An editorial rewrite needs to update files on a feature branch, not administer the whole repository. Deployment automation deserves a stricter model than drafting copy.
Thinking about permissions as design has a useful side effect: it forces the task to become clearer. If we cannot explain the minimum capability a task needs, we may not have separated its responsibilities well enough. Friction is informative too. When an agent cannot complete a step, that failure may reveal a hidden manual dependency or two jobs that should have been split apart. The goal is not unlimited access. It is access that is narrow enough to understand and broad enough to finish the assigned work.
Evidence should be independent from the implementation story
One of the easiest mistakes in a fast workflow is treating the same system that made the change as the only authority on whether the change is correct. If an agent rewrites a generator and then reports that generation is better, we still need something capable of disagreeing. Tests, validators, builds, snapshots, independent reviews and behavioural comparisons create evidence that does not rely on trusting the author’s own description.
This matters especially with language models because explanations can sound persuasive even when one detail is wrong. A failing command is less eloquent and more useful. A quality gate that catches a broken route is stronger evidence than a paragraph claiming all links were checked. Not every product decision can be automated, but anything that can be verified cheaply and repeatedly is a strong candidate for becoming part of the system.
Puzzles are an unusually good laboratory for false confidence
Blupoli Puzzles contains many problems where an output can look plausible while being wrong underneath. A generated board may have the right visual shape and multiple solutions. A solver may find one answer without proving uniqueness. An “expert” difficulty may use a larger grid while remaining trivial. That combination—convincing appearance, hidden invalidity—is very similar to the failure mode of code produced quickly without independent checks.
That is why puzzle engines have pushed us toward separate validators. “Generating is not solving” explores the algorithmic side of that problem. The broader agent lesson is simple: when a task can generate an output that merely looks correct, the workflow should ask what could prove it wrong. The ability to refute a result belongs inside the quality definition, not as an afterthought once something reaches production.
Specialised roles reduce implementation bias
We do not assume the same agent should always investigate a problem, build a solution and judge its own work. Separating roles can improve the result even when the underlying tools are similar. One agent can research existing patterns before any files change. Another can implement inside a deliberately narrow scope. A third can inspect the diff from the perspective of expected behaviour, looking for forgotten routes, unsupported assumptions or conflicts with documentation.
The point is not to mimic a human company for show. It is to introduce different questions. The implementer naturally follows the path it has already chosen. A reviewer can begin from the acceptance criteria and search for places where that path fails. Partial independence increases the chance of finding problems the author has stopped noticing. Human code review has relied on the same principle for years; cheap machine-generated second opinions make it easier to apply more often.
Parallelism only helps when the boundaries are real
Launching several agents at once sounds like a straightforward way to multiply throughput. Sometimes it is. But parallel work creates coordination cost. If two tasks touch the same files, depend on an unresolved design decision or duplicate the same investigation, the apparent speed turns into merge conflicts and inconsistent solutions. The real question is not how many agents we can run. It is how much work is genuinely independent.
Good parallel candidates tend to have natural boundaries: researching options without editing, preparing translations in separate files, reviewing one PR while another branch handles unrelated functionality, or dividing a migration into units that share a contract but not an editing surface. When coupling is high, sequencing is often faster overall. Coordination is work too, even when it does not show up in a commit’s line count.
Documentation close to the code reduces entropy
The more automation we introduce, the more valuable it becomes for operational knowledge to live near the thing it governs. A repository that explains its architecture, commands and conventions can orient both humans and agents. If the same information is spread across old chats, private notes and somebody’s memory, every new session reconstructs a slightly different version of reality.
That does not mean every product document belongs in Git. It does mean the decisions required to modify the software should be reachable from the development workflow. At Blupoli we increasingly try to bring specifications, tasks and technical documentation closer to where they are used. Documentation is useful not because it exists, but because it appears at the point where a decision needs context.
Context size is also a resource that needs design
More information is not automatically better. An enormous context can bury the one critical restriction under hundreds of irrelevant details. Reading and reasoning over material also has a cost. A mature workflow therefore moves away from ever-larger prompts and toward discovery: a small instruction tells the agent where the source of truth lives, and the agent retrieves only the pieces it needs.
This rewards repositories with clear names, focused documents and explicit links between related concepts. It also makes contradictions more dangerous. If two guides describe different conventions, an agent cannot reliably know which one represents the current system unless another signal resolves the conflict. Maintaining canonical guidance and retiring stale instructions is part of repository hygiene. AI amplifies good documentation, but it amplifies bad documentation just as efficiently.
Human review changes when alternatives are cheap to produce
Historically, a large part of engineering time could be spent simply turning the first viable idea into something concrete enough to evaluate. When that cost falls, review shifts toward comparison and consequences. We can ask for two approaches, inspect both diffs and decide which one better matches the product. Human judgement does not disappear. It moves toward the areas where it has the most leverage: priorities, coherence, simplicity and experience.
A lower generation cost also creates a healthy obligation to discard more work. If producing a candidate solution was cheap, we should be less emotionally attached to keeping it. Otherwise sunk-cost thinking turns fast generation into a pile of mediocre code that is endlessly polished. A good agent workflow treats “we explored this and decided not to merge it” as a valid outcome when the evidence points elsewhere.
Some tasks do not need an agent at all
Useful AI adoption includes recognising where delegation adds no value. A sensitive brand decision, a subtle visual judgement or a conversation with users may depend on context that is not captured in files. A tiny code change that a developer understands completely may take less time to make directly than to package, delegate and review. Automation for its own sake can introduce ceremony without improving the result.
Our practical rule is to use agents when they expand capacity, explore a wider solution space or execute repeatable work without harming traceability. We avoid them when delegation costs more than the task, when the required evidence is unavailable, or when responsibility cannot reasonably be transferred. The goal is not to maximise the percentage of work attributed to AI. The goal is to improve the system we use to build the product.
Product architecture determines how much work can be delegated safely
A modular repository is easier for agents to change for exactly the same reason it is easier for people to change: responsibilities are less entangled. If one puzzle engine mixes rules, navigation, presentation and persistence, even a small change requires understanding too much at once. When engine, host and UI have clear contracts, a task can operate inside a much smaller boundary.
That is why the puzzle-engine architecture is directly relevant to AI-assisted development. The architecture was not invented for agents, but agents benefit from it. They can operate more independently when the repository clearly states what belongs to each layer and tests defend the contract. Good architecture lowers the amount of context required to make a safe change.
The repository starts to behave like a collaboration interface
Once a meaningful amount of work passes through agents, the quality of the repository as an interface becomes obvious. Names, folder structure, scripts, error messages, examples and documentation determine how quickly a new participant can orient itself. A codebase that can only be modified correctly after a long oral handover has an undocumented human API. Making some of that API explicit helps everyone who arrives later.
This changes how we value small engineering improvements. A script that fails with a precise message is more useful than one that simply exits with status 1. A test whose name explains the contract teaches while it verifies. A task that links to the right precedent reduces search. These details make the project operationally legible, which in turn makes agent speed less dependent on a single person guiding every step.
The loop we are trying to make routine
Our current model can be summarised in four movements. First, context: define the goal, constraints and sources of truth. Second, execution: research or implement inside a limited unit of change. Third, evidence: run tests, builds and validators, then inspect the diff. Fourth, judgement: accept, revise or rethink the proposal. Whatever we learn feeds back into context so that the next task begins from a stronger baseline.
The important detail is that the loop does not end when the model produces an answer. It ends when the state of the project is understandable. The outcome may be code, documentation, a PR, a new test or even a decision to leave the code unchanged. The product of the task is a verifiable improvement to the system, not the volume of text or lines created during the process. That definition helps prevent activity from masquerading as progress.
What changed when Blupoli Puzzles became Blupoli
The rebrand did not fundamentally change this workflow, but it widened the scope of the problem. Blupoli Puzzles could be imagined as one puzzle platform. Blupoli is intended to provide a broader identity for multiple products and the editorial layer connecting them. Architecture, content and automation therefore need clearer boundaries between what belongs specifically to Blupoli Puzzles and what belongs to the wider ecosystem.
That makes context even more important for agents. “Change the website” no longer points to one obvious application. A task may need to know whether it is touching Blupoli Puzzles, the main site, shared packages or documentation. Brand evolution reinforces a lesson we had already learned from software architecture: as a system grows, names and boundaries stop being organisational niceties and become prerequisites for safe work.
Useful speed should make the next task easier
The metric we care about is not how many lines an agent can produce in an afternoon. It is whether the project becomes easier to understand and verify after the change. Sometimes that means adding a test. Sometimes it means consolidating a source of truth, removing duplication, documenting a convention or turning a manual check into an automated gate. The best form of acceleration solves today’s problem while reducing tomorrow’s friction.
That perspective also gives us a healthy limit on mass generation. If every task adds exceptions, special instructions and duplicated files, apparent productivity creates a tax on future work. We want the opposite: use agent capacity to do more while strengthening the structure that makes the output trustworthy. Speed and maintainability do not have to be enemies when review and refactoring are treated as part of the same loop.
What we are still learning
We do not have a final model for an “AI development team.” Tools change, autonomy improves and every repository exposes different constraints. What has remained stable is a small set of principles: small but canonical context, observable tasks, minimum permissions, reviewable changes, independent evidence, specialised roles when they create a genuinely different perspective, and a human owner for product decisions.
Blupoli will keep being a place to test those principles against real work. The benefit of doing this inside a live product is that mistakes cannot hide behind a demo. A broken route, a weak puzzle or an inconsistent translation eventually becomes visible. That forces the agent system to meet the same standard as any other engineering tool: not how impressive it looks while running, but how much it improves the product and the confidence with which we can continue changing it.
Using AI as a team ultimately means designing the work better
The most valuable conclusion from experimenting with agents is not simply that they can do more than we expected. It is that they force us to define more clearly how we want work to happen. Good delegation requires named sources of truth, separated responsibilities, acceptance criteria, automated checks and durable decisions. All of those practices were useful before generative AI. The difference is that their value now appears immediately and repeatedly.
That is why we prefer to think in terms of collaboration rather than replacement. People provide direction, broad context and judgement. Agents provide speed, exploration and the ability to execute well-scoped work. Git and verification provide memory and evidence. When those pieces fit together, AI stops being a generator of snippets and becomes a genuine part of the development process—not because it gets the final word, but because the project is designed to work with it responsibly.