From 82bcdde043938524f00f900efe39efd15c5c3cac Mon Sep 17 00:00:00 2001 From: Alec Perkins Date: Mon, 26 Oct 2026 22:27:06 -0400 Subject: [PATCH] docs: add concept and V1 implementation plan Co-Authored-By: Claude Fable 5.1 --- docs/concept.md | 69 +++++++++++++++++ docs/plan.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 271 insertions(+) create mode 100644 docs/concept.md create mode 100644 docs/plan.md diff --git a/docs/concept.md b/docs/concept.md new file mode 100644 index 0000000..57b968f --- /dev/null +++ b/docs/concept.md @@ -0,0 +1,69 @@ + +Intent is an app for defining high level feature sets for projects that span one or more implementations. + +It's "GitHub for intent". Where tools like GitHub and Forgejo are for tracking the _how_, this tool tracks the _why_. Instead of files of code being the unit of collaboration, it's features. Users can create an issue that describes a problem or new desired functionality, discuss, and then create a new feature or link to an existing feature, with the necessary changes described. The history of the feature is tracked, so the decisions behind why something works the way it does can be known. + +This then feeds into the implementations, where one or more repositories of app or package implementations can be linked, and their compliance with the feature set tracked and organized. + +Data model: +Organization - higher level wrapper around multiple projects, collaborators +Project - root set of logically-associated problems +Issue - a pre-proposal, bug report, etc that can optionally be linked to an existing Feature, or used to create a new Feature (promoted to a Feature(status=active)), or not associated with any Feature, (status=open, rejected, accepted), a potential change to a feature +Feature - a free markdown description of a particular functional solution to a problem within a Project, with discussion (comments can be resolved, or converted to Issues), associated Issues, prototype files, documentation files, and associated Implementation status. Can have parent Features to create a hierarchy of any depth (and have independent statuses for V1). Have a stable ID to be referenced by Implementation changes and Issues, and a status. They also have a sequential revision number that Implementations can reference to catch up with the latest version of the Feature. (status=active, withdrawn, superseded) +Implementation - name and status (active, archived), a repository in any forgejo instance, one or more can be linked to the project and represent a particular implementation of the project, they have features associated, not necessarily all features (marked N/A for that implementation). Intent itself only links to a repo host elsewhere, it does not need to store the repo itself. It can provide links to implementation releases (V1.1). Each Implementation can be on a different Forgejo instance (assume the Forgejo already has the Intent instance onboarded once we get to V1.1, to start it's purely a URL to click on). Per feature × implementation status is one of: n/a, not started, in progress, shipped, retired, stamped with the feature revision number it applies to so it's clear if an Implementation has fallen behind. +CommentThread - hangs off specific lines in the Feature description, the general feature, a whole file, a specific coordinate of an image file, an Issue. Can be resolved (to collapse and hide) +User - basic user account, optionally linked to Organization as Team Member +Comment - a specific versioned comment from a User that's part of a CommentThread + +Feature history is like git history, each edit is a commit with notes explaining the change. They are edited directly by team members (as if commiting directly to main) - and edits can be tied to an Issue. To start, Implementation status is purely manual. The Intent data lives entirely within its own data store. + +For V1.1: after making changes to a feature, the user can optionally create issues back on the forgejo instance to do the implementation (optionally passing agent-specific instructions on top of links back to the Intent content). (Flow is mostly one-way, Intent -> Forgejo, but delivery status does propagate back to Intent via commit messages. Issues on Forgejo do not propagate back to Intent.) + +Users can authenticate using Forgejo, GitHub, Discord, or email (magic link) (and multiple of these by linking their auths together). System admin users can use password authentication (these users are separate from regular users and cannot act within projects). + + +Tenancy: multiple organizations and teams, potentially many public users +(just a few organizations to start and only a handful of projects and colalborators, at most dozens of users overall) + +Users of the Intent app DO NOT need accounts with the underlying Forgejo instances. (V1.1: only users with Forgejo access can set up the syncing with the target repositories etc, via a Forgejo service user + scoped token stored per org. All users can see the Implementation status, but the visibility of the Forgejo project's details propagates to Intent.) In V1 an Implementation is just a URL and Intent never calls the Forgejo API. + +Not needed for V1: notifications, search, public API or MCP, Forgejo issue creation, release links + +Organization and user structure imitates forgejo (does not sync data but a user linking a repo from forgejo requires an account on both, such as a service-user): +- Organization (can only be created by sysadmin for V1, requires specifying an owner User who can add additional team members, only owner-role can manage team members though they need to accept invite and can remove themselves) + - team members (Users who are either collaborators or owners of the org): one set of team members per org + - Project + - any team member with the org-level project-create grant (set by org owners) can create a project and becomes its owner + - team member can have project-owner permissions (admin actions like delete project, manage project members) and/or collaborator actions (accept issues, create and update features, create/link implementations and update statuses). Collaborator access is granted per project. + - org owners can add themselves to any org project as collaborators, and admin the project + - can allow open contribution from other non-team Users (Issue creation, comments) or restrict these to team members only + - may be completely private and only visible to project members (plus org owners), require auth so only logged-in users can see, or fully public so the world can see and browse (but only logged-in users can contribute/comment) +- Users + - can freely contribute to projects that allow open contributions (depending on those permissions) including comment on features and promote those comment threads to an Issue (original commenter or team member can do this, other users cannot) + - cannot create projects outside of an organization + +Front-end approach: Django + HTMX + Alpine to start with islands of rich interactivity where needed. +Styling: extremely minimal. Largely browser defaults; if the stylesheet failed to load the look-and-feel should not be drastically different (layout aside). Accessibility is key. Dark mode from the start. +Back-end: Django, Sqlite (Litestream), deployed onto Fly.io and using Tigris object store. Database backups to B2 +Local development: Docker (Fly uses Docker also) +Transactional email (magic links, invites): provider TBD. Console backend in development. + +Already have credentials for Fly and B2. + +See plan.md for the V1 implementation plan and the defaults chosen for details not covered here. + + + +For example: + +1. A general User creates a new Issue in a Project. +2. Multiple Users including team members discuss in comments on the Issue. +3. A Team Member decides to accept the Issue, which closes it to status=accepted, and the creates a new Feature and writes the description of it (the Feature is linked to the Issue it came from) +4. The Team Member then updates the status of the Feature manually to track with implementations +5. Later, a User starts a comment thread on a Feature. +6. After some Discussion, the User promotes the thread to an Issue. +7. More discussion, then a Team Member accepts the Issue and updates the Feature (manually for V1) + - or, a Team Member rejects the Issue and it's marked as rejected, but still linked to the Feature so others can see it was put forward and rejected + + + diff --git a/docs/plan.md b/docs/plan.md new file mode 100644 index 0000000..fe92ee1 --- /dev/null +++ b/docs/plan.md @@ -0,0 +1,202 @@ +# Intent V1 implementation plan + +Companion to [concept.md](concept.md). The concept says what Intent is; this says how V1 gets built, in what order, and which details were decided by default rather than in the concept. Where the two disagree, fix the concept first. + +## 1. V1 scope + +**In:** organizations, projects, features (markdown, revisions, hierarchy, files), issues, comment threads (feature, line, file, image coordinate, issue), implementations as plain URLs with per-feature manual status, auth via Forgejo/GitHub/Discord/magic link with account linking, sysadmin via Django admin, three project visibility levels, open contribution toggle, invites. + +**Out (V1.1 or later):** notifications, search, public API or MCP, Forgejo API access of any kind (issue creation, release links, visibility propagation, commit-trailer status), status inheritance through the feature hierarchy, real-time updates. + +## 2. Decisions and defaults + +Decisions made in the concept are not repeated. These fill the gaps. + +### Model + +| Topic | Default | +|---|---| +| Primary keys | Opaque, non-sequential: ULID stored as a 26-char string, generated in Python (`python-ulid`), set as `default` on a shared abstract base model. Never exposed as a sequence; used in URLs only where no human-readable key exists (files, file versions, threads, comments). | +| Feature stable ID | Human-facing, separate from the PK: per-project prefix + sequence, e.g. `AUTH-12`. Prefix is set on project creation, uppercase, 2–8 chars, unique within the org. Number never reused. | +| Issue ID | Per-project sequence `#N`, separate from feature numbers. | +| Feature revision | Integer starting at 1, incremented by every commit to the feature: description edit, file add/replace/remove, parent change, status change. Each revision stores the full description text (not a diff); diffs are computed on display. | +| Commit note | Required, short, free text. Optionally linked to one or more issues. | +| Issue ↔ feature | Many-to-many. An issue promoted from a comment thread is linked to that thread's feature. Accepting an issue that creates a feature links both. | +| Issue statuses | `open`, `accepted`, `rejected`, `withdrawn` (author closes), `duplicate` (links to another issue). Collaborators can reopen. | +| Feature statuses | `active`, `withdrawn`, `superseded` (requires `superseded_by` feature). | +| Implementation status | `active`, `archived`. | +| Feature × implementation status | `n/a`, `not_started`, `in_progress`, `shipped`, `retired`; stamped with the feature revision it applies to. Missing row displays as `not_started @ —`. If stamped revision < current revision, display "behind". | +| Hierarchy | Single optional parent within the same project. Cycles rejected. Moving a feature records a revision. Statuses independent in V1. | +| Files | Belong to a feature, typed `prototype` or `documentation`. Replacing a file creates a new file version and a feature revision; old versions stay (so old image-pin threads still resolve). Size cap 25 MB; allowed types: images, PDF, markdown/text, HTML, zip. | +| Line-anchored threads | Anchor = feature revision + start/end source line. On later revisions the thread shows as "outdated" with a link to the revision it was made on; no attempt to re-map lines. | +| Image threads | Anchor = file version + x/y as fractions (0–1). | +| Comments | Edits keep history (visible "edited" link). Author or project owner may delete; a deleted comment shows as a tombstone. Resolving a thread is allowed for the thread author or any collaborator. | +| Thread → issue | Original commenter or any team member. Thread gets `promoted_to` issue; issue body is prefilled with the thread text and links back. | +| Deleted users | Content remains, attributed to a "ghost" user. | +| Moderation | Project owners can delete comments and close issues in their project. Sysadmin can deactivate a user site-wide. | +| Invites | By email or existing username. Email invites create a pending invite, accepted via a signed link that also logs the user in (magic link). Expire after 14 days. The last org owner cannot be removed or demoted. | + +### Stack + +| Topic | Default | +|---|---| +| Runtime | Python 3.13, Django 5.2 LTS, `uv` for dependencies, `ruff` for lint/format. | +| Auth | `django-allauth`: GitHub, Discord, OpenID Connect provider configured per Forgejo instance (Forgejo supports OIDC), email login-by-code for magic links. Multiple social accounts per user via allauth's connect flow. | +| Sysadmins | Django `is_staff` users with passwords, Django admin at `/admin/`. A model constraint rejects staff users as org members. Regular users have no password (unusable). | +| Database | SQLite on a Fly volume. `transaction_mode = "IMMEDIATE"`, WAL mode, `busy_timeout` 5 s. Litestream replicates to B2 continuously. | +| Files | Tigris via `django-storages` S3 backend, private bucket, time-limited signed URLs. HTML prototypes are shown in a sandboxed `