Skip to content

Projects

Projects turn a build brief into a reviewable plan and then build the accepted artifacts in your workspace. Use a Project when a change spans several Resources, Fields, Policies, Roles, Workflows, Pages, or navigation menus and you want to inspect the design before anything is created.

A plan can also cover Components, layouts, and email layouts, so you can review how they fit the design, but Diagonal doesn't build those three yet — plan them here and create them in their own settings.

Plan a Project

  1. Open Projects and create a Project with a clear overview of the outcome.
  2. Add rules for requirements that apply across the build.
  3. Attach existing Projects or workspace artifacts when the plan must build on them.
  4. Start planning.

Planning runs in the background. The planner turns the overview into artifact tasks and records dependencies between them. A Project can be Draft, Planning, Planned, Building, Completed, or Archived.

Review before accepting

A planned Project isn't ready to build until its artifacts have been reviewed. Use the plan rail and schema view to inspect:

  • Resources, Fields, Relations, Policies, and sample Records;
  • Workflow triggers, inputs, steps, and callers;
  • Page behavior, Resource access, and workflow calls;
  • Roles, navigation, Components, layouts, and email layouts;
  • the build order and blockers between artifacts.

Mark each artifact reviewed only after its specification is clear. Use Ask about when the plan leaves an ambiguity. Incomplete review, dependency cycles, and invalid references block acceptance. An open question can leave its artifact unreviewed, but isn't a separate acceptance gate.

If the plan changes after review, affected artifacts can move to Needs re-review. Review the new version before accepting; an earlier review doesn't approve later changes.

Accept and build

Accepting the plan moves it into a buildable state. It doesn't take a snapshot: the build uses the plan as it stands when the build starts, and later edits move affected artifacts back to Needs re-review, which must be cleared before those artifacts build. Start the build after acceptance.

Diagonal builds independent artifacts together and waits for their blockers before starting dependent tasks. Resource structure is created before artifacts that use it; Pages and Workflows use the owning modules' normal validation and publishing rules.

Task states include Pending, In progress, Needs input, Done, Failed, and Skipped. A failed prerequisite prevents dependent work from starting. You can request a stop; running work finishes or stops at a safe boundary before the Project settles.

Work with existing artifacts

A task has a Create, Update, or Remove operation. Check this carefully when the workspace already contains similarly named artifacts. Existing schema and planned schema are shown separately so an intended update doesn't quietly become a duplicate create.

A Project build uses normal module rules:

  • Policies and permissions still govern data access.
  • Package-owned artifacts can reject changes their policy doesn't allow.
  • Resource and capability validation still applies.
  • Workflows and Pages follow their draft and publish lifecycle.

Write a useful brief

Name the people, data, decisions, and outcomes the application needs. Prefer “Members submit applications, staff review them, and approved members can access the directory” over a list of screen names.

State hard rules explicitly, such as:

  • applicants can see only their own application;
  • staff can add internal notes that applicants never see;
  • approval sends an email and grants the Member role;
  • the public directory includes only approved members who opted in.

The planner can derive artifact structure, but it shouldn't guess security or destructive behavior.

Troubleshooting

  • Plan can't be accepted: finish artifact review and resolve invalid or cyclic dependencies.
  • Artifact needs re-review: its specification changed after you reviewed it. Inspect the changes and review it again.
  • Build is waiting: one or more blocker tasks haven't completed.
  • Build failed: open the failed task for its validation or builder error. Fix the plan or workspace conflict before retrying.
  • Unexpected duplicate artifact: verify whether the task operation is Create or Update and attach the intended existing artifact as plan context.