Project Knowledge - Modelcode

Project Knowledge is where all structured project context lives in the product — the Project Spec, Project Setup (lifecycle scripts, environment variables, dependencies, Dockerfile), milestones, wikis, and rules — together with Knowledge chat for conversing with . You open it from the Roadmap: under Modernization, click Project Knowledge. During onboarding opens this drawer for you twice: first to review and approve the Project Spec, and then — at the High validation level — to go through Project Setup, discovering and validating the application’s lifecycle alongside the agent. Throughout the migration, agents read from and write to the same underlying knowledge; this UI is how you inspect and steer it.

What Project Knowledge Is

Think of Project Knowledge as structured context for Morph agents, surfaced in a full-height drawer on the Roadmap. Every time an agent works on a task, the agent reads this knowledge to understand your project’s architecture, conventions, how the application actually runs, and decisions already made. When an agent learns something new during execution — a pattern the agent discovered, an architectural decision, a fix to a startup script — the agent writes that back (often as wiki pages, rules, or lifecycle updates). This is how agents pass knowledge to each other. Onboarding establishes how the app installs, builds, and runs (for projects on High validation). Milestone 1 might establish a database access pattern. Milestone 5, handled by a different agent, reads both from the same project knowledge and follows them. The result is consistent code across your migration — and a configuration the agent can actually run — even when different agents handle different parts.

What’s Inside

Project Knowledge is organized in a tree:

Type	What It Holds	How It’s Used
Project Setup	Lifecycle for Origin and Target (scripts, environment variables, lifecycle document), Acceptance Criteria, plus either Dependencies (self-hosted) or Dockerfile (cloud)	Agents use the lifecycle to run, validate, and functionally test the application; acceptance criteria define quality gates
Project Spec	Goals, scope, and approach for the migration	Agents reference the Project Spec to stay aligned with the overall direction
Milestones	Detailed descriptions and scope for each migration step	Agents use milestone content to understand what each step requires
Wiki	Architecture docs, design decisions, patterns discovered during migration	Agents read wikis to understand project context and conventions
Rules	Coding standards, library preferences, explicit constraints — grouped as Published, Draft, or Archived	Agents follow published rules as hard requirements in every milestone

How Agents Use It

When an agent starts working on a milestone:

It reads the Project Spec to understand the migration’s overall goals
It reads the Project Setup to know how to install, build, run, and health-check the app
It reads all rules to know which standards to follow
It reads relevant wiki pages to understand architecture and patterns
It reads the milestone description to know what to build

After execution, the agent writes back anything it learned — new patterns, architectural decisions, integration notes, and any lifecycle fixes it needed to make the app run — as wiki pages or as updates to the lifecycle configuration. That keeps project knowledge growing and more accurate over the course of the migration.

Opening Project Knowledge

During onboarding — Project Spec: When your Project Spec finishes generating, the drawer opens with Project Spec selected so you can review and approve it. During onboarding — Project Setup: After you approve the spec and pick the High validation level, the Project Setup stage on the Roadmap opens the drawer again with Knowledge chat seeded to start setup — the agent walks you through discovering and validating how your application installs, builds, runs, and is health-checked. See Project Setup (Onboarding) below. Any time after that: Go to the project’s Roadmap. In the left Modernization column, click Project Knowledge to open the drawer. You can also open it from flows that link knowledge (for example, opening a rule, milestone, or lifecycle script in context).

Project Setup (Onboarding)

Project Setup is the branch of the Project Knowledge tree that holds everything needs to actually run your application. It’s also where the Project Setup onboarding stage happens — the agent collaborates with you in Knowledge chat to fill this branch in, then validates it end to end.

Project Setup runs only at the High validation level, after the Project Spec is approved. At Low and Mid, never builds or runs the origin application, so there is no origin lifecycle to set up. See Validation Level.

The branch is organized by side of the migration, mirroring the rest of project knowledge:

Origin — How the source application builds and runs. Discovered together with you during onboarding and used as the behavioral baseline for functional testing.
Target — How the destination application builds and runs. Discovered automatically during the foundation milestone (Milestone 1) so the target side is ready before migration code starts landing.
Dependencies and Dockerfile — Project-wide artifacts the agent builds during onboarding and keeps in sync as the project evolves.

Each origin/target entry contains three sub-items you can select in the tree:

Sub-item	What it is
Scripts	Ordered shell scripts — typically `install`, `build`, `run`, `healthcheck`, and `test` — that bring the app to a healthy, running state
Environment Variables	Variables and secrets the app needs at build or runtime, discovered from the codebase or set explicitly. Secrets are encrypted at rest
Lifecycle Document	A markdown overview describing the application’s architecture, the execution order of scripts, and how each phase fits together

How Project Setup flows through this drawer

The Project Setup stage on the Roadmap routes you into the Project Knowledge drawer with the chat focused on lifecycle discovery. Until the agent has discovered something to show, the drawer is chat only — the tree and content pane appear once the configuration exists. From there:

The agent inventories your repository — framework, install/build/run commands, healthcheck signals, env vars and secrets, external service dependencies — and reports back what it found before writing anything.
It proposes the lifecycle phases (install / build / run / healthcheck / test, plus optional steps like migrate or per-service splits in multi-environment projects) and confirms them with you.
It registers the scripts and environment variables, asking you for any values it can’t infer (service URLs, tenant-specific config). Credentials are requested with a Provide Secret card that encrypts the value immediately — never type a secret into the chat box.
It executes the lifecycle end-to-end to validate it actually works. On failure, it surfaces the failing phase, the last lines of output, and a proposed fix before retrying.
Once validation passes, the lifecycle is marked Validated and onboarding continues to Generate Roadmap. If the agent can’t get it fully healthy, it asks you to confirm saving the configuration as Draft — Needs Review so you can correct it.

You can see this happen live in the drawer: the tree on the left shows the Project Setup branch filling in as the agent works, and the chat on the right is where you answer questions and approve choices.

Lifecycle validation statuses

Status	Meaning
Validated	Lifecycle ran successfully end-to-end
Draft — Needs Review	Saved but not fully healthy — needs manual correction
Pending Validation	Awaiting first validation run
Failed	Last validation run failed
Imported — Needs Verification	Imported from organizational knowledge — re-validate to confirm

Project Setup tree and content panel in the Project Knowledge drawer

Editing the lifecycle later

Scripts and environment variables stay editable in the panel — use Add Script, Add Variable, and Save Changes. The lifecycle document, Dockerfile, and Dependencies are displayed read-only; the last two carry the hint “Read-only — ask the chat to update this.” Change any of them by asking the chat. Running validation always goes through the chat. Re-validate in the toolbar hands the run to the agent, so you can watch it work and answer questions mid-run. Ask Knowledge chat whenever you’d rather have the agent work the change out itself. Typical asks:

The run script should bind to port 8080, not 3000.
Re-validate after the change.

Add a `migrate` script that runs `alembic upgrade head` before `run`.

DATABASE_URL should point at a local Postgres on localhost:5432
for validation. Save it as a regular env var, not a secret.

For a full walkthrough of the Project Setup chat flow, the panel sections, and validation states, see Lifecycle Setup.

Knowledge Chat

Knowledge chat is the chat panel on the right side of the Project Knowledge drawer. It is your primary way to interact with when working with project knowledge — onboarding, Project Spec review, lifecycle changes, wiki and rule management all happen here.

Sessions

Knowledge chat supports multiple sessions. Use the session picker at the top of the chat panel to switch between existing conversations or start a New chat. Each session keeps its own history, so you can have separate threads for different topics (lifecycle tuning, architecture decisions, rule changes) without losing context. Sessions may show which daemon they are running on (displayed as ”· on <daemon>” next to the session name).

Preparing and warmup

When you open Knowledge chat, may need a moment to prepare a sandbox on the daemon — allocating a workspace, cloning the repository, installing dependencies, and indexing the codebase. This warmup happens automatically and you can see its progress in the chat panel. After the first warmup, subsequent opens are faster because the environment is already cached.

Session locking

Only one user can actively control a Knowledge chat session at a time. If a teammate already has an active session, you see a message naming the user who holds the lock. The session unlocks when that user finishes or their session times out after inactivity. This prevents the agent from receiving conflicting instructions from multiple users at the same time. If you need to work in Knowledge chat while a teammate holds the lock, coordinate with them directly.

Exclusive access and moving workers

Sometimes a Knowledge chat session needs exclusive access to the application process on the daemon (for example, to run lifecycle commands). If another job is already using that access on the same worker, your chat is parked — it waits for the other job to finish. If the pool has another available daemon, offers a Move to a free worker option so your chat can continue on a different daemon without waiting.

Pool capacity

Knowledge chat is exempt from the daemon pool execution capacity gate. You can start a Knowledge chat session even when all workers in the pool are busy with milestone or ad-hoc executions.

Adding Your Own Knowledge

You can add context at any time. This is useful when you have documentation, design decisions, or standards that should know about from the start.

When you add content, it isn’t stored as a single blob. breaks it down into structured wiki pages and rules, optimized for how agents consume it. A long design doc becomes focused, referenceable entries agents can query efficiently.

Using the Chat

Use the Knowledge chat panel to talk to and create, update, or reorganize knowledge. To add documentation:

Open Project Knowledge from the Roadmap (Modernization → Project Knowledge)
Open the chat panel if it is hidden
Describe what you want to add

For example:

We use the repository pattern for all database access.
Each entity has its own repository class that extends BaseRepository.
Repositories handle all SQL queries — services never write raw SQL.
Here's an example from our codebase:

class UserRepository(BaseRepository[User]):
    async def find_by_email(self, email: str) -> User | None:
        return await self.find_one({"email": email})

takes this and creates the appropriate wiki pages and rules so that every agent follows this pattern.

Dragging in Files

You can drag text files directly onto the chat panel to import existing documentation. reads the file, extracts the relevant knowledge, and creates wiki pages and rules from the imported content. Supported formats include .md, .mdx, .txt, .yaml, .json, .py, .ts, .js, and other common text-based formats (up to 1 MB per file). Example use cases:

Drag your team’s CONTRIBUTING.md to import coding standards
Drop an architecture decision record (ADR) to capture design choices
Import a styleguide.md to encode formatting preferences

From a URL or Repo Path

In the chat, you can also reference external sources:

Please read the coding standards from our wiki at
https://internal-wiki.example.com/coding-standards
and create rules from them.

Or point to a file in your repository:

Read the patterns in src/shared/base-repository.ts
and create a wiki page documenting the repository pattern we use.

Editing Wiki Pages

Wiki pages capture architecture, patterns, and project-specific context. Update them through the chat. Right-click any item in the tree (wiki, rule, milestone, Project Spec, etc.) and select Add to context to attach it to the chat. You can also select text in the content panel and use the same Add to context action. Then describe the change you want:

Add a section about connection pooling.
We use a max of 20 connections per service instance.

Create a new wiki page about our error handling strategy.
All domain errors should extend AppError. HTTP errors are mapped
in the error middleware, not in individual handlers.

On Project Spec, milestones, wikis, and rules you can also leave artifact comments on selected text — useful for team review before asking chat to apply changes.

When to Add Wiki Pages

Add wiki pages when you have knowledge that applies broadly but isn’t a hard rule:

Architecture decisions — “We chose event sourcing for the order service because…”
Integration notes — “The payment gateway expects ISO 8601 dates with timezone”
Migration context — “The legacy UserManager class maps to three separate services in the new architecture”
Patterns — “All API responses follow the envelope pattern: { data, meta, errors }”

Editing Rules

Rules are hard constraints that agents follow in every milestone. Unlike wiki pages (which provide context), rules are treated as requirements. Create and update rules through chat:

Create a rule: all Python files must use absolute imports.
No relative imports allowed except in __init__.py files.

Manage rules in the UI: select a rule in the tree to edit its content, change status (Draft → Published → Archived), or delete it. New rules start as Draft until you publish them — only Published rules apply to agent execution. To update an existing rule via chat, right-click it (or select text) and Add to context, then describe the change:

Update this rule to also require that every new endpoint
has at least one integration test.

Rules vs. Wiki Pages

	Rules	Wiki Pages
Agent behavior	Treated as requirements — agents must follow them	Treated as context — agents use them to inform decisions
Scope	Apply to every milestone (when published)	Referenced when relevant
Best for	Coding standards, library mandates, naming conventions	Architecture docs, design decisions, integration notes
Example	”Use pytest for all tests. No unittest."	"The authentication service uses JWT with RS256 signing.”

Use rules when you want to enforce something. Use wiki pages when you want to inform agents.

Editing Milestones

You can review milestone descriptions in Project Knowledge. To adjust scope, add requirements, or change descriptions, use Editing Milestones from the milestone review flow. You can also ask to restructure milestones through chat. For example, to merge two milestones:

Merge Milestone 3 ("Migrate user authentication") and
Milestone 4 ("Migrate session management") into a single milestone.
They're tightly coupled and should be done together.

Locked Milestones

Milestone plans in Project Knowledge are view-only once execution has started. A milestone is locked when its status is anything other than Not Started — including in progress, pending review, failed, blocked, or merged. If you need to adjust a milestone that’s already executing, wait for the current execution to complete (or merge it), then make your changes before re-running.

For small, recurring adjustments across milestones, add a Rule instead of editing each milestone individually. Published rules apply to all milestones automatically.

Updating the Project Spec

The Project Spec is the top-level document that defines your migration’s goals, scope, and approach. Ask in chat to refine the migration direction; substantial changes may also go through your Project Spec approval flow (see Reviewing the Project Spec). Changes to the Project Spec can affect how agents approach future milestones, so be deliberate about what you request.

Viewing Changes

When modifies knowledge during an agent execution (for example, an agent discovers a pattern and writes a wiki page), you can see exactly what changed. Click Show changes (the diff icon) in the Project Knowledge toolbar to toggle an inline diff view:

Green highlights show added content
Red highlights with strikethrough show removed content
A summary shows the total lines added and removed
Modified items are marked with a status dot in the tree navigation

This makes it easy to review what agents learned and wrote back during execution. The button is disabled when there are no pending changes to show.

How Knowledge Stays in Sync

Project knowledge stays aligned with running work as agents read and write it, and as you add or update context through the chat. When you ask for changes while an agent is running, incorporates them so agents can pick up new rules and wiki context in subsequent steps.

Examples

Setting Up a New Project’s Knowledge

When you start a migration, front-load project knowledge with what you know:

Our project follows clean architecture. The layers are:
- Domain (entities, value objects, repository interfaces)
- Application (use cases, DTOs, application services)
- Infrastructure (database repos, external API clients, message handlers)
- Presentation (controllers, middleware, request/response models)

Dependencies point inward. Infrastructure depends on Domain,
never the reverse. Use dependency injection everywhere.

creates wiki pages for the architecture and rules for the dependency direction constraint.

Correcting Agent Behavior

After reviewing a PR, you notice agents are using console.log for debugging:

Create a rule: never use console.log in production code.
Use the logger service from src/shared/logger.ts for all logging.
Debug logs should use logger.debug(), errors should use logger.error()
with the full error object.

All future milestones follow this rule once you publish it.

Importing Team Standards

Your team has a docs/coding-standards.md in the repo:

Drag the file onto the Knowledge chat panel
reads it and creates wiki pages and draft rules from the content
Review the created entries in the tree navigation
Publish rules you want enforced, and ask the chat to adjust any entries that need refinement

Adding Context Mid-Migration

At Milestone 4, you realize agents don’t know about a critical integration:

The user service calls the billing service over gRPC.
The proto files are in shared/proto/billing.proto.
When migrating user-related code, preserve all billing
service calls and use the generated Python client from
shared/generated/billing_pb2_grpc.py.

Milestones 5 onwards now have this context.

Best Practices

Let the Chat Do the Structuring

Don’t worry about formatting your input perfectly. Describe what you want in natural language and structures it into the right wiki pages and rules. A rough paragraph of context works better than trying to manually create the “right” wiki page.

Review Agent-Created Knowledge

After each milestone, open Project Knowledge and check for new wiki entries and draft rules. Agents write back what they learned. If something is inaccurate, ask the chat to correct or remove it before the next milestone picks it up.

Use Rules for Enforcement, Wikis for Context

If you find yourself writing a wiki page that says “always do X” — that’s a rule. Move it there so agents treat it as a hard requirement, not optional context.

Lifecycle Setup

Reference for lifecycle scripts, env vars, validation status, and re-validation

Validation Level

How High vs Low/Medium affects Project Setup onboarding

Organizational Knowledge

Import organizational knowledge from existing projects

Reviewing the Project Spec

Approve the Project Spec using Project Knowledge and chat

Creating Rules

Deep dive into writing effective rules with examples

Editing Milestones

How to adjust milestone scope and descriptions

Core Concepts

Morph terminology and mental model

​What Project Knowledge Is

​What’s Inside

​How Agents Use It

​Opening Project Knowledge

​Project Setup (Onboarding)

​How Project Setup flows through this drawer

​Lifecycle validation statuses

​Editing the lifecycle later

​Knowledge Chat

​Sessions

​Preparing and warmup

​Session locking

​Exclusive access and moving workers

​Pool capacity

​Adding Your Own Knowledge

​Using the Chat

​Dragging in Files

​From a URL or Repo Path

​Editing Wiki Pages

​When to Add Wiki Pages

​Editing Rules

​Rules vs. Wiki Pages

​Editing Milestones

​Locked Milestones

​Updating the Project Spec

​Viewing Changes

​How Knowledge Stays in Sync

​Examples

​Setting Up a New Project’s Knowledge

​Correcting Agent Behavior

​Importing Team Standards

​Adding Context Mid-Migration

​Best Practices

​Let the Chat Do the Structuring

​Review Agent-Created Knowledge

​Use Rules for Enforcement, Wikis for Context

​Related Docs

Lifecycle Setup

Validation Level

Organizational Knowledge

Reviewing the Project Spec

Creating Rules

Editing Milestones

Core Concepts

What Project Knowledge Is

What’s Inside

How Agents Use It

Opening Project Knowledge

Project Setup (Onboarding)

How Project Setup flows through this drawer

Lifecycle validation statuses

Editing the lifecycle later

Knowledge Chat

Sessions

Preparing and warmup

Session locking

Exclusive access and moving workers

Pool capacity

Adding Your Own Knowledge

Using the Chat

Dragging in Files

From a URL or Repo Path

Editing Wiki Pages

When to Add Wiki Pages

Editing Rules

Rules vs. Wiki Pages

Editing Milestones

Locked Milestones

Updating the Project Spec

Viewing Changes

How Knowledge Stays in Sync

Examples

Setting Up a New Project’s Knowledge

Correcting Agent Behavior

Importing Team Standards

Adding Context Mid-Migration

Best Practices

Let the Chat Do the Structuring

Review Agent-Created Knowledge

Use Rules for Enforcement, Wikis for Context

Related Docs