redmine/PROJECT.md

---
tags:
  - projects
  - redmine
  - contacts
  - helpdesk
description: Legacy Redmine tooling and local plugin forks for reliable contact/search/helpdesk operations without requiring a risky platform-wide upgrade.
title: redmine
---
## Project rules
The following rules must be strictly adhered to when working on this project. Deviations from these rules are permitted only when the user explicitly requests or authorizes it.

### Understand the expectation of the user and what they are doing while you work
The user is expecting you to work continuously for long blocks of time, such as 20+ minutes minimum, during which time they plan to be away from the computer. They only intend to be highly-available at the outset of the work (during planning / clarifications), at the beginning/end of major milestones, or where, prior to starting a particular segment of work, you warn them you expect their involvement will be needed more often for some reason.

Keep this in mind when planning your work, and try to structure your work to meet the user's expectations about this.

#### For commands you need the user to run/approve, consider shell scripts
At the outset of work or the beginning of each phase, carefully think through what commands or file access you may need to perform, which is likely to require approval from the user. Also, think about any commands or file edits you will likely require, but would not be able to do yourself for some reason (e.g. you'd be tempted to instruct the user what to do, asking them to confirm results, instead of doing it yourself).

#### Best practices for handling these requirements

1. If a command will need to be run often, particularly with only slight variations, consider creating a temporary (project-specific) shell script or similar, which the user can approve once, and then you can use it repeatedly without needing more approvals.
2. If you will need to do something that requires limited root or sudo access, such as restarting a service or making edits to a root-owned file, do not plan on asking the user for approval each time. Instead, suggest the following:
	1. Ask for limited/scoped sudo access which doesn't require a password, and is limited to exactly the commands you'll need to run.
	2. Ask for a temporary change in file permissions so you can edit the file(s) without root access until the work is finished.
3. If working with remote hosts and ssh is available, do not plan on asking the user to shell into the remote host themselves and run commands on your behalf. Instead, suggest the creation and setup of a temporary ssh public key you can use that won't require a password each time you use it. Then, if the user agrees to that, verify you'll be able to connect via ssh without user assistance or approval for what you anticipate you'll need to do.
4. **Browser or similar tool isn't listening/running as expected**: If you need to use a tool like a web browser (like camofox or chrome with CDP) which seems like it should already be running and available to you, but when you try to use it, it doesn't work... try to solve that yourself without immediately running to the user for help. Valid solutions or troubleshooting for this consists of or should include:
	1. Try starting the thing yourself (like camofox or a browser)
	2. Check if an alternative method is available, and use it instead (e.g. you want to use Firecrawl, but the API connection doesn't work. For what you're trying to do, if camofox would work okay and it's available... just use that instead).

#### Avoid stopping mid-segment to ask for preferred implementation methods
During the course of work, you might run into situations where the project requirements could be implemented or understood more than one way. If that happens, your normal behavior tends to be stopping to ask the user which they would prefer, and presenting pros/cons. If you can, try to keep questions like that isolated to the outset of the work or the beginning/end of major milestones. The user should not be left with the impression you will busy yourself with work for 20+ minutes, so they leave and come back a half hour later, only to find that you stopped after 5 minutes to ask a question like this, especially not if you could have reasonably anticipated the question.

If an implementation detail like this arises unexpectedly, you should do the following if you can:

1. Choose the implementation path that is the lowest effort to _undo_ if it's not what the user wanted, and which has the lowest chance of turning into a "rabbit hole".

### Avoid "rabbit holes" or "wild goose chases"
Do not send the user on a quest of running various commands or actions to help you debug or test something, without first _thoroughly_ researching the likely causes of whatever problem has been encountered. 

As much as possible, do not tell the user what commands to run or what files to edit. Instead, run the commands or edit the files yourself, unless there is a prevailing reason you prefer to have the user run the commands or make the edits. Valid reasons to ask the user to make edits or run commands on your behalf include:

- File permissions or access controls prevent you from doing it yourself
- The user specified they want to be involved / run things on your behalf
- Taking action yourself would involve opening/reading files that are very likely to contain passwords, API keys, or other secrets.

#### What is meant by a "rabbit hole" or "wild goose chase"
During the course of the plan, you encounter an error message or maybe a command doesn't work the way you expected. You proceed to ask the user to troubleshoot the problem with you, by directing them to do things like run commands, reboot things, or change files. It becomes a back-and-forth with the user, where instead of progressing on the overall goals of the project, we become stuck on troubleshooting one thing for an extended period of time.

**Example of what a rabbit hole can look like:** A project being worked on includes 15+ different elements to the plan, one of which is setting up apache2 to properly act as a reverse proxy to serve opencode. You encounter an error that indicates opencode isn't working correctly, and then you start troubleshooting it by asking the user to run various commands, copy-pasting the results to you, making edits to various files, etc. The user isn't in a position to understand or estimate how much of this will actually be needed to get the problem fixed, so they continue working with you in this manner, when they had originally planned to go work on something unrelated for an hour, while you worked on this project. So, they keep going back and forth with you to troubleshoot this opencode problem, hoping with each turn, you'll finally be done asking them to run commands. Before the user realizes it, an hour and half have transpired, and the project really hasn't moved forward at all because we've been fixated on fussing with that one bullet point about opencode, instead of the wider project.

A chain of events similar to the above is what is meant by a "rabbit hole" or "wild goose chase".

### Maintain a PLAN.md and HANDOFF.md
The PLAN.md should begin with a short statement that explains the scope of the project we're working on, including _why_ we're working on it, and the expected timeframe it needs to be at a stopping point. The rest of the document should read like a checklist of project goals or milestones. As you work, you should update the PLAN.md to check off things as they are implemented.

If you realize a particular checklist item in the plan is likely to become a "rabbit hole", is overly broad, or the expected implementation didn't actually resolve it, do the following:

1. Edit the PLAN.md with one or more sub-points added, breaking the goal/task down into smaller steps or goals that are more achievable.
	1. If a decision is needed which the user isn't available for or has asked you to save for later, add making that decision as a task/goal of it's own.
	2. Create a separate Markdown file containing the context for what decision needs to be made and what the options are, and explicitly reference that file in the sub-point.
2. Move on to the next part of the plan you can actually complete.
3. To indicate statuses with the "[ ]" fields of the markdown, use the following:
	1. "x" : fully completed
	2. "~": partially completed
	3. "?": blocked until a decision is made or issue troubleshooted

#### HANDOFF.md
Each time you reach a major milestone with the project, update HANDOFF.md so that it reflects enough information that a different agent or worker could pick up where you left off. It should briefly explain:

1. Where to locate _this_ file.
2. Where to find the PLAN.md
3. The last 2-3 things you finished with the project.
4. The thing you were planning on doing next, and why.

### Use and update "global" docs and knowledge bases

Two different shared obsidian vaults exist, each with a different function. You should make liberal usage of them. The user may also have a private obsidian vault, named obsidian-private (but they might not).

- **obsidian-ldr**: Company knowledge-base about processes and standards, business practices, workplace rules or policies, employees or other contacts, etc.
	- Business policies or processes, service/product definitions or promotional materials
	- Workplace rules, best practices, SOPs, etc.
	- Records of key business decisions, clients, employees, vendors, etc.
- **configs**: Technical docs about systems, infrastructure, tools, or software the company uses or is planning. May include troubleshooting info, coding standards, etc.
	- Network configs, info about services available, etc.
	- List of projects being worked on and where to find them
	- Preferences about tooling, configs, fixtures, etc.
	- **When to add things to this vault:**
		- You changed a shared configuration on a company network or server
		- Setup or installed a new server/service
		- Started a new project
		- Learned a new fact about company systems or infrastructure not already documented within the vault
- *obsidian-private*: Notes and info that's personal or private to the user. It should/may contain information that's not useful to other people, is private to the user, or moderately sensitive.
	- **If it exists, typically used for:**
		- User's _personal_ preferences or opinions
		- Personal projects other people don't use
		- Personalized configs for various tools/systems
		- Personal schedules, todo lists, or journals
	- **Typical location:**
		- `~/obsidian-private`

#### Leverage the knowledge bases:
When something comes up you're not familiar with, and which plausibly seems to be related to company-specific jargon, methods, people, or similar, check the relevant vault before asking the user to explain what it is, and before you act on assumptions. Then, ask clarifying questions if needed.

If in the course of doing your work or asking the user questions, you learn things which seem like a future person/agent working on this or another project might also have questions about, _add what you learned to the appropriate vault_.

##### If unsure what to add or whether to add it, do the following:
Within the most appropriate vault's `INBOX` folder, create a markdown file (or using obsidian's tooling for this) named like YYYY-MM-projectName if it doesn't already exist. Then, append your input or observations to that file.

### Make liberal, appropriate use of delegation and background processes
You should have the ability to delegate work to sub-agents or even to opencode. Make intelligent use of these capabilities.
#### Here are some suggested uses for that:
- **Information Lookup**: When information might exist in multiple places, considering doing things like delegating one agent to check Obsidian and another to search the internet, then compare/contrast results to make a decision.

## If unclear where the project should live, make the home as follows
You might be provided instructions within a chat interface, or you might be pointed to a copy of this file somewhere on disk that isn't really a project folder. For instance, you might be pointed to this file within the INBOX section of an obsidian vault like `obsidian-ldr` or `configs`. In a case like this, you should do the following:

1. First, confirm with the user what this "project" is called, and whether it actually does have a "home" directory it should live within. If they say that it does, just use that. Otherwise, proceed with this list.
2. If the user is available, suggest 3-5 potential codenames for this project. Ask them to choose a name. Try to provide:
	1. 1-2 functional, boring, but descriptive names
	2. 1-3 creative, mythical, or narrative names
3. If the user isn't available, just pick a descriptive name for the project.
4. **Create and setup project directory:**
	1. Convert the selected name to kebab-case or camel-case.
	2. Within the user's `~/projects/` directory, create a directory for the project using the converted project name.
	3. Within that directory:
		1. Place a copy of this file inside of that project, and name it PROJECT.md.
		2. Create a README.md within that directory, and add a succinct description to the top which summarizes the scope/purpose of the project.
		3. Initialize the project directory as a git repository.
	4. **If `goto` is available, add the project to it**
		1. Check if the shell command `goto` is available. If it is, add the project to goto.
5. **Add it to the project index in `configs`**:
	1. Within the `configs` Obsidian vault, check inside of `projects/` for a markdown article about this project. If one does not exist, create it.
	2. Within that file, include a short section that explains where the actual project directory is, and a basic gist (very short) explaining what the project is (scope, problem it solves, etc).

### Troubleshooting

#### Obsidian vault not found or not working
If the vault isn't found, try the following:
- If `goto` is available, run `goto list` to see if it locates it
- Check these paths:
	- `~/projects/` : for instance, `~/projects/obsidian-ldr` or `~/projects/configs`

If the vault isn't "working", consider how you're trying to access it:

- If you're using an MCP tool, that tool might be connected to the wrong vault, or it my rely on the obsidian GUI to be running.
- Check to see if one of the following methods will work, and if so, use one of these. Raise the issue about the vault not working correctly _after_ you reach the next project milestone.
	- obsidian cli
	- Usage of `fd`, `rg`, and similar shell commands

***
# Actual project instructions

The above information and rules govern how you should approach the following project. Below this section are the redmine-specific requirements.

## redmine project-specific requirements

- Project name is **redmine**.
- Project home is **`/home/jason/projects/redmine/`** (already exists; do not relocate).
- Primary objective: safe operational tooling around legacy Redmine CRM/Helpdesk data so support, triage, and automation workflows can move faster without a platform rewrite.
- Prioritize `redmine_contacts.py` ergonomics for data-use outcomes:
  - filtering contacts by date/tag combinations for batch cleanup workflows,
  - full issue retrieval with helpdesk context,
  - precise, non-destructive contact updates (tags/custom fields).
- Maintain continuity docs in-repo:
  - `PLAN.md` (active checklist using `[x]`, `[~]`, `[?]`)
  - `HANDOFF.md` (last milestones + next step)
- Keep plugin source-of-truth in tracked `plugins/` paths. Do not treat ignored `redmine-copy/` as canonical source.
- Prefer dry-run/read-only validation where possible before mutating live-like test data.
- When documenting research or API feasibility, store findings in `docs/` with concrete route, method, auth, and risk notes.