Connect your organization’s GitHub or GitLab account, add a project’s repositories, and switch on what MySpec does with them:
| Feature | What it does |
|---|---|
| Track tasks automatically | Moves the project’s tasks as work lands. It links pull requests, commits and branches to their tasks, marks a task done when its work is merged, and keeps the review and CI labels up to date. |
| Brief pull requests | Posts one comment on each new pull request: what it does, the tasks it moves, and the spec text it touches, quoted word for word. |
Both features are switched on per repository and start off. Their AI usage is billed to your organization.
Who can do what
| Action | Who |
|---|---|
| Connect or disconnect a GitHub or GitLab account | Organization owners and admins |
| Add or remove a project’s repositories, switch a feature off, run a failed run again | Anyone with Admin on the project |
| Switch a feature on, choose its AI model, write its agent instructions | Organization owners and admins |
| See the project’s repositories and their switches, the run history and its transcripts | Everyone who can open the project’s settings |
Connect an account
An account is connected once for the whole organization. Every project in the organization can then add the repositories it reaches.
Open the Repositories settings
Open a project, then Settings → Repositories. Under Connected accounts, select Connect GitHub or Connect GitLab.
Read what MySpec asks for
A dialog lists what MySpec asks the provider for and what it sends to the AI model. Select Continue.
Approve on GitHub or GitLab
- GitHub: install the MySpec GitHub App on your account or organization and choose its repositories, then approve the authorization. You must own the GitHub organization you install it on. If you do not, the page says an owner must approve the installation: connect again once they have.
- GitLab (gitlab.com): approve MySpec’s access. MySpec acts as the account you connect with, so a dedicated bot or service account is recommended.
Back in MySpec
You return to the Repositories settings, and the account is listed under Connected accounts.
Changes you make on GitHub itself, such as which repositories the App can reach, also come back to MySpec. The page says what changed.
Add a repository
In the Repositories card, select Add repository, pick the account, search for the repository and add it. The card shows how many repositories the project has against its maximum.
- On GitLab, the connected account must be a Maintainer of the project, because MySpec adds a webhook to it.
- A repository can be added to several projects, and several organizations can connect the same repository through their own accounts. Each one only sees the events that reach it through its own account.
Switch a feature on
Each repository has its two switches. Select one to switch it on. A dialog asks first, and says:
- what the agent does, and that it reads the repository’s code (diffs and files) and sends it to the AI model;
- that the AI usage is billed to your organization;
- for briefs, who can read them, and who they are posted as.
Select Switch on to confirm. Switching a feature off is immediate.
Briefs and who can read them
A brief quotes your spec, and everyone who can read the pull request can read the brief.
- On a private repository, that can include collaborators and contractors with no access to the MySpec project.
- On a public or internal repository, you must tick an extra confirmation: anyone (public), everyone in your GitHub enterprise, or anyone signed in to GitLab (internal) can read the briefs.
On GitHub, briefs are posted by the MySpec GitHub App. On GitLab, they are posted as the account that connected. If that is a person’s account, the dialog warns you: comments show as theirs, and stop if they leave.
Choose the AI model
The AI models card sets the model each feature runs on, for all of the project’s repositories. An organization owner or admin picks a model for Track tasks automatically or Brief pull requests, or MySpec default, and selects Save next to it. You can choose before or after switching a feature on, and the choice applies from the next run.
Runs are billed at the chosen model’s price. If a model chosen earlier is no longer offered, the card says so, and runs use MySpec’s default until you choose another.
Give the agent instructions
The Agent instructions card tells each feature’s agent what this project needs, for example:
- Brief pull requests: “Write the summary in Japanese.”
- Track tasks automatically: “Never mark a task done from a push to a release branch.”
An organization owner or admin types the instructions for a feature and selects Save. They apply from the next run. Everyone else sees them read-only.
- Instructions are added after MySpec’s own rules and cannot change them: the agent still only moves tasks forward, quotes your spec word for word, and so on.
- They can be up to 2,000 characters. The card counts them as you type.
- To remove them, empty the box and select Save.
Run history
The Run history card lists what each feature’s agent did, newest first: each task tracking run and each pull request brief, with when it ran, its result, the model, the tokens used and how many times the agent read code. A run that failed before its agent started (for example, a brief that could not be prepared) is listed too, with its error. Select Refresh to see new runs, and Show older runs to go back.
Select View transcript on a run to see:
- the instructions the agent was given, the project’s included;
- the context it was given: the events and tasks for a tracking run, the pull request and spec excerpts for a brief;
- each time it read code: what it asked for (a pull request, a commit or a file) and how much came back, never the code itself;
- its notes after reading, and its answer.
A brief that ran again (after an edit or a reopen) lists its earlier runs: pick one in the Run list. Transcripts are kept for 30 days; an older run shows its result without one.
Run a failed run again
A run can fail, for example when the AI model is briefly unavailable. Anyone with Admin on the project sees Run again on a failed run.
- A task tracking run runs again on the same events. Events that a later run already read stay with that run.
- A pull request brief runs again on the same commit, and edits the same comment.
- The failed attempt’s error and transcript are removed. The run shows as Running (a brief as Queued, then Running) until it ends. While it runs, it cannot run again.
- The new run uses the AI model and is billed like any other run, and counts toward the project’s daily limit. If the project already reached its daily limit or your organization’s AI quota, the run is skipped, and its events wait for a later run.
Run again is refused when another task tracking run of the project is in progress, when the feature is switched off, or when later runs already read all of the run’s events (or they were removed, or tracking is off for their repository). Task tracking runs that failed before this was available can’t run again.
What task tracking does
MySpec collects the repository’s events as they happen: pushes, pull requests, reviews and CI results. A few minutes later, the agent reads the new ones together and decides which tasks they are about.
- It only moves tasks forward: from Pending to In progress, and to Done once the work is merged into, or pushed to, the default branch. It never touches a task that is already done.
- A task key such as
T012in a branch name, a pull request title or a commit message helps it match the work to the task. - It assigns a task only when it is unassigned, and only to a member of your organization who can open the project and signs in to MySpec with the author’s GitHub or GitLab account.
- It only counts activity from members of the repository. Pull requests from forks, from people outside it and from bots are ignored.
- People win. It never overwrites a change a person made, and never redoes a change a person reverted.
On the task board
- A card shows its open pull or merge request, for example #42 or !12, colored by its state.
- The agent manages three labels and never touches any other:
| Label | Means |
|---|---|
in-review |
The linked pull request is open and ready for review (not a draft). |
changes-requested |
A reviewer’s latest review asks for changes. |
ci-failing |
A CI check failed on the pull request’s latest commit. |
All three go once the pull request is merged or closed.
- A task’s details list its Links: pull requests, commits and branches. Anyone who can edit the task can remove a link; the agent never adds it back.
- Activity, in a task’s details, lists what the agent changed and why, with links to the evidence. Select Revert to undo a change. A revert is refused when someone changed that field since: a person’s later edit is never undone.
What a brief contains
A brief is posted when a pull request is opened (not as a draft), marked ready for review, or reopened, and written again when someone edits its title or description while it is open (an edit by a bot does not count). It is not rewritten on every push. Each pull request keeps a single brief comment: a later run edits it. An edit made while a brief is being written is not lost: the brief is written again once the current run ends.
- What the pull request does.
- The tasks it moves, linked to the project’s task board.
- The requirements and acceptance criteria it touches, quoted word for word from your spec files.
No brief is posted for pull requests from forks, from people outside the repository’s members, or from bots, or while the project is archived. Briefs are rate limited per project.
Your code and data
While a feature is on, MySpec sends repository text to the AI model: pull request titles and descriptions, commit messages, file paths, and the code its agent reads.
What MySpec keeps:
- Not kept: the code its agent reads (file contents and diffs), apart from short parts the agent may quote in its notes (see the run’s transcript).
- Kept for up to 30 days: the events it receives, including pull request titles and descriptions, commit messages, branch names, file paths, authors and links.
- Kept for 30 days: each run’s transcript: the instructions and context the agent was given, what it read (the file paths and commits it asked for, not their content), its notes and its answer. Everyone who can open the project’s settings can read them.
- Kept until changed or the project is deleted: each feature’s agent instructions.
- Kept as long as the task exists: the changes it made to your tasks, with their Links (including pull request titles) and Activity (what changed, why, and the links to the evidence).
Remove a repository or disconnect
- Remove a repository from a project: select Remove next to it. MySpec stops reading its events and writing briefs for it. Its tasks keep the links they have.
- Disconnect an account: under Connected accounts, select Disconnect. Every project in the organization loses the repositories it added through that account, with their switches. This cannot be undone. On GitHub, the MySpec GitHub App stays installed: uninstall it on GitHub if you no longer use it.
Troubleshooting
| You see | What to do |
|---|---|
| Suspended next to a GitHub account | The MySpec App is suspended on GitHub. Unsuspend it there, then connect again. |
| Uninstalled next to a GitHub account | The App was uninstalled on GitHub. Select Connect again to install it again. |
| Needs connecting again next to a GitLab account | GitLab refused MySpec’s access. An organization owner or admin selects Connect again. |
| Access lost next to a repository | MySpec can no longer reach the repository through its account. Give the account access again on GitHub or GitLab. |
| The connected GitLab account must be a Maintainer | Give the account the Maintainer role on the GitLab project, then add it again. |
| This connect link expired or was already used | Start connecting again from Settings → Repositories. |
| This model is not offered for repository features | Choose another model in the AI models card. |
| The instructions are too long, or hold characters that cannot be saved | Shorten the instructions to 2,000 characters, and remove any control characters pasted with them. |